安装与首次运行

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

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

canary 是一个 Go 二进制文件。它包含终端 CLI、本机 stdio MCP 服务器，以及保持与你自己的 IB Gateway 或 TWS 会话连接的背景守护进程（daemon）。没有任何部分是托管的，也不涉及 Python 或 Java 运行时。

开始之前

一个运行中并已登录的网关。 IB Gateway 10.37 或更新版本，或 TWS。模拟账户或真实账户都可以。
已在该应用程序中启用 API socket 访问，位置在 Global Configuration → API → Settings。没有启用的话，端口会接受 TCP 连接但永远不会完成握手。
一个 IBKR Pro 账户。 IBKR Lite 不包含 TWS API 访问。
macOS 或 Linux，arm64 或 amd64。 发布版本为这四种组合构建。
与网关同一部机器，除非你固定了 [gateway].host。探测只检查本机回环地址。
任何 IBKR 实体。 由 Interactive Brokers 香港、新加坡、日本、澳洲、爱尔兰、英国或 LLC 持有的账户，连接方式完全相同；香港及新加坡账户说明基础货币和交易所日历。

没有 Windows 版本。守护进程使用 setsid、flock 和 AF_UNIX socket，所以代码完全无法为 Windows 编译，而安装程序在侦测到 MSYS、MinGW 或 Cygwin shell 时会停止并显示讯息。WSL 是 Windows 上的途径：在 WSL 内，uname 报告 Linux，普通的 Linux 安装方式即适用。

在 Linux 上，canary stop、canary restart 以及 canary update 之后的重启都从 /proc 读取进程身份，所以不需要 ps，在 Alpine 等 BusyBox 系统上也一样运作。Canary 向进程发送信号之前，会检查守护进程锁文件中的 PID 是否正在运行 canary daemon，对于无关或无法读取的进程会拒绝而不发送任何信号。通过 qemu-user 模拟在 arm64 主机上运行的 amd64 二进制文件会按其解释器被识别。其他模拟器，例如 Rosetta for Linux、FEX 或 box64，则不会：stop 会列出它所看到的命令并让守护进程继续运行，请自行用 kill 停止。

从 v3.26.2 或更早版本升级

如果你的应用程序使用含空格的路径，或者你运行独立的 HOME/XDG 配置文件，请先使用 canary update --no-restart。然后从应用程序原本的配置文件环境呼叫新安装的 canary restart。较旧的更新程序即使替换了文件，仍以自己的旧重启代码执行启用，所以其 --restart 无法套用这些修正。交易版本的用户应先通过现有的安装流程安装新的交易版本制品，再重启。

从 v3.26.3 起，应用程序生命周期命令在停止它之前会核对应用程序实际生效的 HOME、socket、设置和状态路径。不同或无法读取的配置文件环境会被拒绝而不停止任何进程；请使用应用程序原本的环境。相对的配置文件路径和相对的应用程序 --state-dir/--log 值需要改为绝对路径。带有自订环境或工作目录的自订 launchd 工作需要明确的监督程序管理；自动生命周期命令不会触碰它们。较旧的已存储监督程序复原记录没有配置文件身份：请从其原本的配置文件环境以 canary setup app 复原，而不是在目前环境下自动恢复。

选择安装方式

方式	做法	适用情况
Claude Desktop 套件	以 Claude Desktop 开启 `canary.mcpb`	Claude Desktop 是你唯一的主机。套件自带 macOS 和 Linux 二进制文件。
Shell 安装程序	`curl -fsSL https://raw.githubusercontent.com/osauer/canary/main/install.sh \| sh`	你想要一个供终端和每个 MCP 主机共用的二进制文件。
公开 Go 模块 / v2 CLI	`go install github.com/osauer/canary/v2/cmd/canary@latest`	你刻意要使用维护中的 v2 Go 系列。这不会安装产品 v3。
发布版 tarball	下载 `canary-vX.Y.Z-<os>-<arch>.tar.gz`，并对照 `SHA256SUMS` 核对	你手动核对下载文件，或安装到受管理的位置。
复制并构建	`make install GO_TAGS=""`	你正在开发这份代码。

