故障排除

本页由 AI 模型译自英文原文，并自动转换为简体，尚未经母语人士审阅；与英文原文不一致时以英文版为准。阅读英文版

更新：2026-11-04 09:23 CET

症状、原因、修复。先从 canary status 开始：它印出四种判断之一（READY、STARTING、ATTENTION、OFFLINE），最多等待 25 秒让 API 握手完成，并在网关未连接时以 1 退出。对于缺失或降级的输入，执行 canary data health。

Gateway setup 行说某项设置不同

每次连接后数秒，守护进程会在一个独立的短暂连接上读取一次应用程序的 API 设置（与下文 --gateway-diagnostics 相同的读取），而 canary status 把结果印为 Gateway setup 行。as expected 表示 Canary 依赖的每项设置都符合所需。否则该行会为每个差异带一个短句，各自按 TWS 或 IB Gateway 的标签命名该设置，并说明它对你的代价：

Gateway setup  Master API client ID is not 15: orders and fills from TWS or
               other apps stay unseen. · read 08:36
               Open orders are not downloaded at connect: orders placed
               elsewhere stay unseen.

它检查的设置，除另有说明外都在 Configure → Settings → API → Settings： Read-Only API（当 [trading].mode 是 paper 或 live 时必须关闭）、Master API client ID（Canary 的客户端 ID）、Download open orders on connection （开启）、Reject messages above maximum allowed message rate（关闭：开启时三次拒绝就会切断会话）、守护进程连接回环地址时的受信任 IP 清单（Allow connections from localhost only 开启，或 127.0.0.1 受信任；否则每次重新连接都要等待一次点击）、API 日志等级（Detail 增长很快）和 Include market data in API log file（关闭），以及 Lock and Exit 下的每日 Auto restart（登出会让 Gateway 处于已登出状态）。经纪商没有报告的设置不算差异。not read yet 表示读取尚未完成或无法进行；原因跟在后面。Canary 永不更改设置：请在应用程序中修正，该行会在下一次连接或 canary status --gateway-diagnostics 时更新。

IB Gateway 以加密方式写入其日志和配置文件（*.ibgzenc），而 IBKR 没有记载任何关闭此功能的设置。纯文字副本来自 Gateway 的 File 菜单（API Logs 或 Gateway Logs → Export Today Logs…）。Automatic Encryption 菜单项目与日志无关：它关乎 FIX CTCI 连接，在 API 模式下没有作用。

更改 TWS 或 Gateway 后检查 API 设置

执行 canary status --gateway-diagnostics（加上 --json 取得所有栏位）。正常连接维持其已测试的协议上限 203。诊断会对同一端点开启一个独立连接，协商至最高 219，读取 API 设置，并在五秒内关闭。它不会重启 TWS、更改端口、更新设置、绑定订单或向经纪商提交指示。

observed 表示经纪商回传了设置。unsupported 表示该会话无法协商所需的设置读取协议；请在 TWS 或 Gateway 中手动检查设置。unavailable 或 rejected 带有原因。省略的设置表示未报告，而不是关闭。协商得出的协议不是已安装应用程序的版本号。

输出包括只读 API 模式、自动下载未完成订单、重新连接时的订单保留、美股以手数计算成交量的模式、速率限制拒绝、主 API 客户端 ID、仅限本机模式及回环地址是否受信任（受信任 IP 清单本身永不保留）、API 讯息日志及其等级、已开启的订单预防措施绕过，以及应用程序所报告的 Lock and Exit 排程（按其自己的时钟；经纪商不发送时区）。这些都是观察，不是更改，也不是交易许可。成交量值保留经纪商的小数数量；Canary 不会按数值大小猜测是股数还是手数。保留的经纪商订单按身份对账；不确定的发送永不自动重放。

切换应用程序时，请把 Session 端点与所选应用程序中的 socket 端口比较。明确的 [gateway].port 固定值仍然具约束力：TWS 通常使用 7496/7497， Gateway 使用 4001/4002。在目标应用程序的登录、API socket 和设置准备好之前，保持使用正常运作的端点。设置诊断不会建立重启时区，也不会更改操作者宣告的重启排程。

Gateway 已就绪，但对账或 Edge 没有结单证据

Gateway API 访问与经纪商报表是分开的。新安装可以成功连接，而每个按结单支持的功能仍然是空的。请完成设置经纪商报表：建立八个区段的 XML Activity Flex Query，启用 Flex Web Service，并设置其 Query ID 和令牌文件。从 canary reporting status 开始诊断；它分辨本机文件、经纪商可达性、保留的证据、缺失的区段、存在但为空的区段，以及已证明缺失的栏位。

