TWS API 使用配置

这一步是所有 TWS API 开发的入口。Python、Java、C#、C++ 客户端都不是直接连 IBKR 云端，而是先连接开发机或服务器上已经登录的 TWS / IB Gateway，再由 TWS / IB Gateway 和 IBKR 后端通信。

官方位置：

File / 文件 -> Global Configuration / 全局配置 -> API -> Settings / 设置

必须确认的三项

TWS 字段	中文意思	新手建议	影响
Enable ActiveX and Socket Clients	启用 ActiveX 和 Socket 客户端	必须勾选	不勾选时，API 客户端无法建立 Socket 连接。
Read-Only API	只读 API	模拟账户测试可不勾选，真实账户建议先勾选	勾选后只能读取数据，不能通过 API 下单或改撤单。
Socket Port	Socket 端口	模拟账户常见为 `7497`，真实账户常见为 `7496`	Python 连接时必须填同一个端口。

只要这三项不对，后面的合约查询、行情、历史 K 线、账户、订单页面都会失败。

常用设置项说明

设置项	中文解释	建议
`Use negative numbers to bind automatic orders`	使用负数绑定自动委托单	普通新手可以先保持默认；涉及手动订单绑定、FA 或多客户端订单管理时再单独处理。
`Create API message log file`	创建 API 消息日志文件	排查连接、订单拒绝、字段格式错误时建议开启；长期运行要注意日志体积。
`Include market data in API log file`	API 日志中包含市场数据	只在排查行情字段时临时开启，实时行情多时日志会很大。
`Send API messages in English`	以英文发送 API 消息	建议开启。错误码和英文原文更方便搜索官方资料，也更方便 Agent 判断问题。
`Logging Level`	日志级别	日常用 `Error` 即可；排查连接或订单问题时再临时调高。
`Master API client ID`	主 API 客户端 ID	普通单客户端开发先留空；需要一个客户端接收所有订单状态时再配置。
`Timeout to send bulk data to API`	向 API 发送批量数据超时	一般保持默认；大量账户、持仓或历史数据返回慢时再调。
`Allow connections from localhost only`	仅允许本地主机连接	程序和 TWS 在同一台电脑上运行时建议勾选；跨机器连接必须理解网络和安全风险后再调整。
`Trusted IPs`	可信 IP 列表	只有关闭 localhost 限制、允许远程客户端连接时才需要配置。

场景	推荐配置
桌面学习和模拟账户测试	勾选 `Enable ActiveX and Socket Clients`，端口用 `7497`，保留 `Allow connections from localhost only`。
真实账户只读监控	勾选 `Read-Only API`，仅做行情、账户、持仓、订单状态读取。
服务器长期运行	更推荐 IB Gateway；如果必须用 TWS，需要处理每日自动重启和每周重新认证。
排查连接问题	临时开启 API 日志，并提高 `Logging Level`，排查完再恢复。

localhost only 是什么

Allow connections from localhost only 的意思是只允许同一台机器上的程序连接 TWS。

如果你在 Windows 上运行 TWS，并在同一台 Windows 上运行 Python，连接地址通常是：

127.0.0.1:7497

如果你的 Python 程序在另一台服务器上，而 TWS 在 Windows 电脑上，那么 localhost only 会阻止远程连接。长期方案通常不是直接暴露 Windows TWS，而是在服务器上运行 IB Gateway，或者用本地脚本把请求安全转发出去。

最小连通验证

配置完成后，不要一上来写复杂策略。先只验证三件事：

能连接到 127.0.0.1:7497。
能收到 nextValidId。
能请求并收到 currentTime。

nextValidId 很重要。端口打开只代表 TCP 可以连接，收到 nextValidId 才基本说明 TWS API 握手完成。

下面脚本只验证连接和 reqIds()，不会请求行情，也不会下单。代码中的注释保留中文，变量和 TWS API 方法名保持英文，方便对照官方接口。

from __future__ import annotations

import threading
import time

from ibapi.client import EClient
from ibapi.wrapper import EWrapper


