Cc Remote

cc-remote — 通过飞书远程操作 Claude Code

把 Claude Code 在本地需要确认/审批的环节（危险工具调用、权限弹窗）和每轮进度推送变成飞书交互卡片。通过 AgentBoard 中转，安装一次只需贴一个 token。

功能

事件	飞书侧	你能做的
Bash / Write / Edit / MultiEdit / NotebookEdit / mcp__* 调用	红色审批卡	Approve / Deny / 文本指示 / 交还终端
每轮回复结束 (Stop)	蓝色进度卡 + 输入框	直接在飞书写一句让 Claude 接着做
权限弹窗 (Notification)	橙色通知卡	知会
Session Start / End	绿/灰生命周期卡	知道哪台机器在跑哪个项目

双通道兼容：飞书等待时随时可以在终端按 Esc → 卡片自动 PATCH 成 cancelled，本地原生提示接管。先到的渠道（飞书 / 本地 / 超时）单赢，绝不会同时给 Claude 两个相反决定。

Fail-open：AgentBoard 不可达 / Lark 离线 / 超时 → hook 自动回退成 permissionDecision: "ask"，Claude Code 走原生本地提示，永远不卡死你的工作流。

架构（relay 模式）

Claude Code TUI
   │ hook stdin/stdout
   ▼
bin/cc-remote-hook  ──HTTPS 长轮询──►  AgentBoard /api/cc-remote/event
   (本机瘦客户端)                      ├── 内置 Lark WSClient (单例)
                                      └── PendingTable (单进程 Map)
                                                │ WebSocket 出站
                                                ▼
                                            飞书自建应用 (公司共享)

• 本机只装一个瘦 hook（bin/cc-remote-hook）+ 配置 ~/.cc-remote/config.json，没有 daemon、没有占端口。
• App ID/Secret 配在 AgentBoard 的环境变量里，全公司共用一个机器人。
• 每个用户在 AgentBoard 上 generate 一个 ccr_… 的 token，把 token 粘进本机 + 在飞书机器人里发 /bind <token> 即可。

安装

1. 在 AgentBoard 上 generate token

打开 AgentBoard → cc-remote 页面 → Generate token，得到形如 ccr_xxx… 的字符串。

2. 装入 Claude Code

/plugin install file:///Users/<you>/Code/cc-remote

或者把仓库路径加到 marketplace。/plugin list 应能看到 cc-remote 0.2.0。

3. 绑定本机

/cc-remote:link

按提示粘贴 AgentBoard base URL + token。本机配置写到 ~/.cc-remote/config.json (mode 0600)。

4. 在飞书机器人私聊里发 /bind <token>

把整段 token 贴到 /bind 后面（机器人由 AgentBoard 维护，全公司共用）。绑完飞书会回一张绿色 “linked” 卡。

5. 验证

/cc-remote:status

应该看到：

base   : https://agentboard.example.com
token  : ccr_xxxxx…
lark   : connected
bound  : yes (chat=oc_xxxxxxxx)
pending: 0

随后让 Claude 执行任意 Bash —— 飞书应弹出红色审批卡。点 Approve 看终端继续。

命令

命令	作用
/cc-remote:link	粘 token + base URL，本机绑定
/cc-remote:status	查 AgentBoard / Lark 连接 + 当前 chat
/cc-remote:pause	临时关闭飞书转发，所有 hook 走本地默认
/cc-remote:resume	恢复飞书转发
/cc-remote:unlink	删除本地 config（如要撤销 token，去 AgentBoard 页面 Revoke）

文件位置

~/.cc-remote/
├── config.json   # { baseUrl, token } (mode 0600)
├── state.json    # pause 标志等运行时状态
└── hook.log      # hook 端日志（fail-open 原因）

环境变量（hook 侧）

无。所有配置在 ~/.cc-remote/config.json。AgentBoard 那边的环境变量由管理员配置。

排错

Q: /cc-remote:status 显示 lark: DISCONNECTED → AgentBoard 那边的 CC_REMOTE_LARK_APP_ID / CC_REMOTE_LARK_APP_SECRET 没设置或机器人 App 没启用长连接。让管理员检查 AgentBoard 服务器日志。

Q: 在飞书发 /bind <token> 没反应 → 确认机器人订阅了 im.message.receive_v1 事件、token 没敲错。也可能 /bind 写错（注意中间有空格）。

Q: 卡片按钮按了没反应 → 飞书自建应用必须订阅 card.action.trigger，否则 AgentBoard 收不到点击。

Q: 飞书不在身边想就地操作 → 在终端按 Esc 取消（卡片会被 PATCH 成 “cancelled”），或者跑 /cc-remote:pause 整段时间不打扰。

设计取舍

• 集中式 relay：把 Lark 长连接、卡片 PATCH、决议表都放到 AgentBoard，一台机一个 process 共享 WS 通道。本机只剩 token + 小 hook。
• 同步长轮询 hook：PreToolUse hook timeout 300s，AgentBoard 内部 290s 计时；保证总是服务端先回，不会被 Claude 中途 kill。
• Single-resolve 决议：每个 decisionId 只能被一个 channel 解决（飞书 / 本地 Esc / 超时），避免双向冲突。
• Fail-open 原则：任何故障路径都回退到 Claude 本地原生提示，远比"飞书坏了你也别想干活"安全。
• Token-per-user：一个公司机器人对多个开发者；每人独立 token，只能解决自己的卡。

协议参考

• Claude Code hooks: https://code.claude.com/docs/en/hooks
• Claude Code plugins: https://code.claude.com/docs/en/plugins
• Lark Node SDK (服务端用): https://github.com/larksuite/node-sdk
• 飞书卡片 2.0: https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/feishu-cards/card-json-structure-overview

许可

MIT