用稳定的原因选择下一步：

缺失的区段是没有回传；空的区段是回传了零行。两者都不能证明选择了哪些栏位。永远不要仅为填充报表区段而下单或调动现金。

每个命令都印出指向 canary status 的提示

一个命令失败了，而 CLI 附加了这段：

  hint: run `canary status` to see whether the daemon is still
        connecting (retry in a few seconds) or the gateway is
        down (start IB Gateway; check ~/.local/state/ibkr/ibkr-daemon.log).

每当守护进程的错误包含 gateway_unavailable，CLI 就会加上这三行。它表示守护进程已启动并在回应，而它背后的经纪商连接没有。

canary status 分辨这两种情况。STARTING 表示守护进程尚未发布连接错误，所以握手仍在进行中；等几秒后重新执行。OFFLINE 表示它已放弃并发布了原因，Last attempt 行会原文印出。

no IBKR listener found on 127.0.0.1 ports [4001 4002 7496 7497]

在每个端口 200 毫秒的预算内，四个标准端口（4001 Gateway 真实、4002 Gateway 模拟、7496 TWS 真实、7497 TWS 模拟）都没有回应 TCP 探测。讯息的其余部分告诉你属于哪种情况。

如果有 IBKR 应用程序在运行，错误会指出它和它的 PID。对于 TWS 和 IBKR Desktop，它列出从进程外部无法分辨的三个原因：Global Configuration → API → Settings 下的 'Enable ActiveX and Socket Clients' 未勾选、尚未完成的登录（2FA 或日终对话框），或非默认的 Socket 端口。IB Gateway 没有这个复选框——它的 API 永远开启——所以对 Gateway 讯息只指出余下的两个：它仍在启动（端口在登录完成后才开启），或者它在非默认的 Socket 端口上监听。那种情况请在 ~/.config/ibkr/config.toml 的 [gateway] 下固定端口。

如果没有应用程序在运行，讯息会这样说，并以 start one and Canary will reconnect automatically 结尾。它确实会。

探测只检查你设置中的主机，默认为 127.0.0.1。在另一部机器上的网关需要明确设置 host；它永远不会被探测找到。

accepts connections on 127.0.0.1:4001 and resets them before the API handshake

端口是开启的，但拥有它的进程在 API 握手交换任何一个字节之前就结束每个连接。探测的连接在 Canary 发送任何东西之前被关闭（FIN）或重设（RST），而守护进程自己的连接尝试会在连接时失败（connection reset by peer）、在第一个 socket 选项时失败（failed to set TCP_NODELAY: ... invalid argument）或在写入版本描述符时失败（broken pipe），取决于重设落在哪一步。Canary 把这些都报告为一种状态：canary status --json 在 gateway_phase 显示 port_rejecting，证据在 port_rejection 下，文字的 TWS 行陈述这个事实，而守护进程日志在每次变化时记录一次判断，而不是每个周期一个不同的 socket 错误。

讯息会指出拥有该端口的应用程序以及要在其中核对什么。对于没有 API 开关的 IB Gateway：登录和初始化已完成（2FA、每日自动重启、「existing session」对话框）、Gateway 窗口中没有等待中的连入连接提示，以及在 Configure → Settings → API → Settings 和 Precautions 下，Trusted IPs 涵盖守护进程的地址、其动作未设为拒绝，且 Socket 端口是被探测的那个。Gateway 前方的作业系统应用程序防火墙可以在 Gateway 看到连接之前，以同样方式重设已接受的连接（macOS：System Settings → Network → Firewall）。对于 TWS，'Enable ActiveX and Socket Clients' 复选框列在首位。

一个拒绝的端口仍然是候选。当另一个监听器保持其连接时——例如一个就绪的 TWS 旁边有一个会中断的 Gateway——守护进程会先尝试那一个。

not responding to TWS handshake within 12s

完整文字是 gateway HOST:PORT not responding to TWS handshake within 12s; check IB Gateway is running and 'Enable ActiveX and Socket Clients' is on。TCP 已连接而 API 握手没有得到回复，这几乎总是表示 API socket 被停用而不是不存在。

握手进行中时，canary status 印出相同的检查清单：

    Configure → Settings → API → Settings → 'Enable ActiveX and Socket Clients'
    Trusted IPs include 127.0.0.1 (or empty)
    Login fully completed (not paused at 2FA)

