要求

开始写 TWS API 程序前，先确认运行环境已经准备好。TWS API 不是单独连到 IBKR 云端的接口，它依赖开发机或服务器上已经登录的 Trader Workstation（TWS） 或 IB Gateway。

最小可用环境

如果只是做桌面开发和模拟账户测试，最小环境是：

项目	推荐值	说明
账户	Paper Account	新手先用模拟账户，避免误下真实订单。
客户端	TWS	Windows 桌面开发更直观，方便看界面和订单状态。
API 端口	`7497`	TWS 模拟账户常用端口；真实账户常见为 `7496`，以 TWS 设置为准。
连接地址	`127.0.0.1`	程序和 TWS 在同一台电脑上运行时使用。
API 设置	启用 Socket clients	需要在 TWS 设置中开启 API 连接。
Python 包	`ibapi`	Python 示例使用官方 TWS API Python 包。

这套环境能完成连接测试、服务器时间、合约查询、账户摘要、历史行情和模拟订单预览等基础验证。

最小环境只代表“可以开始开发”，不代表所有行情、逐笔数据、新闻、期权 Greeks、市场深度或订单类型都可用。后面每个接口页都会把“连接要求”和“权限要求”分开说明。

至少安装并运行一个：

新手建议先用 TWS。TWS 有完整界面，能直接看到订单窗口、风险提示、连接状态、行情权限提示和 API 设置。等脚本、日志和错误处理流程稳定后，再把服务器部署切到 IB Gateway。

Python 代码需要能导入这些模块：

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

如果导入失败，说明还没有安装官方 TWS API Python 包，或运行脚本的 Python 环境不是你安装包时使用的那个环境。

验证方式：

python -c "from ibapi.client import EClient; from ibapi.wrapper import EWrapper; print('ibapi ok')"

如果电脑里有多个 Python，重点检查“运行脚本的 Python”和“安装 ibapi 的 Python”是不是同一个。Windows 上尤其容易出现命令行能导入、IDE 里不能导入，或反过来的情况。

Paper Account 可以用于多数开发测试，但它不是完整真实市场环境：

模拟账户适合验证：

能连接 TWS API 不代表一定能拿到实时行情。实时行情、延迟行情、历史行情都可能受到订阅、交易权限和交易所规则影响。

行情相关页面会单独解释：

开发时建议这样判断：

现象	常见原因	处理方式
能连接，但 `reqMktData()` 没有实时价格	没有对应交易所实时行情订阅	先尝试延迟行情，或检查 Client Portal 中的行情订阅。
逐笔数据返回权限错误	逐笔数据权限比普通 L1 行情更严格	在文档和程序里允许这种错误，不要把它当代码必然失败。
历史 K 线能返回，实时行情不能返回	历史数据和实时数据权限并不完全等价	分别测试 `reqHistoricalData()` 和 `reqMktData()`。
某些字段为 `-1` 或空值	该数据源没有提供、账户无权限或暂时无行情	在页面展示时标注“无数据”，不要直接当作 0。

提交订单前，账户必须有对应产品和地区的交易权限。程序侧也需要设置订单风险保护，尤其是：

先用 whatIf=True 做订单影响预览。
先在 Paper Account 中测试。
确认合约唯一，避免把同一个代码下到错误交易所或币种。
明确订单类型、价格、数量、有效期和是否允许盘前盘后。
读取 openOrder()、orderStatus()、execDetails() 和 error()，不要只看 placeOrder() 是否调用成功。

下单相关页面会默认使用小数量、限价单和模拟账户示例。真实账户自动化交易应该在业务系统里额外加白名单、价格保护、最大数量限制、撤单机制和日志审计。

默认情况下，本地开发只需要连接：

host = "127.0.0.1"
port = 7497

如果程序运行在另一台机器上，就属于远程连接，需要额外考虑：

不要把 TWS API 端口直接暴露到公网。即使是模拟账户，也应该按真实账户的安全标准处理。

桌面开发常见配置：

检查项	目标状态
TWS / IB Gateway 已启动	已登录账户，界面可用。
账户类型确认	使用的是 Paper Account 还是 Live Account。
API Socket 已启用	TWS 设置中允许 API 客户端连接。
端口确认	模拟账户常用 `7497`，真实账户常用 `7496`。
Python 能导入 `ibapi`	`from ibapi.client import EClient` 不报错。
能收到 `nextValidId`	表示 Socket 握手完成，可以继续请求。
能请求 `currentTime`	表示最小 API 请求链路可用。
行情权限已预期	没有权限时能看懂错误码，不把权限问题误判为代码错误。
下单保护已设置	下单前有合约确认、数量限制、限价保护和日志。

连接机制章节会使用 Python 连接脚本验证 nextValidId 和 currentTime，这样可以先确认 Socket 握手成功，再继续排查行情或订单问题。