如何启用 Debug 日志

Debug 日志用于让 TWS / IB Gateway 记录更详细的宿主平台行为。它和 API 日志里的 Logging Level = Detail 不是一回事：

项目	作用	典型入口
API 消息日志	记录 API 程序和 TWS / IB Gateway 之间的请求、回调、错误码	API -> Settings -> Create API message log file
API 日志级别	决定 API 消息日志记录得多详细	Logging Level = Detail 或 setServerLogLevel(5)
Debug 日志	让 TWS / IB Gateway 宿主平台记录更详细的诊断信息	修改 jts.ini，在 [Communication] 下设置 debug=1

新手排查 API 参数、错误码、订单回调时，通常先启用 API 消息日志就够了。只有在平台行为本身异常，或者 IBKR 支持要求提供更详细诊断时，才需要启用 Debug 日志。

什么时候需要 Debug 日志

适合启用 Debug 日志的情况：

• TWS 或 IB Gateway 自身出现异常、卡住、崩溃或登录状态异常。
• API 日志里能看到请求，但平台行为仍然无法解释。
• IBKR 支持人员明确要求启用 Debug 日志后重新复现。
• 同一个问题在不同版本的 TWS / IB Gateway 中表现不同。
• 连接、重新认证、断线恢复等问题无法只靠 API 错误码判断。

不建议长期打开 Debug 日志。它会增加日志量，也可能记录更多账户、合约、连接和界面上下文。排查结束后，应恢复默认配置。

官方 Debug 启用方式

官方说明的 Debug logging 启用方式是修改 TWS / IB Gateway 安装目录下的 jts.ini：

1. 退出 TWS 或 IB Gateway。
2. 进入 TWS / IB Gateway 的安装目录。
3. 找到 jts.ini。
4. 用文本编辑器打开它。
5. 在 [Communication] 段落下加入或修改：

[Communication]
debug=1

6. 保存文件。
7. 重新启动 TWS 或 IB Gateway。
8. 复现问题，并记录复现时间、账户类型、客户端类型和 clientId。

如果 jts.ini 里已经有 [Communication] 段，不要新建第二个同名段，直接在原段落里加 debug=1。如果不确定安装目录在哪里，先不要乱改文件；回到“Interactive Brokers 日志位置”和“下载 TWS 或 IB Gateway”相关页面确认目录。

Debug=1 还会带来什么

官方文档提到，在 TWS 中设置 debug=1 后，还会增加一些界面诊断能力。例如可以在观察列表行输入 conId|C 形式，让 TWS 把合约 ID 解析成合约；也会在合约描述窗口里显示更多合约细节，例如 conId、最小订单大小、市场规则、可用订单类型和可用交易所。

这些能力对排查合约定义、最小价格变动、订单类型可用性很有帮助，但它们不是普通交易界面必须开启的功能。只在排查或支持人员要求时使用即可。

和 setServerLogLevel 的区别

TWS API 里还有 setServerLogLevel(logLevel) 方法。它可以在 API 程序连接成功后调整服务端日志等级，常见数值含义如下：

数值	名称	中文解释
1	SYSTEM	系统级别信息
2	ERROR	错误信息，默认等级
3	WARNING	警告信息
4	INFORMATION	普通信息
5	DETAIL	更详细的信息

Python 示例：

# 连接成功后、复现问题前调用。
# app 通常是同时继承 EWrapper 和 EClient 的客户端实例。
app.setServerLogLevel(5)

这个方法适合临时提高 API 侧日志详细程度，但它不能替代 jts.ini 里的 debug=1。如果 IBKR 支持明确要求启用 Debug logging，应按 jts.ini 方式处理。

推荐排查顺序

1. 先打印程序里的 error()、connectionClosed()、nextValidId()、订单状态和关键请求参数。
2. 启用 API 消息日志，复现一次问题。
3. 如果 API 日志仍然不够判断，再把 API 日志级别设为 Detail。
4. 只有在平台级问题或支持人员要求时，再启用 debug=1。
5. 复现时只运行一个最小程序，固定 clientId。
6. 记录复现时间，导出或上传日志。
7. 排查完成后恢复保守配置，避免日志长期膨胀。

这套顺序能让日志量保持可控，也能避免把 API 参数问题误判成 TWS / IB Gateway 平台问题。

常见误区

误区	正确理解
Logging Level = Detail 就等于 Debug 日志	不等于。它主要影响 API / 平台日志详细程度；官方 Debug logging 是 jts.ini 的 debug=1。
setServerLogLevel(5) 可以解决连接失败	不能。它要在连接成功后调用，连接失败时先查端口、API 设置、登录状态和防火墙。
Debug 日志应该一直开着	不建议。它会增加日志量，也会记录更多敏感上下文。
改了 jts.ini 不用重启	需要重启 TWS / IB Gateway 后才会按新配置运行。
找不到 jts.ini 就随便新建一个	不建议。应先确认安装目录和正在运行的客户端。

官方依据

• IBKR TWS API Documentation：官方在 How To Enable Debug Logging 中说明，启用宿主平台 Debug 日志需要进入 TWS / IB Gateway 安装根目录，编辑 jts.ini，在 [Communication] 下加入 debug=1，然后重启平台。