一则相关讯息 none of N discovered endpoint(s) completed TWS handshake (tried ...) 表示有几个应用程序接受了 TCP 而没有一个完成握手。它列出尝试过的每个端点，通常是一个过时的 Gateway 窗口连同一个刚登录的 TWS。退出你不想要的那个。

daemon socket did not appear within 5s

当 socket 不存在时，CLI 会自动启动 canary daemon，并给它 5 秒的预算到达其接受回圈。此讯息表示它没有做到，所以守护进程在启动期间崩溃或卡住了。

错误带有 CLI 能查明的资讯。当锁定持有者仍在运行时，它加上 daemon PID N holds PATH but never opened the socket 和 if it's stuck, run: kill N。当守护进程日志的最后一行可读时，它附上 last daemon log: ...。在终止任何东西之前，先阅读 ~/.local/state/ibkr/ibkr-daemon.log 的完整日志。

如果守护进程日志以关于 daemon authority、daemon.db 或预览密钥的 start: 行结尾，表示启动完整性检查失败，守护进程刻意保持停止；请依照 从失败的启动检查中复原。

守护进程在启动时因设置错误而停止

守护进程日志或 canary daemon 的输出显示 config ...: ... The [gateway] pins and [trading].mode decide which broker account Canary acts on。 Canary 无法读取决定经纪商账户的设置：文件本身、某个 [gateway] 固定值（host、port、account、client_id、tls）或 [trading].mode。当 [gateway] 或 [trading] 带有它不认识的键时它也会停止，因为那可能是拼错的固定值，或者固定值的名称放在了另一个区段。讯息会指出键和行号。在 ~/.config/ibkr/config.toml 中修正并执行 canary restart。

文件中任何其他无法读取的部分永远不会停止守护进程。它以 Canary 对该部分的默认值运行并如此说明：canary status 显示 config:degraded 并列出键，简报带有一行 config，警报收件匣有一则「Config file needs attention」通知。当 [trading]、[auto_trade] 或 [rulebook] 以默认值运行时，预先授权的保护提交会暂停；手动平仓、减仓和读取继续。修正文件并执行 canary restart 以清除。

第二个守护进程无法启动

这是刻意的。守护进程在触碰网关之前，会对 socket 旁边的 ibkr.lock 取得非阻塞的独占 flock。第二个守护进程发现锁被占用，记录 Another daemon is already running for socket PATH; exiting cleanly，并以 0 退出。

崩溃的守护进程遗留的 socket 文件也不是问题。新的守护进程会连接探测它：没有回应表示过时，会自动移除。锁被持有而仍有即时回应是不可能的情况，它会以 socket PATH already serving despite holding lock; refusing to evict 大声失败。

要刻意替换运行中的守护进程，使用 canary restart。它停止旧进程，从目前的二进制文件启动新进程，并报告网关健康状况。

CLI version X does not match daemon version Y

完整警告：

Canary: warning: CLI version X does not match daemon version Y — run `canary restart` to pick up the new binary.

你安装了新的二进制文件，而旧的守护进程仍驻留。执行 canary restart。

此检查对 canary status 跳过，而当任何一方标记为 dev 时它保持沉默，所以工作树不会每次运行都对自己发出警告。

报价显示 delayed、frozen 或 delayed-frozen

通常是正确的行为，不是故障。市场数据在你的 IBKR 市场数据订阅涵盖的地方是即时的，在没有涵盖的地方则是延迟的。

守护进程在每次连接时刻意向网关请求市场数据类型 2（支持冻结）：类型 1（纯即时）在收盘时可能让快照请求悬而未决，而类型 2 会改为回传最后已知的价格。如果你预期某个代码是 live 却得到 delayed，修复方法是在 IBKR 的账户管理中订阅市场数据，而不是在这里更改。

网关在冻结模式下只发送一次快照，永不串流。在 v3 中，请查看相关的持仓或应用程序行及其交易时段背景；独立的报价监看命令已经停用。

持有的名称在隔夜网关重设后停止更新

IBKR 的每夜重设可以让网关在一段时间内对所有东西回答「no security definition」，而在该窗口内被请求的名称会被标记为不活跃。这个标记是缓存而不是判断：它只存在于内存中，12 小时后过期，并在每次重新连接时从头重建。

守护进程也会记住那个回答，所以不会每次读取都再问一次。连接器会暂停重新解析该名称一分钟，倍增至 30 分钟，直到解析成功为止。报价的收盘背景保留拒绝 30 分钟。分配表在经纪商会话的余下时间保留它，而市场广度扫描会把该名称排除在外，直到下一个完成的交易时段。

