把 IB Paper 从零打通：端口、API 开关与第一次连上

IBKR 的模拟账户本身几分钟就能开通，真正耗时间的是中间那一段：桌面应用装了、API 开关点了、端口填了，软件还是连不上，或者连上了却没有行情、下不去单。这一篇按第一次搭建的顺序把这段路走一遍，并在最后给一张按症状查的表。

先说清楚一件事：下面所有步骤都在你自己的机器和账户上完成，不涉及任何"代配置"。

先把三个东西分清

新手最常混淆的是这三层，它们的故障表现完全不同：

• IBKR 桌面应用（TWS 或 IB Gateway）：负责登录、维持会话、把 API 请求转给 IBKR。它没有运行，你的软件永远连不上。
• 模拟账户（Paper）：IBKR 账户体系里的一个账户环境。它决定你连上的是哪一套余额、持仓和订单，而不是"是不是真钱"这么简单——实盘账户和模拟账户的端口、账户号、行情权限都可能不同。
• 你的交易软件：通过本地 socket 连到上面那层，然后自己管理订阅、合约、订单和对账。

接口文档里常说的"客户端"（client）指第三层。大量"连不上"的问题，答案其实在第一层或第二层。

准备工作

1. 有一个能登录 IBKR 的账户，并已开通模拟账户。多数情况下模拟账户随主账户自动提供；如果没有，在账户管理里创建。
2. 安装 TWS 或 IB Gateway，二选一即可。两者的差别我们在另一篇里写过：要看得见的界面选 TWS，要更轻的连接层选 IB Gateway。
3. 先用桌面应用手动登录一次，确认账户、余额、合约搜索都能用。这一步能挡掉很多"其实是账户或登录问题"的假故障。

打开 API 开关

IBKR 的桌面应用默认不接受外部连接，需要显式打开。位置大致是：

• TWS：File → Global Configuration → API → Settings
• IB Gateway：Configure → Settings → API → Settings

需要确认的项：

• Enable ActiveX and Socket Clients：必须勾上，否则 socket 端口根本不会监听。
• Socket Port：记下这个数字，后面填到软件里。默认值见下一节的表。
• Read-Only API：勾上时任何下单请求都会被拒绝。第一次调试建议先保持只读，确认能读账户和行情后再取消。
• Trusted IPs：只允许本机连接时可以留空或用 127.0.0.1；软件和桌面应用不在同一台机器上时才需要放行对端地址。

改完之后通常要重启桌面应用才生效。改完没重启、然后对着端口反复排查，是这一步最常见的浪费。

端口对照表

这张表值得单独背下来，因为它解释了一类很难察觉的错误：端口填错，未必连不上。把模拟端口换成实盘端口、而桌面应用正好登录着实盘账户，你会得到一个"连接成功"的实盘会话。所以只支持模拟交易的产品，必须在连接成功之后再核对账户本身，而不能只信端口。

第一次连接：主机、端口、客户端 ID

大多数桌面软件要填三项：

• 主机：软件与 IBKR 应用在同一台机器上时填 127.0.0.1；
• 端口：上表里的数字；
• 客户端 ID（clientId）：一个整数，用来区分不同的连接方。

客户端 ID 唯一性是硬约束。同一个 ID 已经被别的进程占用时，第二条连接会被拒绝，报错大意是 "client ID already in use"。这时不要反复重试，先找占用者：可能是上一次没退干净的进程，也可能是另一个同时开着的客户端。

软件里通常还有一个 只读（read-only） 开关，它和桌面应用里的只读设置是两回事：一个限制这层不发送订单，一个限制整个应用不接受订单。两个都开着时，"为什么下单被拒绝"的答案通常是后者。

连上了，但图表是空的

连接成功只说明会话建立，不说明你拿到了行情。三个常见原因，按出现频率排：

• 行情权限：API 连通不等于拿到全部实时行情。权限属于你的 IBKR 账户，模拟账户也受同样限制，取决于自己的订阅。切换桌面应用类型解决不了缺订阅。
• 延迟数据：没有实时订阅时，很多标的只能拿到延迟数据。图表的形态会和真实盘口有明显差别，回测里尤其不能拿它当实时样本。
• 合约没解析对：期货要精确到期月，期权要精确行权价与到期日，股票要确认交易所。只填一个代码，有时能解析出好几张合约，软件替你选了一张不一定是你想要的那张。稳妥的做法是先查合约详情拿到 conId，再把它固定下来。

连上不等于就绪

这是最容易吃亏的一段。socket 恢复、账户有余额、图表有数据，这三件事同时成立，仍然不代表可以开始交易。

一个更安全的顺序是：

连接恢复
        |
  同步账户
        |
  同步持仓
        |
 同步活动委托
        |
  确认行情
        |
 确认策略状态
        |
  允许新交易

原因很实际：重连之后，上一次会话里可能还有未结的委托、部分成交的订单、或者已经变成未归属的持仓。跳过对账直接放行，最典型的结果是重复下单和多出来的一笔"没人认领"的仓位。

每日重启：最容易被误判成"网络问题"

IBKR 的桌面应用有每日重启策略，通常发生在美东深夜。重启意味着 API 会话被断开，你的软件会看到一次"无缘无故的掉线"。

这带来两个具体要求：

• 重连必须是自动的，但对账不能自动跳过。 重连成功只是回到上面那个七步顺序的起点。
• 不要用"它自己会好"来安慰自己。 掉线本身不是问题，掉线期间委托状态发生变化才是问题。

如果你的软件没有把这两件事分开，表现就是每隔一天早上出现一次状态不一致，而且每次都发生在同一个时间点附近——这个特征本身就是线索。

排错对照表

如果用的是 Algoryn

前面的流程对所有客户端都成立，Algoryn 只多三步，且都发生在"连上之后"：

1. 确认账户是模拟账户。公开版本只支持模拟交易，不提供实盘；如果桌面应用登录的是实盘账户，连接会被拒绝，而不是悄悄降级。
2. 解锁自动交易权限。这是独立于连接的授权，默认是锁着的；重连后它需要重新解锁，不会自动继承。
3. 通过启动前的对账。持仓与活动委托核对完成后，实例才被允许启动；未归属的持仓必须先人工确认归属，或者先在 IB 端平掉。

这也是为什么我们在别处反复强调"连上不等于就绪"：这不是一句方法论，它是产品里真实存在的一道门。

一页清单

• 装好 TWS 或 IB Gateway，先手动登录一次。
• 勾选 Enable ActiveX and Socket Clients，记下端口。
• 对照端口表：TWS 7497、Gateway 4002（模拟）。
• 初调先开只读；确认能读再取消。
• 客户端 ID 保持唯一，冲突先找占用者。
• 先查行情订阅，再怀疑连接。
• 用 conId 固定合约，不要靠"看起来像"。
• 重连之后走一遍七步对账，别直接放行。
• 每日重启是常态，把它当成固定维护窗口。

Algoryn 是独立产品，并非由 Interactive Brokers LLC 关联、背书或赞助。本文涉及的应用界面与端口以你当前使用的 IBKR 版本和官方文档为准。