Windows 本地开发

Windows 本地开发是学习 TWS API 最直观的方式：TWS 界面在眼前，Python 程序连接本机 127.0.0.1，出错时可以同时看代码输出和 TWS 设置。

这一页只讲本地开发环境怎么搭起来。EClient、EWrapper、nextValidId 和回调模型已经在前面的 TWS API 入门页解释过，这里重点放在安装、端口、检查命令和常见问题。

推荐组合

项目	建议	说明
客户端	TWS	本地开发更适合用完整图形界面，方便确认设置和订单状态。
账户	Paper Account	新手先用模拟账户，避免误连真实资金。
连接地址	127.0.0.1	Python 程序和 TWS 在同一台 Windows 电脑上。
API 端口	7497	TWS 模拟账户常用端口，最终以 TWS 设置页为准。
Python 包	官方 ibapi	从 TWS API 包的 source\pythonclient 安装。
编辑器	VS Code / PyCharm / 终端均可	关键是确认运行代码的 Python 环境能导入 ibapi。

不要一开始就做远程连接、服务器部署或真实下单。先在本机用模拟账户跑通 currentTime，再进入合约、行情和订单预览。

准备步骤

1. 登录 TWS 模拟账户

先打开 TWS，登录 Paper Account。登录后确认界面里显示的是模拟账户，而不是 Live Account。

如果看不出当前账户类型，先不要运行下单示例。TWS API 代码只会连接当前登录的客户端，不能替你判断“这是不是你想连的账户”。

2. 开启 Socket API

在 TWS 中进入 API 设置页，确认：

设置	建议
Enable ActiveX and Socket Clients	勾选，允许 API 客户端连接。
Socket port	模拟账户常用 7497。
Read-Only API	初学阶段可先开启；需要测试 whatIf 或模拟订单时再按需求关闭。
Allow connections from localhost only	本机开发建议保持开启。

如果端口不是 7497，后面的代码和命令要改成你设置页里的实际端口。

3. 安装 TWS API Python 包

确认你已经下载并安装 TWS API 包。Windows 上官方示例常见目录是 C:\TWS API，但真实路径以你安装时选择的位置为准。

$ApiRoot = "<你的 TWS API 安装目录>"
cd "$ApiRoot\source\pythonclient"
py -m pip install .

安装后验证：

py -c "import ibapi; print(ibapi.__file__)"

能打印出 ibapi 路径，就说明当前 Python 可以找到官方 API 包。

最小连接测试

下面的测试只做一件事：连接本机 TWS，等待 nextValidId，然后请求服务器时间。

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


class LocalTimeApp(EWrapper, EClient):
    def __init__(self):
        EClient.__init__(self, self)

    def nextValidId(self, orderId: int):
        # 收到 nextValidId 表示 TWS 已经接受这个 API 客户端。
        # 这里再请求服务器时间，避免连接还没准备好就发请求。
        self.reqCurrentTime()

    def currentTime(self, time_: int):
        # time_ 是 IBKR 服务器时间的 Unix 时间戳。
        print("服务器时间:", time_)
        self.disconnect()

    def error(self, reqId, errorCode, errorString, advancedOrderRejectJson=""):
        # 连接状态、行情场状态和错误都会从这里输出。
        print("TWS 消息:", reqId, errorCode, errorString)


app = LocalTimeApp()

# 本机 TWS 使用 127.0.0.1。
# 7497 是 TWS 模拟账户常用端口；如果你的 TWS 设置不同，请改成实际端口。
# clientId 用来区分不同 API 客户端，同一时间不要和其他程序重复。
app.connect("127.0.0.1", 7497, clientId=1961)

# 启动消息循环，等待 TWS 回调。
app.run()

成功时会看到类似输出：

TWS 消息: -1 2104 市场数据场连接正常:usfarm
TWS 消息: -1 2106 历史市场数据场连接正常:ushmds
服务器时间: 1781286441

2104、2106 这类消息通常是连接状态信息，不一定是错误。只要最终收到 服务器时间，就说明本机 Socket 连接、TWS API 设置和 Python 回调链路已经可用。

保存成脚本运行

把上面的 Python 示例保存成 tws_current_time.py，然后在命令行运行：

py tws_current_time.py

参考输出：

TWS 消息: -1 2104 市场数据场连接正常:usfarm
TWS 消息: -1 2106 历史市场数据场连接正常:ushmds
服务器时间: 1781286441

如果你电脑上有多个 Python 版本，也可以把 py 换成你实际使用的 Python 路径。关键是运行这个脚本的 Python 必须能成功 import ibapi。

常见问题

现象	常见原因	处理方式
import ibapi 失败	没安装官方 Python client，或运行代码的 Python 不是安装时的 Python。	进入 <API安装目录>\source\pythonclient 后重新执行 py -m pip install .。
连接超时	TWS 没启动、端口不对、API Socket 没开启。	确认 TWS 已登录，API 设置页端口和代码一致。
没有 nextValidId	Socket 握手没完成，或 TWS 拒绝 API 客户端。	检查 Enable ActiveX and Socket Clients、端口、只允许本机连接。
有 2104 / 2106 消息	行情场或历史行情场状态消息。	只要后面的请求正常返回，通常不用当成错误处理。
多个程序互相影响	clientId 重复或订单 ID 序列冲突。	每个程序使用不同 clientId，订单章节再单独处理 orderId。
连接成功但没有行情	缺少行情权限、请求参数不对或数据类型不匹配。	先用历史 K 线或延迟行情验证，再排查实时行情权限。

不要在本地开发阶段做这些事

• 不要把 TWS API 端口开放到公网。
• 不要在还没确认账户类型时运行真实下单代码。
• 不要把账号、资产、订单编号和日志截图直接发到公开页面。
• 不要同时运行多个使用相同 clientId 的测试程序。
• 不要把 2104、2106 这类状态消息直接当成失败。

官方依据

官方 TWS API 文档说明，TWS API 需要连接已经运行的 TWS 或 IB Gateway，并通过 Socket 端口通信；Windows 用户需要安装官方 TWS API 包，Python 示例依赖 source\pythonclient 中的官方 ibapi。官方连接示例也强调应等待 nextValidId 后再开始发送需要连接状态的请求。