cc-connect：15K Star 的「Agent 遥控器」——Claude Code 装进飞书/Telegram，人不在电脑前，手机发条消息 agent 照样改代码

多 Agent 时代的最后一个盲区：人不在电脑前

该解决的都解决了：agent 能自己开终端（herdr）、能自己改代码（Claude Code/Codex）、能互相协作（多 agent 编排）、能记住上下文（claude-mem）。但有一个场景一直没人好好填——你离开电脑之后，agent 怎么办。地铁上想起来有个测试要重跑，周末出门 PR 卡在 CI，agent 干到一半卡在权限审批等你点确认——你只能干瞪眼，等回到屏幕前。

传统解法都别扭：SSH 回家连 tmux，手机上的终端体验一言难尽，还得有公网 IP 或 frp；用云 IDE（GitHub Codespaces / Cursor 云）等于换一套环境，本地代码库、本地依赖全对不上；MCP 远程通道能传消息，但那是给程序用的，不是给人用的。cc-connect 选了一条最顺手的路：聊天软件就是现成的远程驾驶舱，你的 agent 变成一个会回你消息的「同事」。

它是什么：一个 Go 二进制，两头都是适配器

架构一句话：消息平台 ⇄ cc-connect ⇄ 本地 agent CLI。cc-connect 是个常驻进程，一端接各聊天平台的 bot API，另一端拉起并驱动你的 coding agent。你在飞书/Telegram 里发消息，它把消息转成 agent 的输入，agent 的回复流式地转回聊天框。Agent 侧的会话通过 --continue 持久化，所以每次对话都能接上之前的上下文，不是一问一答的裸 API 调用。

层	是什么	举例
Agent 适配层	10+ 种官方适配 + 任意 ACP 兼容 agent	Claude Code、Codex、Cursor Agent、Gemini CLI、Kimi CLI、Qoder、OpenCode、Pi、Copilot、Devin（走 ACP）
平台适配层	13 种消息平台 bot	飞书、钉钉、Telegram、Slack、Discord、企业微信、微信（ilink）、QQ、QQ Bot、LINE、微博、Matrix、TuiTui
控制层	斜杠命令 + Web UI + CLI	`/mode yolo`、`/cron`、`cc-connect send`、Web 配置台 `:9820`

多项目架构：一个进程可以挂多个 project，每个 project 绑定自己的代码目录 + agent + 平台组合，互不干扰。配置走 ~/.cc-connect/config.toml，Web UI 改完热加载，不用重启。

核心机制一：免公网 IP 是怎么做到的

这是它最狠的设计。绝大多数平台走的是出站长连接——你的机器主动连平台服务器，平台把消息推下来，所以不需要 inbound 端口、不需要公网 IP、不需要 frp/ngrok：

平台	连接方式	要公网 IP 吗
飞书 / Lark	WebSocket	❌ 不需要
钉钉 DingTalk	Stream 模式	❌ 不需要
Telegram	Long Polling	❌ 不需要
Slack	Socket Mode	❌ 不需要
Discord	Gateway	❌ 不需要
QQ Bot（官方）	WebSocket	❌ 不需要
个人微信	HTTP 长轮询（ilink）	❌ 不需要
企业微信	WebSocket / Webhook	⚠️ Webhook 模式要，WS 不要
LINE	Webhook	✅ 需要
Matrix	/sync 长轮询	❌ 不需要

对国内用户这几乎是刚需：飞书、钉钉、企业微信、QQ、微信全覆盖，还全都不用公网 IP。装个机器人，把 token 贴进 Web UI，就通了。对比一下：SSH 方案得先解决 NAT 穿透，这方案开箱即用。

核心机制二：agent 侧怎么被「遥控」

桥接层是 Go 写的，但 agent 侧不是每个都写死适配——统一走 CLI 包装 + ACP（Agent Client Protocol）。ACP 是个开放协议（agentclientprotocol.com），任何实现了 ACP 的 agent 都能被 cc-connect 驱动，Devin 就是这么接进来的。没实现 ACP 的（Claude Code、Codex 们）用各自 CLI 的持久会话模式包装。

会话管理有两个防失控设计，值得抄：

