IBKR 只读查询 Skill for OpenClaw

🔒 只读安全模式：此 Skill 仅能查询数据，无法执行任何交易操作。

通过 OpenClaw 在 Telegram 中直接查看你的 IBKR 持仓、余额和实时行情。

---

🔥 实际效果演示

---

📢 v2.0 架构升级：IB Gateway + ib_insync

2026-02-27 重大更新

为什么要升级？

v1.0 使用 Client Portal Gateway（HTTP REST API）+ Selenium 自动登录 的方案，在实际运行中暴露了严重的稳定性问题：

v2.0 新架构

用 IB Gateway（IBKR 官方桌面应用）+ ib_insync（Python socket API）替代了整套 HTTP 方案：

v1.0 (已弃用)                          v2.0 (当前)
┌──────────────┐                      ┌──────────────┐
│ Python 脚本   │                      │ Python 脚本   │
│ (requests)   │                      │ (ib_insync)  │
└──────┬───────┘                      └──────┬───────┘
       │ HTTP REST                           │ Socket (TCP)
       ▼                                     ▼
┌──────────────┐                      ┌──────────────┐
│ Client Portal│                      │  IB Gateway  │
│   Gateway    │                      │  (桌面应用)   │
│ (Java HTTP)  │                      │  Auto Restart│
└──────┬───────┘                      └──────┬───────┘
       │                                     │
       ▼                                     ▼
   IBKR 服务器                           IBKR 服务器

新旧对比

---

⚡ 一键安装（推荐）

直接把以下内容发送给你的 OpenClaw 机器人：

请帮我安装这个 Skill：https://github.com/liusai0820/ibkrclaw.git

安装完成后，请帮我配置 IB Gateway + ib_insync 环境。

---

📋 前置条件

---

🛠️ 安装步骤

第 1 步：安装依赖

# 安装 Java（如已安装可跳过）
brew install openjdk@17

# 创建工作目录和 Python 环境
mkdir -p ~/trading && cd ~/trading
python3 -m venv venv
source venv/bin/activate
pip install ib_insync requests

第 2 步：安装 IB Gateway

从 IBKR 官网下载 IB Gateway Stable 版本：

https://www.interactivebrokers.com/en/trading/ibgateway-stable.php

下载后双击 .dmg 安装到 Applications。

第 3 步：首次登录

1. 启动 IB Gateway（选择 IB API 模式）
2. 输入你的只读子账户用户名和密码
3. 在手机上批准 IBKR Key 2FA 通知

第 4 步：配置 API Settings

登录后进入 Configure → Settings → API：

然后进入 Configure → Settings → Lock and Exit：

第 5 步：配置环境变量

创建 ~/trading/.env：

IB_HOST=127.0.0.1
IB_PORT=4001
IB_CLIENT_ID=1

第 6 步：测试连接

cd ~/trading && source venv/bin/activate
python ibkr_readonly.py

应该能看到账户余额、持仓、行情等数据。

---

💬 在 OpenClaw / Telegram 中使用

安装并认证成功后，直接在 Telegram 中向 OpenClaw 机器人发送以下消息即可：

触发词：IBKR、分析公司、盈透、持仓、股价、行情、基本面、财报、投资建议

---

🔄 稳定性保障

IB Gateway Auto Restart

IB Gateway 自带 Auto Restart 功能，勾选后每周日（或自定义时间）自动重启，session 可连续运行一整周。这是 v1.0 Client Portal Gateway（24 小时过期）无法实现的。

ib_insync 自动重连

代码内置了断线自动重连逻辑，网络短暂中断后会自动恢复连接：

def on_disconnect():
    time.sleep(5)
    ib.connect(host, port, clientId=client_id, readonly=True)

ib.disconnectedEvent += on_disconnect

健康检查 + Telegram 通知

通过 keepalive.py（cron 每 5 分钟执行），监控 IB Gateway 进程和端口状态，异常时发送 Telegram 通知：

# Crontab
*/5 * * * * cd ~/trading && source venv/bin/activate && python keepalive.py >> ~/trading/keepalive.log 2>&1

需要手动介入的场景

---

🔧 功能说明

关于行情数据订阅

默认使用 免费延迟行情（15 分钟延迟），对于投研分析场景完全够用。如需实时行情，可在 IBKR 后台订阅市场数据包（非专业用户约 $10/月）。

💡 持仓市值和盈亏不受行情订阅影响——通过 ib.portfolio() 从 IB 服务器直接获取已计算好的数据，股票和期权均有。

---

📁 文件结构

ibkr-trader/
├── SKILL.md              # OpenClaw Skill 描述文件
├── README.md             # 本文档
├── scripts/
│   ├── setup.sh          # 安装脚本（部署 Python 环境）
│   ├── ibkr_readonly.py  # 核心只读查询客户端（ib_insync 版）
│   └── keepalive.py      # 健康检查脚本（进程/端口监控 + Telegram 通知）
└── references/
    └── ...               # 参考文档

部署后在 ~/trading/ 目录下的文件：

~/trading/
├── .env                  # IB Gateway 配置（端口、IP）
├── ibkr_readonly.py      # 核心查询脚本副本
├── keepalive.py          # 健康检查脚本副本
├── venv/                 # Python 虚拟环境（含 ib_insync）
├── keepalive.log         # 健康检查日志
├── tws_reader.py         # TWS 连接测试脚本（参考用）
└── clientportal/         # [已弃用] 旧版 Client Portal Gateway

---

🚨 故障排查

---

🔐 安全说明

• 连接层安全：代码中不包含任何下单、修改订单、取消订单的 API 调用
• 账户层安全：建议使用只读子账户，从 IBKR 层面杜绝交易权限（这是最根本的安全保障）
• 代码层安全：IBKRReadOnlyClient 类中没有任何写操作方法
• 为什么不勾选 Read-Only API：IB Gateway 的 Read-Only API 设置过于严格，会阻止历史持仓查询、Scanner 扫描等纯查询功能。安全性应通过账户权限控制，而非 API 层限制
• 凭证安全：.env 文件仅保存在本地，不会上传到任何服务器；v2.0 的 .env 只含端口配置，不再存储账号密码
• 源代码完全开源，可自行审查
• 即使有人要求下单，此 Skill 技术上无法执行

---

⚖️ 免责声明 (Disclaimer)

请在安装和使用此工具前仔细阅读：

1. 按"原样"提供：本工具代码完全开源且免费，按"原样"提供，不带任何明示或暗示的保证。
2. 数据准确性风险：通过此工具查询到的持仓、余额、盈亏或行情及报价数据，可能因网络延迟、API 限制或代码逻辑问题而出现误差、未及时更新或根本错误。本工具的数据不能代替官方渠道（TWS 或 IBKR Mobile App），仅供一般性参考，请勿据此做出任何投资或交易的决定。
3. 资金安全责任自负：虽然我们在设计上将其限制为"只读"并强烈建议您通过"只读使用者账户"来使用，但在自行部署和提供凭证的过程中可能遇到的任何意外（如账号本身设置错误、服务器被黑等），作者概不负责。
4. 无责任担保：对于任何人因使用、无法使用、或依赖本工具提供的信息而导致的任何直接或间接的财务损失、利润损失或其他后果，工具作者不承担任何法律责任。使用本工具即代表您同意自行承担所有可能产生的风险。

---

📄 License

MIT License - 自由使用、修改和分发。