纯 make install 和 make restart-daemon 使用此仓库的实验性交易版本默认值。传入 GO_TAGS="" 以保留标准的只读能力。

Claude Desktop 安装页面逐步讲解套件的安装。打包与发布描述每个制品包含什么。

产品 v3 及之后的版本使用已签名的安装程序、MCPB 或发布版 tarball。公开 Go 模块维持为 github.com/osauer/canary/v2：Go 会忽略该模块路径的根 v3 标签，所以 /v2/...@latest 会继续解析为最新的有效 v2 标签。这让现有的库用户和从源代码构建的 v2 安装留在其维护中的主要版本上，而不会无声地跨越产品边界。

目前源代码与已签名的发布版

文档和 MCP 探索目录跟随 main。FX 贡献和借出费用报表已包含在 v3.16.0 的已签名二进制文件和 MCPB 中。未来的命令和工具可能在已签名的发布版之前出现在这里。请核对你已安装的 canary --help 和最新发布版。

要以只读版本试用目前的源代码：

git clone https://github.com/osauer/canary.git
cd canary
make build GO_TAGS=""
./bin/canary --help

这会构建一个独立的可可执行文件；它不会取代已安装的 Canary。需要 Go、Make 以及仓库中宣告的版本。

Shell 安装程序做什么

侦测你的作业系统和架构，并拒绝 Darwin 或 Linux 上 arm64 或 amd64 以外的任何组合。
通过跟随 /releases/latest 的重定向解析最新发布版，所以它不会呼叫 API，也不可能触及速率限制。
下载 tarball、SHA256SUMS 和 SHA256SUMS.asc。从 v1.0.0 起，缺少签名会中止安装，而不会退回到只核对校验和的路径。
从已加标签的源代码树把发布版签名密钥导入一个临时密钥环，对照 D98426D48FED85EFA33904694D922A4F922B7D7D 核对其指纹，并核对签名。指纹或签名不符会中止。v1.0.0 及之后的版本需要 gpg。
核对 SHA-256 校验和。
在解压前列出压缩档内容。canary、LICENSE 和 README.md 以外的任何东西都会被拒绝，符号链接形式的 canary 也会被拒绝。
以 0755 模式把二进制文件安装到 ~/.local/bin，或者你设置了 CANARY_INSTALL_DIR 的话，安装到那里。
清除 macOS 的 com.apple.quarantine 属性，让 Gatekeeper 不会阻挡首次运行。
当 ~/.local/bin 不在 PATH 中时把它加入。对 Bash，它更新 .bashrc 和第一个存在的登录档（.bash_profile、.bash_login 或 .profile），若都不存在则建立 .bash_profile。对 Zsh，它更新 ${ZDOTDIR:-$HOME}/.zshrc；fish 使用 ${XDG_CONFIG_HOME:-$HOME/.config}/fish/config.fish；其他 shell 使用 .profile。之后请开启新的终端。自订的 CANARY_INSTALL_DIR 会把 shell 设置留给你处理。如果启动档无法写入，安装会继续并印出需要手动加入的那一行。当 PATH 上有较旧的可可执行文件优先时，安装程序会警告并显示已安装版本的绝对命令。
执行 canary version，如果已安装的二进制文件报告的版本与刚才取得的不同，则发出警告。

建议先阅读它：curl -fsSL https://raw.githubusercontent.com/osauer/canary/main/install.sh -o install.sh，然后 less install.sh，再 sh install.sh。

检查是否成功：`canary status`

canary status 是唯一值得记住的命令。它回答守护进程是否已启动、网关握手是否已完成、它连上了哪个端点和账户，以及哪个子系统仍在预热。

canary status

一个健康的安装会印出接近以下的内容。以下数值皆为虚构：

IBKR Gateway  READY