reset_on_idle_mins（默认 30 分钟）：会话空闲超过 30 分钟自动开新会话，防止旧聊天记录里的调试噪音、失败命令反复被 --continue 灌进上下文，把模型注意力带偏（官方叫 context drift）。旧会话不删，/list、/switch 还能找回。
max_turn_time_mins 墙钟上限：一条消息的处理时长封顶，超时走 soft-stop → force-kill → auto-resume 三级处置。没有这个，一条卡死的 npm test 能把整个会话锁到天荒地老。

还有附件回传：agent 在本地生成了截图、图表、PDF，可以主动发回聊天（cc-connect send --image /path/chart.png --file /path/report.pdf），目前飞书和 Telegram 支持，单附件上限 50MiB。跑完测试把截图甩到群里，比文字汇报直观得多。

核心机制三：权限和隔离，不是裸奔的远程 shell

把 agent 接进聊天软件，等于给聊天账号开了半个 shell 权限，所以权限体系是分层的：

allow_from / admin_from：谁能在群里用这个 bot；admin_from 白名单里的用户才能跑特权命令（/dir、/shell、/restart、/upgrade、/cron addexec）。/whoami 能查自己的 User ID。官方直接警告：admin_from = "*" 等于把主机 shell 交给所有被允许的人。
/mode 权限模式：default（每个工具调用都要确认，回到电脑前批）vs yolo（全自动放行）。出门在外的正确姿势是 yolo + 可信代码库，别拿 yolo 跑不可信代码。
run_as_user（Linux/macOS）：让 agent 以另一个 Unix 用户身份跑，OS 级的文件系统隔离，跟跑 cc-connect 的宿主用户分开。启动前用 cc-connect doctor user-isolation 审计——三个 go/no-go 预检 + 隔离探测，探测到跨用户泄漏直接拒绝启动。这套目前 Claude Code 支持得最完整。

多 Bot 编排 + 定时任务：agent 之间互相喊话

一个群里可以绑多个 bot，各自接不同的 agent——「多 bot 中继」：让 Claude 干活，让 Gemini 评论，relay send 还能跨项目转发消息拿回复。你在一个对话里同时指挥两个模型，它们之间还能互相引用对方的输出。

定时任务走自然语言：

/cron add 0 6 * * * Summarize GitHub trending   # 每天早上 6 点干这个
/cron list                                      # 看看都挂了啥
/cron exec <id>                                 # 立刻触发一次

语音和图片也通：发语音过去自动 STT，agent 回语音用 TTS（要另配语音服务）；截图直接发过去当多模态输入。对「人在外面」这个场景，语音是最快的输入方式。

上手：实测跑通的命令序列

# 0) 顺序不能错：先装 agent CLI 并登录，再装 cc-connect
npm install -g @anthropic-ai/claude-code && claude login

# 1) 装 cc-connect（npm / brew / 二进制三选一）
npm install -g cc-connect
# 或：curl -L -o cc-connect.tar.gz \
#   https://github.com/chenhg5/cc-connect/releases/download/v1.5.0/cc-connect-v1.5.0-linux-amd64.tar.gz
#   ⚠️ README 里的 cc-connect-linux-amd64 直链已经 404，asset 名带版本号

# 2) 启动（首次运行自动生成 ~/.cc-connect/config.toml 然后退出，让你先编辑）
cc-connect
# 编辑 config.toml：把 work_dir 改成真实目录，贴平台 bot token
# 或者用 web 子命令自动配置：
cc-connect web        # 自动配好 Web admin，打印 http://localhost:9820/login?token=...

# 3) 再启动，服务起来后 Web 配置台在 :9820，热加载
cc-connect

# 4) 聊天里的常用命令
/new                 # 新会话
/dir ~/proj          # 切换工作目录
/mode yolo           # 全自动放行（出门在外标配）
/model switch sonnet # 切模型
/provider switch deepseek
/cron add 0 6 * * * Summarize GitHub trending
/cancel              # 打断当前回合

# 5) CLI 侧
cc-connect send -m "跑一下测试" -p my-project
cc-connect sessions list
cc-connect provider import    # 能直接导入 cc-switch 的 provider 配置

实测与踩坑（v1.5.0，Linux amd64）

