连接你的 AI 智能体

ACP 连接器是一个跑在你自己电脑上的小程序。它把你个人的 Claude 或 Codex 接到一个 Cheers 机器人上， 让它能读频道、看到你附加的文件、并回复——全程用你自己的智能体订阅。本文面向非开发者，带你走一遍：安装、连接、保持更新， 并解决那个最常见的意外。

1. 连接器是什么（30 秒版）

Cheers 本身不内置 AI。相反，你自带智能体，从你的电脑把它连进来。三个部件互相通信：

你的浏览器 ──▶ Cheers 网关（服务器） ◀──── 连接器（跑在你电脑上） ──▶ 你的 AI 智能体
                                          └ 一个配置文件 = 一个机器人

• 网关是你团队已经在跑的 Cheers 服务器。
• 连接器（cce-acp-connector）是你要安装并运行的小桥梁。
• 你的智能体是 Claude 或 Codex，用你自己的订阅登录——不需要额外的 API key。

一个配置文件描述一个机器人。想要两个机器人（比如一个 Claude、一个 Codex）？两个文件，跑两份，彼此完全独立。

2. 开始之前

就这些——你不需要 Rust、Docker，也不需要 API key。给智能体登录一次就够了。

3. 安装连接器

下载对应你系统的预编译二进制，无需任何工具链。把下面这段粘进终端：

# 自动挑选对应系统/CPU 的文件、下载、赋予可执行权限
os=$(uname -s | tr 'A-Z' 'a-z'); arch=$(uname -m | sed -e 's/x86_64/amd64/' -e 's/aarch64/arm64/')
mkdir -p ~/.cheers/bin ~/.cheers/workspace   # workspace 是智能体的工作目录——必须存在，否则连接器会拒绝启动
curl -fsSL -o ~/.cheers/bin/cce-acp-connector \
  "https://github.com/ElePerson/Cheers/releases/latest/download/cce-acp-connector-$os-$arch"
chmod +x ~/.cheers/bin/cce-acp-connector
export PATH="$HOME/.cheers/bin:$PATH"   # 把这行加进 ~/.zshrc 就能长期生效
cce-acp-connector --help                # 打印出帮助 = 成功

4. 创建机器人并拿到令牌

令牌（token）是连接器以你的机器人身份登录网关用的"密码"。在界面里获取：

1. 登录 Cheers，打开 设置 → 机器人。
2. 创建一个机器人（或打开已有的）。取个名字如 claude，把 bridge/provider 类型设为 generic / ACP。
3. 签发令牌并复制。把它存进一个只有你能读的小文件：

   mkdir -p ~/.cheers/secrets && chmod 700 ~/.cheers/secrets
   # 把 PASTE_TOKEN_HERE 换成你复制的令牌：
   printf '%s' 'PASTE_TOKEN_HERE' > ~/.cheers/secrets/claude.token
   chmod 600 ~/.cheers/secrets/claude.token

5. 写一个配置文件

创建 ~/.cheers/cheers-daemon.claude.toml。这是最小形式——其余字段都有合理默认值。把两个 URL 改成你的网关地址， 把 command 改成你智能体的路径：

version = 1

[daemon]
state_path = "state-claude.json"   # 相对于本文件所在目录（~/.cheers）
log_dir    = "logs-claude"

[accounts.claude.bridge]
control_url    = "ws://localhost:8000/ws/agent-bridge/control"
data_url       = "ws://localhost:8000/ws/agent-bridge/data"
bot_token_file = "secrets/claude.token"   # 第 4 步的文件——绝不在这里直接写令牌

[accounts.claude.adapter]
type    = "stdio"
command = "/opt/homebrew/bin/claude-agent-acp"   # command -v claude-agent-acp 的输出
args    = []

[accounts.claude.policy.prompt]
allow             = true
allow_attachments = true    # ← 让机器人能收到你附加的文件
allow_images      = true

[accounts.claude.policy.workspace]
default_cwd   = "~/.cheers/workspace"
allowed_roots = ["~/.cheers/workspace"]
backend_may_set_cwd = true

[accounts.claude.policy.env]
inherit = false
allow   = ["HOME", "PATH"]   # HOME 让智能体能读到你 ~/.claude 的订阅登录

[accounts.claude.policy.permission]
forward_to_backend = true    # 工具调用请求会作为审批卡片出现在频道里
wait_timeout_ms    = 900000
on_timeout         = "cancel"
auto_allow         = false

[accounts.claude.policy.mcp]
inject_cheers = true         # 给智能体注入 Cheers 工具（读文件、发消息……）

配置目录最终长这样：

~/.cheers/
├─ cheers-daemon.claude.toml     # 一个文件 = 一个机器人
├─ secrets/claude.token          # 令牌，权限 600
├─ workspace/                    # 智能体的工作目录
└─ logs-claude/                  # 它的日志

启动并确认在线

cce-acp-connector start  --config ~/.cheers/cheers-daemon.claude.toml --name claude
cce-acp-connector status --name claude          # → status=running
cce-acp-connector logs   --name claude --lines 40
# 应看到 "initialized ACP agent" 和 "BridgeRuntime started"，没有 ERROR

现在在 Cheers 频道里 @ 这个机器人。有回复就说明连上了。🎉 因为令牌存在文件里，重启不需要任何额外步骤： cce-acp-connector restart --name claude。

6. 保持更新 （重要）

Cheers 的新功能往往需要相匹配的连接器版本。过期的连接器照样能连、照样能跑——它只是会悄悄跳过自己还看不懂的东西。 最常见的"受害者"就是附加的 context：文件小标签（chip）在聊天里显示得好好的，但机器人根本没收到，还反过来让你上传文件。 更新一下就能修好。

先看你是不是落后了

cce-acp-connector status --name claude
# 若有更新版本，这里会出现一行 "update available:"，
# 启动时的日志里也会有一条提醒。

方式 A —— 打开带签名的自动更新（连接器 ≥ 0.1.27）

在配置里加上这段，然后重启一次。之后连接器会安全地自我更新（校验 ed25519 签名和 sha256、等空闲、原地替换， 新版本不健康还会自动回滚）：

[update]
auto = true

方式 B —— 手动更新

重新跑一遍第 3 步的下载（会覆盖旧二进制），然后重启：

os=$(uname -s | tr 'A-Z' 'a-z'); arch=$(uname -m | sed -e 's/x86_64/amd64/' -e 's/aarch64/arm64/')
curl -fsSL -o ~/.cheers/bin/cce-acp-connector \
  "https://github.com/ElePerson/Cheers/releases/latest/download/cce-acp-connector-$os-$arch"
chmod +x ~/.cheers/bin/cce-acp-connector
cce-acp-connector restart --name claude

自动更新默认关闭是有意为之——更新意味着执行下载来的代码，所以由机器主人自己选择开启。 你随时可以用 CHEERS_ACP_NO_SELF_UPDATE=1 彻底禁用它。

7. 附加文件是怎么工作的

在消息输入框里，Add context（添加上下文）让你附加一个文件（或像 review.md:1-1 这样的行范围， 或工作区里的某个文件）。每个附件会在你的消息上变成一个小标签。发送时，Cheers 把这些引用传给机器人的连接器， 连接器再把它们写进智能体的 prompt，让它知道你指的是什么。

• 机器人在它那侧解析这些引用（通过 Cheers 工具去读文件）——所以大文件也不用整段粘贴。
• 要实现这一点，机器人的配置需要 allow_attachments = true（上面模板里已有），并且连接器要是 较新版本。旧连接器会静默丢弃这些引用。

8. 排障

延伸阅读