Session        DU0000000 via 127.0.0.1:4001 (tls=false, discovered), client 15
Market data    Live
Daemon         v1.0.0, up 30m42s
TWS            API server 178
Gateway setup  as expected · read 09:02
Executions     other-client fills not yet observed · check TWS Master API client
               ID is 15
SPX members    cache:2026-05-22, 503 names

第一行的标记是 READY、STARTING、ATTENTION 或 OFFLINE。Session 行上的 discovered 表示端口来自探测；pinned 表示它来自你的配置文件。数据农场、市场访问、背景工作、子系统、交易和数据品质的行只在有话要说时才出现，而 Next concern 行只在有事项时才出现。

Executions 行报告来自其他客户端的成交证据。在观察到一笔之前，即使 TWS 已正确设置，可见性仍未被证明。TWS 只向其主客户端报告手动输入或由其他 API 客户端输入的成交，所以执行成本报表和决策记分卡只有在你把 TWS 的 Global Configuration → API → Settings → Master API client ID 设为 Canary 的客户端 ID 之后才会看到它们；看到第一笔这类成交后，该行会显示 all clients (proven HH:MM)，而 canary status --json 在 executions 下带有相同的事实。

Market access 行是缺少 IBKR 市场数据订阅唯一会按名称显示的地方，而不是在每个需要该数据的功能中分别浮现：

Market access  SPX not subscribed (IBKR 354, seen 14:03, retry 14:33)

它列出网关拒绝了什么、何时拒绝，以及 Canary 何时会再次请求——IBKR 代码 354 表示账户未订阅该数据。没有任何东西会因此被关闭：列出的代码只表示此刻重新撷取会被拒绝，而持有缓存结果的功能会继续提供它。该行是一个 30 分钟窗口内的观察，不是你订阅权限的记录，所以窗口内没有任何功能请求过的代码永远不会出现，而数据农场故障也可能把你账户确实持有的代码放到那里。订阅在 IBKR Client Portal 管理，不在 Canary 内。

首次运行而没有开启任何 IBKR 应用程序时，标记是 OFFLINE，而 Last attempt 行说明守护进程发现了什么以及接下来该做什么。以下数值皆为虚构：

IBKR Gateway  OFFLINE

Session        auto-detect via 127.0.0.1 (tls=false), client 15
Market data    unavailable until connected
Daemon         v1.0.0, just started
TWS            not connected
Last attempt   no IBKR listener found on 127.0.0.1 ports [4001 4002 7496 7497]
               (probe timeout 200ms); no TWS / IB Gateway / IBKR Desktop process
               found — start one and Canary will reconnect automatically
Next concern   Broker data connection unavailable

  Daemon log: ~/.local/state/ibkr/ibkr-daemon.log

Last attempt 行是守护进程对其上一次连接尝试的判断，原文照印：没有运行中的 IBKR 应用程序、应用程序运行中但端口拒绝连接（附上要检查的设置，或要在 config.toml 中固定的 [gateway] 端口）、没有完成的握手，或者接受连接后又中断的端口。故障排除解释每一则讯息。Next concern 行保留守护进程的整体判断。

当守护进程尚未从网关得到判断时，status 会每 500 毫秒轮询一次，最多 25 秒后放弃，然后印出守护进程日志路径，以及在守护进程尚未说明握手为何停滞时印出 API 检查清单。网关未连接时，命令以 1 退出；canary status --json 在 verdict 下带有相同的判断，在 last_error 下带有连接错误，所以可在脚本中使用。

这一切都不需要配置文件。守护进程以每个 200 毫秒的逾时并行探测 4001（Gateway 真实）、4002（Gateway 模拟）、7496（TWS 真实）和 7497（TWS 模拟），按该顺序取第一个回应者，把其他的列为备选，从 managedAccounts 自动侦测账户，并使用客户端 ID 15。只有当你想固定某项设置时才建立 ~/.config/ibkr/config.toml；配置参考中的每个键都是可选的。