我在沙箱里完整走了一遍：v1.5.0 二进制（52MB）下载 → 首次启动 → 配置校验链 → Web UI。跑通的部分：--version 正常（commit 17c61062，2026-08-16 构建）；首次启动自动创建 ~/.cc-connect/config.toml；cc-connect config example 输出 2272 行完整带注释配置；cc-connect web 自动配置 Web admin 并打印带 token 的登录 URL。但 README 至少有三个说法已经跟 v1.5.0 对不上了——按坑的杀伤力排序：

坑 1：README 的 release 直链 404。README 写 cc-connect-linux-amd64，我 curl 下来一个 9 字节的 "Not Found" 文件。实际 asset 名是 cc-connect-v1.5.0-linux-amd64.tar.gz（tar 包，解压后才是二进制）。照着 README 装必踩。
坑 2：README 停在 v1.3.3，实际已 v1.5.0，几个说法全过时。① README 说端口被占时传 --web-port 9821——实测 v1.5.0 根命令根本没有这个 flag（flag provided but not defined: -web-port，直接打印帮助退出）；② README 说首次运行会打印 "Web admin: http://localhost:9820"——实测首次运行只生成默认配置就退出，提示你编辑完再跑；③ cc-connect web 的行为也变了：README 说它「只打开浏览器和配置 UI，不开服务」，实测它自动把 Web admin 配好并生成 login token，比文档描述的更自动。遇到文档和二进制打架，以 cc-connect config example 和 --help 为准。
坑 3：启动校验链是「三关连卡」，且报错有误导性。第一关 work_dir 必须真实存在（默认配置里的 /path/to/your/project 占位符会直接报 work_dir ... does not exist）；第二关 agent CLI 必须在 PATH（claudecode: "claude" CLI not found in PATH，README 只提了这关）；第三关平台 token 必须有效——我塞了个假 Telegram token，报的是 telegram: token is required，而不是「token 无效」，排查时容易被带偏（疑似内部调了 Telegram getMe 校验，失败统一归到 required）。三关任何一关不过，进程直接退出，Web UI (9820) 根本起不来——不是起了 UI 等你慢慢配。
小坑：admin_from 必须写在 [[projects]] 层，写进 [projects.platforms.options] 不生效（README 特意强调，容易顺手放错）。另外 reset_on_idle_mins 默认 30 分钟，长时间挂后台的任务会被轮换会话，虽然旧会话 /list 还在，但别指望一个对话活一整天。

对比：跟「远程控制 agent」的其它路线

方案	形态	要公网 IP	agent 感知	消息回传	上手成本
cc-connect	Go 桥接服务 + 聊天 bot	大多不需要	✅ 完整（持久会话 + 权限 + 隔离）	✅ 流式 + 附件 + 语音	低（贴 token 即用）
herdr	Rust 终端 server + TUI	看部署	✅ 状态机（blocked/working/idle）	❌ 无消息通道	中（要理解 workspace 模型）
SSH + tmux	手工组合	✅ 必须（或 frp/ngrok）	❌ 完全无感知	❌ 纯终端	高（穿透 + 终端 app）
云 IDE（Codespaces/Cursor 云）	浏览器 IDE	✅ 平台托管	部分（云环境里）	⚠️ 靠通知	中（环境要重搭）
MCP 远程通道	程序到程序	看实现	✅ 但面向程序	❌ 不是给人聊天的	高

一句话：herdr 解决「agent 在我电脑上怎么活得更久」，cc-connect 解决「agent 在我电脑上怎么被我远程指挥」。两者不冲突，甚至可以叠用——herdr 保活终端，cc-connect 负责把消息送进去。

什么时候别用它

反话时间：代码里有密钥、agent 要碰生产环境的，先想清楚 /mode yolo + 手机远程这个组合意味着什么——你的聊天账号就是半个 root，admin_from 配错等于给群里所有人开 shell。真想隔离就认真配 run_as_user，别嫌它前置条件多（passwordless sudo、独立 home、凭据同步，全套下来够喝一壶）。另外它定位是「桥」，不做 agent 本身的事：没有自己的模型、不做代码理解，你的 agent 还是原来那个 agent。

但如果你已经用 Claude Code / Codex 干活，且不止一次在离开电脑后想过「这活儿能不能让 agent 先干着」——这就是那个把聊天软件变成 agent 遥控器的东西。6 个月 1.5 万 star、v1.5.0 两天前刚发、MIT 协议，这个方向被市场验证过了。装上之后你会发现，agent 从「坐在你电脑里的工具」变成了「随时能喊的同事」。