所以修复方法是 canary restart。它重启守护进程并一次清除所有这些；单靠网关重新连接只会清除不活跃标记和分配备忘。另一个独立的 30 分钟重试窗口涵盖订阅权限拒绝，那是症状相同但不同的故障。

市场广度显示 0.0 %，或停留在 computing

冷的或仍在计算的引擎还没有读数。使用 canary status --json 和每日简报分辨 cold、computing、ready 和 degraded。

一个 ready 读数是某个特定交易时段的收盘值。简报保留该日期，并在它不再是最新完成的交易时段时标记为过时。守护进程继续提供最后良好值，而不会发布部分的替代值；canary status 带有子系统的原因和重试状态。

在新的守护进程上计算很长时间是预期的。IBKR 的历史数据限速把 503 个名称的展开限制在每分钟约 6 个名称，所以首次构建大约需要 74 分钟。一次成分股覆盖率低于 80% 的扫描不会发布任何东西，每 12 分钟重试一次，最多 15 次，这可能把等待时间拉长不少。之后状态退回 cold，由正常的每日一次更新接手，在官方交易时段收盘后 35 分钟进行。

Gamma 显示 no data yet (cold cache) 或 computing

两者都是状态而不是故障，两者都以 0 退出。只有 error 状态以 1 退出。

冷表示没有可用的结果，也没有东西在计算。守护进程在网关启动后预热 Gamma，并在美国期权常规交易时间内，于 15 分钟的软性 TTL 之后在已提供的值背后更新。在这些时间以外，自动更新根本不到期，所以非交易时间的冷缓存会刻意保持冷，而不是对已收盘的市场运行沉重的期权链展开。

canary status --json 和应用程序会显示计算中的状态、进度和类型化的故障，没有已停用的强制/不等待命令控制。

在美国期权常规交易时间内，SPY 或 SPX 上的 IBKR 354 会为该标的触发一次延迟重试。成功的结果在文字中显示 15m delayed，在 JSON 中带有 data_type: "delayed"。Canary 只在现货和期权模型的 tick 共用该延迟时钟时才接受它；它不会把延迟报价变成即时数据。如果延迟的期权模型 tick 也失败， Gamma 保持不可用，而错误仍会指出 IBKR 354。

以 canary feedback 报告错误

canary feedback --surface cli --error "the message you saw"

它印出一份简短的诊断报告和一个链接。链接开启 GitHub 上的错误报告表单，报告已填好；「Where did this happen?」下拉菜单是唯一要你自己选的栏位，因为 GitHub 不会从链接填写下拉菜单。在你阅读表单并提交之前，什么都不会发送。 --surface 指出它在哪里发生（cli、mcp、app、install），是要你选的选项；--error 是要包含的文字。报告带有 Canary 版本和构建、你的作业系统和架构、守护进程是否回应、网关种类和 API 服务器版本、作为来源覆盖率的数据健康摘要，以及经过遮蔽的错误文字：账户 ID、余额、持仓、订单参考、主机名称、用户名称和主目录路径都会被替换为方括号内的字词。它在没有守护进程运行时也能运作，而且不会启动任何守护进程；报告会如此说明。以 run `canary feedback` 结尾的错误讯息是 Canary 的缺陷，不是设置问题，而这就是它要求的步骤。通过 MCP 连接的 AI 助手以 canary_feedback 工具得到相同的报告。私密或涉及经纪商敏感资料的背景请改为以电子邮件 发送，而不是公开的 issue。

Claude Desktop 没有列出工具

完全退出 Claude Desktop 再重新开启。关闭窗口不等于退出，MCP 服务器只在真正重新启动时才会重新产生。这也是重新安装套件后人们遗漏的步骤。

canary setup claude-desktop 会把一个指向运行中二进制文件已验证绝对启动器路径的 mcpServers.canary 项目，写入 macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json。它会先备份任何现有设置。它拒绝覆盖不是有效 JSON 的文件，并印出路径让你修正或删除。连接 MCP 主机完整涵盖每个主机的接线。

如果工具仍然没有出现，阅读 Claude Desktop 自己的日志 ~/Library/Logs/Claude/mcp-server-canary.log。

MCPB 安装则不同：它带有自己嵌入的二进制文件，而 canary update 不会触碰它。更新涵盖重新安装套件。

日志和本机文件在哪里

守护进程日志是诊断串流，不是审计记录。开机时一旦超过 64 MiB 就会被移到 .1，并保留一代。撷取的框架和日志可能带有账户敏感资料；分享之前请先阅读 SECURITY.md。