两件令人意外的事

守护进程会自行启动。 任何由守护进程支持的命令都会连接 Unix socket，而当 socket 不存在时，会在自己的会话中启动 canary daemon，最多等待 5 秒让它出现。你永远不需要手动启动它。一个守护进程同时服务 CLI 和每个 MCP 主机，所以它们共用一个网关连接和客户端 ID。当 15 分钟内没有客户端连接且没有进行中的背景工作时它会退出，由 [daemon].idle_timeout 控制。

首次市场广度构建大约需要 74 分钟。 标普 500 市场广度在本机由成分股的每日 K 线计算，因为 IBKR 不会在零售订阅中转发 S&P DJI 的广度指数。共用的历史数据限速器允许最初 60 个请求，然后以每秒 0.1 个的速度补充，所以其余 443 个名称在冷缓存上大约需要 74 分钟。这段期间没有任何东西坏了：canary status 显示 breadth:computing，而 Background 行显示 refreshing rolling SPX breadth。快照只有在覆盖率达到成分股数目的 80% 时才会发布；低于此值时，引擎保留它已撷取的各名称窗口，每 12 分钟重试一次，15 次后放弃，直到下一次收盘后更新。闲置计时器不会中断构建：市场广度计为背景工作，所以守护进程会保持运行，直到更新完成或重试预算用尽。之后的更新很快，而且缓存在重启后仍然保留。

文件放在哪里

路径	内容
`~/.local/bin/canary`	二进制文件，除非你设置了 `CANARY_INSTALL_DIR`
`~/.config/ibkr/config.toml`	可选的固定设置。默认不存在
`~/.config/ibkr/policies/`	安装程序从 Canary 默认值写入的政策档，每个都以 `Canary defaults, not yet reviewed` 开头：`rulebook-policy.toml`、`protection-policy.toml`、`opportunity-policy.toml` 和 `risk-policy.toml`，后者的资本数字是留给你填写的占位值，其 `[order_limits]` 载有每笔订单的上限。永不被取代：守护进程在下一次启动时先备份再就地迁移现有文件，并保留你写入的每项设置；见交易政策
`~/.local/state/ibkr/daemon.db`	守护进程拥有的状态：设置、日志记录、成分股、证据
`~/.local/state/ibkr/ibkr-daemon.log`	守护进程日志。有东西无法启动时第一个要看的地方
`~/.cache/ibkr/ibkr.sock`	守护进程 socket；设置了 `$XDG_RUNTIME_DIR` 时位于 `$XDG_RUNTIME_DIR/ibkr/`
`~/.cache/ibkr/`	缓存和更新暂存空间

XDG_CONFIG_HOME 重新定位 config.toml；XDG_STATE_HOME 重新定位守护进程状态和日志，而 XDG_CACHE_HOME 重新定位缓存和更新暂存空间。socket 在设置了 XDG_RUNTIME_DIR 时使用它，否则使用 HOME/.cache/ibkr，与 XDG_CACHE_HOME 无关。CANARY_CONFIG、CANARY_SOCKET 和 CANARY_LOG 各自覆盖对应的文件。

政策默认值维持在 HOME/.config/ibkr/policies 下，即使设置了 XDG_CONFIG_HOME 或 CANARY_CONFIG。规则手册、保护和机会政策在 [rulebook]、[auto_trade] 和 [opportunities] 中有明确的 policy_file 覆盖；风险宪章使用其固定的默认路径。更改设置路径不会重新定位政策。

下一步

在依赖对账、按结单推算的权益或 Canary Edge 之前，先在设置经纪商报表中设置共用的 IBKR 结单来源。然后在连接 MCP 主机中把智能体接到服务器。以港元、新加坡元或日元计的账户，请阅读香港及新加坡账户了解日历和简报的时间。以更新保持二进制文件为最新。在对它能向经纪商发送什么、不能发送什么作出任何假设之前，先阅读受约束的订单与交易版本。