确认安装结果

确认安装结果分两步：

先确认 Python 能导入 ibapi。
再确认这个 Python 能连接 TWS / IB Gateway，并收到最小回调。

第一步只验证 Python 环境，第二步才验证 TWS API Socket 连接。把这两步分开，排查会清楚很多。

第一步：确认能导入 ibapi

在你准备运行 TWS API 脚本的同一个 Python 环境里执行：

python -c "import sys, ibapi; print(sys.executable); print(ibapi.__file__)"

如果使用虚拟环境：

"D:\你的项目目录\.venv\Scripts\python.exe" -c "import sys, ibapi; print(sys.executable); print(ibapi.__file__)"

正常输出应包含两类信息：

D:\你的项目目录\.venv\Scripts\python.exe
D:\你的项目目录\.venv\lib\site-packages\ibapi\__init__.py

只要能打印出 ibapi.__file__，就说明这个 Python 可以找到官方 ibapi 包。

如果这里失败，先不要看 TWS 设置。import ibapi 失败发生在 Python 本地环境，还没开始连接 TWS。

第二步：请求服务器时间

导入成功后，可以用 reqCurrentTime() 做最小连接测试。它不需要行情权限，不下单，也不读取账户持仓，适合作为安装后的第一条 TWS API 验证。

from __future__ import annotations

import threading
import time

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


class TimeCheckApp(EWrapper, EClient):
    def __init__(self) -> None:
        EClient.__init__(self, self)
        self.connected_event = threading.Event()
        self.time_event = threading.Event()
        self.server_time: int | None = None
        self.messages: list[str] = []

    def nextValidId(self, orderId: int) -> None:
        # 收到 nextValidId 表示 TWS 已接受这个 API 客户端。
        self.connected_event.set()
        self.reqCurrentTime()

    def currentTime(self, time_: int) -> None:
        # time_ 是 IBKR 服务器时间的 Unix 时间戳。
        self.server_time = time_
        self.time_event.set()
        self.disconnect()

    def error(self, *args) -> None:
        # TWS 的连接状态、警告和错误都会进入这里。
        self.messages.append(" ".join(str(arg) for arg in args))


app = TimeCheckApp()

# TWS 模拟账户常用端口是 7497；如果你的设置页不同，请改成实际端口。
app.connect("127.0.0.1", 7497, clientId=910)

thread = threading.Thread(target=app.run, daemon=True)
thread.start()

if not app.connected_event.wait(8):
    print("没有收到 nextValidId，TWS 可能没有开启 API、端口不对或连接被拦截。")
    print("\n".join(app.messages))
    app.disconnect()
elif not app.time_event.wait(8):
    print("已经连接，但没有收到 currentTime。")
    print("\n".join(app.messages))
    app.disconnect()
else:
    time.sleep(0.2)
    print(f"TWS API OK: server_time={app.server_time}")

运行方式示例：

python time_check.py

或者使用明确的虚拟环境 Python：

"D:\你的项目目录\.venv\Scripts\python.exe" time_check.py

预期输出

如果 TWS 模拟账户使用 7497 端口，且 API 设置正确，请求服务器时间成功时通常会看到类似输出：

TWS API OK: server_time=1781289125

输出中的 server_time 是 IBKR 服务器时间戳，每次运行都会变化。你不需要得到同一个数字，只要能收到服务器时间，就说明：

检查项	通过含义
Python 能导入 `ibapi`	Python client 安装到了运行脚本的解释器。
收到 `nextValidId`	TWS / IB Gateway 接受了 API 客户端连接。
收到 `currentTime`	请求和回调链路已经跑通。

连接失败时先看哪里

现象	更可能的问题
`ModuleNotFoundError: No module named 'ibapi'`	Python 环境没装对，和 TWS 设置无关。
`Connection refused` 或连接超时	TWS / IB Gateway 没启动、端口不对，或 API 没开启。
没有 `nextValidId`	Socket 连接可能建立了，但 TWS 没接受客户端或消息循环没跑起来。
收到只读或订单相关警告	安装已经通过，后续要看 TWS API 设置和订单保护。
行情请求失败	安装和连接可能都没问题，通常要看行情权限、合约定义或请求参数。

通过后再继续

确认安装结果通过以后，再进入后续主题会更稳：

合约对象：确认 Contract 字段是否写对。
行情数据：确认行情权限、marketDataType 和订阅限制。
历史 K 线：确认 durationStr、barSizeSetting、whatToShow 和限频。
订单：先使用模拟账户和 whatIf 预览，再考虑真实下单。

不要把所有问题都归因于安装。安装只解决 Python 能不能加载 ibapi；真正的交易接口还会受到 TWS 设置、账户权限、市场权限和风控规则影响。

官方依据

IBKR TWS API Documentation：官方 Python client 安装流程完成后，需要确认运行脚本的解释器可以加载 API 包；TWS API 的最小连接检查通常通过连接 TWS / IB Gateway 后接收回调来完成。