class NextValidIdProbe(EWrapper, EClient):
    def __init__(self) -> None:
        EClient.__init__(self, self)
        self.first_id = threading.Event()
        self.second_id = threading.Event()
        self.ids: list[int] = []
        self.errors: list[tuple[int, int, str]] = []

    def nextValidId(self, orderId: int) -> None:
        # TWS 返回下一个可用订单 ID，收到它代表基础握手已经完成。
        self.ids.append(orderId)
        if len(self.ids) == 1:
            self.first_id.set()
        else:
            self.second_id.set()

    def error(self, reqId: int, *args) -> None:
        # 过滤常见连接状态提示，只保留真正需要排查的错误。
        if len(args) >= 3 and isinstance(args[0], int) and args[0] > 1_000_000_000_000:
            code = int(args[1])
            msg = str(args[2])
        elif len(args) >= 2:
            code = int(args[0])
            msg = str(args[1])
        else:
            code = -1
            msg = str(args)

        if code not in {2104, 2105, 2106, 2158}:
            self.errors.append((reqId, code, msg))


app = NextValidIdProbe()

try:
    app.connect("127.0.0.1", 7497, clientId=98200)
    thread = threading.Thread(target=app.run, daemon=True)
    thread.start()

    got_initial = app.first_id.wait(10)
    if got_initial:
        app.reqIds(-1)
    got_requested = app.second_id.wait(10)

    print(f"CONNECTED={got_initial}")
    print(f"INITIAL_NEXT_VALID_ID={app.ids[0] if app.ids else 'NONE'}")
    print(f"REQ_IDS_SENT={got_initial}")
    print(f"REQUESTED_NEXT_VALID_ID_RECEIVED={got_requested}")
    print("ALL_IDS=" + ",".join(str(item) for item in app.ids))
    print(f"NON_INFO_ERROR_COUNT={len(app.errors)}")

finally:
    app.disconnect()
    time.sleep(0.5)

一次正常输出通常类似：

CONNECTED=True
INITIAL_NEXT_VALID_ID=1
REQ_IDS_SENT=True
REQUESTED_NEXT_VALID_ID_RECEIVED=True
ALL_IDS=1,1
NON_INFO_ERROR_COUNT=0

字段含义：

输出字段	含义
`CONNECTED=True`	已收到第一次 `nextValidId()`，说明 Socket 握手完成。
`INITIAL_NEXT_VALID_ID`	TWS 自动返回的下一个可用订单 ID。
`REQ_IDS_SENT=True`	程序在连接成功后调用了 `reqIds(-1)`。
`REQUESTED_NEXT_VALID_ID_RECEIVED=True`	TWS 对 `reqIds(-1)` 再次返回了 `nextValidId()`。
`NON_INFO_ERROR_COUNT=0`	没有出现需要处理的非状态类错误。

常见错误判断

现象	通常原因
连接被拒绝	TWS 没有启动、端口不对，或没有勾选 `Enable ActiveX and Socket Clients`。
能连端口但没有 `nextValidId`	TWS 登录状态、API 连接确认弹窗、clientId 冲突或 API 设置仍未生效。
读取正常但订单失败	`Read-Only API` 仍然勾选，或订单风险提示没有处理。
远程服务器连不上 Windows TWS	`Allow connections from localhost only` 阻止了非同机连接。

设置检查项

完成设置后，重点检查下面几项：

检查项	推荐判断
`Enable ActiveX and Socket Clients`	必须勾选，否则 Socket API 无法连接。
`Read-Only API`	查询脚本可以勾选；需要模拟下单、改单、撤单时必须取消勾选。
`Socket Port`	Paper Account 常用 `7497`，Live Account 常用 `7496`，以 TWS 页面显示为准。
`Allow connections from localhost only`	同一台电脑开发建议保留；跨机器连接要单独配置网络和可信 IP。
`Send API messages in English`	建议勾选，方便搜索错误信息和对照官方文档。

如果使用真实账户，请只参考设置项含义，不要直接照搬模拟账户的风险设置。公开问题图片或录屏中不要展示真实账户、资产、持仓、订单号、真实 IP 和系统用户名。

官方依据

官方 TWS API 文档说明，TWS API 所需设置位于 Global Configuration -> API -> Settings，并强调至少要启用 ActiveX and Socket Clients、关闭 Read-Only API、确认 Socket Port。

IBKR TWS API Documentation