CloseCrab 🦀

把 Claude Code、OpenClaw、Kilo Code、Gemini CLI 变成 24/7 在线的聊天 Bot——跑在飞书、Discord、钉钉上，支持共享记忆、bot 间协作、运行时热切换、实时语音。

CloseCrab 把 AI Agent CLI 工具包装成多平台聊天 Bot。它不重新实现 agent 能力——直接驱动 CLI 进程，所以上游生态里的每一个 Skill、Plugin、MCP Server 都能即装即用，零适配成本。

🌍 English readers: see README.en.md for the full English documentation.

4 个 Agent Runtime · 3 个聊天平台 · 默认部署 28 个 Skill（24 个公共 + 4 个私有；仓库共 47 个，按 allowlist 放行）· 3 条语音通道 · 1 套统一身份和记忆。

每个 runtime 是一个不同的 AI Agent CLI。CloseCrab 让同一个 bot 在它们之间运行时切换——身份 / 记忆 / 团队上下文在切换中全部保留。

切换中自动处理：model 命名空间翻译（claude-opus-4-7 → provider/model:openclaw）· workspace 文件自愈（GEMINI.md / AGENTS.md 缺失自动重写）· memory 索引重建（OpenClaw sqlite 启动扫描）。

延伸阅读：Hybrid Agent Runtimes——4 个 Agent CLI 如何互相吸收对方的能力

每个 bot 都有四层持久化记忆，重启、runtime 切换、迁移机器后不丢（另有第五层「会话自动召回」，见跑起来之后会自动发生的事）：

自动写入：agent 在对话中发现 user / feedback / project / reference 级别的信息时主动落盘——参考 Karpathy LLM Wiki 理念，知识编译而非检索。

多 bot 跨机器协作，分两层通道：

• 协调通道：Leader 在 #team-ops 飞书/Discord 频道用 @mention 派活，Teammate 完成后 @Leader 汇报
• 异步通道：scripts/inbox-send.py 写 Firestore messages 集合，对端 bot 通过 on_snapshot 实时推送（不是轮询）

# Leader 给 teammate 派任务（异步，非阻塞）
python3 scripts/inbox-send.py bunny "在 B200 上跑 Llama 4 benchmark，写到 CC Pages 给我链接"

Team 角色配置存 Firestore bots/{name}.team，build_system_prompt() 根据角色动态注入协调规则，所以 Leader 看到的 system prompt 跟 Teammate 不一样。

多阶段任务走 Inbox 协议 V1：kickoff / progress / done 三种 phase 用同一个 task_id 串起来。progress 不触发对端 LLM turn（只给人看），只有 done 触发一次，把全部 progress 打包进 prompt。详见 docs/inbox-task-protocol.md。

三条独立的语音通道，可以同时开：

音色是 bot 级配置，存 Firestore bots/{name}.channels.discord.tts_voice（Gemini TTS 的 15 个 voice 任选）。流式直播和 ogg 语音消息共用同一个来源，没配就直接报错——不做静默兜底，避免"改了配置不生效"这类问题。

开关都会落盘：/discordon /discordoff /zelloon /zellooff 写回 Firestore，跨重启保持。Zello 全网只有一个账号，/zelloon 会先检查是否已被别的 bot 占用（同账号双登会互踢）。

LiveKit（/voice 浏览器通话）的房间与网页前端已停用；closecrab/voice/livekit_io.py 仍然承重 —— Discord 语音接收方向依赖它的 agents SDK，别按文件名误删。

一条时间线，一个 daemon，两种用法。由第一个 bot 的 run.sh 以单例方式拉起，所以 daemon 跟 bot 同环境；机器上没 bot 就不会有 daemon。

# 定时提醒（--cron 与 --at 按 HKT 解释）
python3 scripts/cron-tool.py add --target <bot> --in 10m --message "..."
python3 scripts/cron-tool.py add --target <bot> --cron "0 9 * * MON-FRI" --message "..."
python3 scripts/cron-tool.py list|remove <job_id>

# 盯一个训练/压测，有进展才出声
python3 scripts/watch-task.py create --name t80 --interval 120 --model sonnet \
    --notify-bot <bot> --max-age 7200 \
    --prompt "读 /tmp/t80.log 判断进度。出现 TRAINING COMPLETE 或 Error 时用 DONE。没变化就 SKIP。"
python3 scripts/watch-task.py list|stop <name>

设计要点：

• 通知与触发事件走不同通道。REPORT 用 feishu-notify.py 直接贴消息，零 turn 零 token；DONE 写 inbox，触发主进程一次完整 turn 来接手。别让"看一眼就行"的播报去烧 turn。
• 探针档位自选：--model haiku（看日志变没变，默认）/ sonnet（要读懂内容再判断）/ opus（要做真取舍）。
• 任务钉在创建它的机器上。每条记录带 host 归属，多机共驱一条时间线靠 Firestore 事务抢占；没有 host 归属的记录会被直接删除。
• 有硬上限：--max-age 默认 6 小时自动收，--stall-after 连续无进展算疑似卡住。不要往系统 crontab 里塞会调 LLM 的东西——那种条目没有 owner、list 看不见、不会自终止。

设计细节见 docs/task-scheduler-design.md。

每个 skill 是 skills/{name}/SKILL.md 加可选的 scripts/ 和 references/。deploy.sh 只 link config/skill-allowlist.txt 里放行的——仓库里还有 20 多个低频 skill，源码都在、默认不装，需要时在 allowlist 加一行再跑 deploy 就回来。新建 skill 用 skill-creator 自举。

部分 skill 依赖内部环境（Google 内网 MCP、客户群追踪等），放在私有仓库，不在这份清单里。

不依赖具体 worker 的运行时能力，所有 bot 都能调：

# 真并行多个 LLM sub-agent（每个独立推理 + bash + read）
python3 scripts/subagent-parallel.py --inline '{"tasks":[{"label":"A","prompt":"..."}]}'

# 定时 / 盯梢（见上面 Timeline 章节）
python3 scripts/cron-tool.py   add|list|remove ...
python3 scripts/watch-task.py  create|list|stop ...

# 只发通知，零 turn 零 token（跟"写 inbox 触发 turn"是两回事）
python3 scripts/feishu-notify.py "跑到第 2 步了"

# 自查 model / cost / token / 历史 turns
python3 scripts/session-status.py <bot> [--days N]

# 安全自重启（agent 不能 kill 自己的父进程，用这个写 marker 走 exit-42）
BOT_NAME=<bot> python3 scripts/self-restart.py --note "重启后要做的事"

# 图片 / 语音生成
skills/imagen-generator/scripts/imagen-generate.sh "prompt" --aspect 16:9
skills/tts-generator/scripts/tts-generate.py "[casually] hello"

这些默认开启、用户看不见，但在花钱或在改写 prompt，部署前值得知道：

• <voice-summary> —— 文字回复末尾加这个，内容会被 TTS 念出来做口语摘要
• <voice-file>/tmp/xxx.ogg</voice-file> —— 已经生成好的 ogg 直接发出去（tts / music skill 的产物走这条）

tools/cc-api.py 是一个 HTTP 入口，让 Siri 快捷指令这类外部客户端也能给 bot 发消息， 不必经过飞书/Discord。配套 tools/board-push.sh 服务 live-canvas skill 的实时白板。

scripts/publish-cc-page.sh <本地html> [--to pages|assets|both]

内部文档必须显式 --to pages —— 默认 both 会同时传一份到无鉴权的公开路径。

Python 3.13+ 注意：audioop 已被 PEP 594 移除，Discord 语音 sidecar 在新系统上需要先装 audioop-lts。音色配置模块 voice/tts_config.py 已刻意做成零重依赖，不受影响。

这个项目的本质是：把聊天消息变成你机器上的 shell 命令。 agent 拥有 Read / Edit / Bash 和所有 MCP，权限等同于跑它的那个 Linux 用户。请按这个前提评估风险。

一句话：当作「给别人一个你机器上的 shell」来对待，而不是当作一个聊天机器人。

# 1. 克隆
git clone https://github.com/yangwhale/CloseCrab.git && cd CloseCrab

# 2. 配置 Firestore（只填 project + database，其它走 Firestore）
cp .env.example .env && vim .env

# 3. 一键部署（交互式引导 API keys，会装 Claude Code + Gemini CLI + Skills + Python 依赖）
./deploy.sh

# 4. 创建 bot（默认 channel 推荐飞书）
python3 scripts/config-manage.py create mybot --channel feishu \
    --app-id "cli_xxxxxxx" --app-secret "xxxxxxxxxxxx"

# 5. 启动（run.sh 是带自动重启的 wrapper，同时负责单例拉起 cron-daemon）
nohup ./run.sh mybot > /tmp/mybot.log 2>&1 &

Pro tip：已经装了 Claude Code？在这个目录跑 claude，然后说"按照 README 帮我部署成飞书 bot"——它会读这份文档帮你搞定全程。

# 三台机器的 @reboot 都调它；幂等，随时可手动跑验证
scripts/boot-autostart.sh [--check]

顺序：补 cron 最小环境 → 等 DNS → gcsfuse → OpenClaw Gateway → launcher.sh start all。cron-daemon 不在这里起，由第一个 bot 的 run.sh 拉起，这样它跟 bot 拿到同一份 PATH。

飞书是 CloseCrab 的 一等公民——下面的配置最完整。Discord 和钉钉是基础支持。

飞书是 CloseCrab 主力平台，配套 4 类事件订阅 + 4 类回调 + 完整命令体系。只复制 App ID 和 Secret 是远远不够的，需要额外配置以下内容：

1. 打开 飞书开放平台 → 创建企业自建应用
2. 在 凭证与基础信息 复制 App ID（形如 cli_xxxxxxx）和 App Secret
3. Lark 海外版同样流程，在 Lark Developer 操作

进 事件与回调 → 事件订阅，订阅方式选 长连接（CloseCrab 不需要 webhook URL），添加以下 4 个事件：

⚠️ 常被遗漏的两项：reaction.created_v1 和 bot.menu_v6 默认不订阅，导致用户给 bot 加 👍 没反应、点 bot 菜单没反应。

进 权限管理，申请以下 scope：

进 机器人能力 → 自定义菜单，event_key 填命令名（带不带 / 都行，bot 会自动规范化）。推荐配这 8 个：

完整命令集（23 个，直接发消息也能用）：

用户给 bot 上一条消息加 emoji，会被合成为一段"用户表态"消息发给 LLM。约束：只对 bot 自己发出的消息 上的 reaction 响应（避免群里别人互相 reaction 触发 bot）。

其他 emoji 默认不映射，由 LLM 自行判断是否响应。

bot 发的交互卡片（如 ExitPlanMode 审批卡、/sessions 切换卡）的按钮 / 下拉菜单点击，通过 card.action.trigger 事件回传。卡片用 _decode_feishu_card_action() 校验：

• 发起人必须是原 chat 的用户（防止群里别人点别人的卡片）
• 卡片必须未过期（默认 1 小时）
• 卡片必须在当前 session 上下文

无需额外订阅，绑定卡片即生效。

创建版本 → 申请发布 → 管理员审批通过后，bot 才能在企业内使用。

python3 scripts/config-manage.py create mybot --channel feishu \
    --app-id "cli_xxxxxxx" --app-secret "xxxxxxxxxxxxx"

# 可选：白名单 + 日志群。set 用 Firestore 点号路径，值按 JSON 解析
python3 scripts/config-manage.py set mybot channels.feishu.allowed_open_ids '["ou_xxx","ou_yyy"]'
python3 scripts/config-manage.py set mybot channels.feishu.log_chat_id '"oc_zzzz"'

每个 bot 可独立配置企业邮件，详见 docs/full-reference.md。

1. 打开 Developer Portal → New App → 改名 → Bot 子页 → 复制 Token
2. 开启 Message Content Intent（必须，否则收不到消息内容）
3. OAuth2 → URL Generator：勾 bot + applications.commands，权限勾 Send Messages Read Message History Connect（语音）Speak（语音）
4. 拿生成的邀请 URL 邀请到 server
5. 配置到 Firestore：

python3 scripts/config-manage.py create mybot --channel discord --token "DISCORD_TOKEN"
python3 scripts/config-manage.py set mybot allowed_user_ids '[123,456]'

Discord 自带 9 个 slash command（/status /end /restart /stop /docs /context /sessions /say /leave），bot 启动时自动注册到 Server。

常驻语音频道（可选）：active channel 是飞书时，也能让 bot 额外连一条只做语音输出的 Discord 连接。配 channels.discord.voice_sidecar=true + voice_channel_id + tts_voice，或运行时发 /discordon（会落盘，跨重启保持）。

1. 钉钉开放平台 → 企业内部开发 → 创建应用
2. 复制 Client ID + Client Secret
3. 开启 Stream 模式（CloseCrab 长连接），勾 企业内机器人 权限
4. 配到 Firestore：

python3 scripts/config-manage.py create mybot --channel dingtalk \
    --client-id "dingxxxx" --client-secret "xxxxxxxxxxxx"

钉钉只支持文字消息，不支持语音 / 斜杠命令 / 卡片按钮回调。

任何平台发以下关键词立即中断当前 turn：

停 stop 取消 算了 打住 急刹车 停下 别做了 不要了

中断不是 SIGINT，是通过 worker 自己的协议传过去（Claude socketpair / ACP session/cancel / SSE close），保证 agent 干净退出。

# 本地 bot 管理（内部直接调 run.sh，不另抄重启循环）
scripts/launcher.sh start|stop|restart|status|logs <bot>

# 开机自启（幂等）
scripts/boot-autostart.sh [--check]

# 健康检查（进程 / Firestore / worker secrets / 日志活性 / 近期错误）
scripts/closecrab-smoke-test.sh <bot> [--json] [--actions]

# 远程部署（多 bot 调度）
scripts/dispatch-bot.sh deploy <bot> <host>   # 三种动作签名不同，别套同一个模板
scripts/dispatch-bot.sh move   <bot> <host>
scripts/dispatch-bot.sh recall <bot>          # 不收 host
scripts/dispatch-bot.sh check  <ssh_host>     # 只收 host，不收 bot

# Runtime 切换
scripts/config-manage.py set-worker-type <bot> claude|openclaw|kilo|gemini

# Bot 间消息（Firestore inbox，on_snapshot 实时推送）
scripts/inbox-send.py <target> "<msg>"

# 记忆同步备份（GCS + private repo）
scripts/sync-memory.sh --push|--pull

别随便升级。Claude Code CLI 没有 auto-upgrade，所有升级都是手动 claude install <version>。历史上 2.1.144 / 2.1.145 出现过 900K 上下文 regression，所以每次升级前必须先验证「上下文有没有被卡死在 200K」。

根因（反编译验证）：Math.min(jL() cap, autoCompactWindow) - min(CqH(H), 20000)，144 改了 compact decision function 让 autoCompactWindow 失效。

# Step 1: 记下当前良品版本（旧版本留在 versions/ 目录里当回滚点）
readlink ~/.local/bin/claude

# Step 2: 装目标版本（原生 installer 只换 symlink）
~/.local/bin/claude install <target-version>

# Step 3: 拿一个非主力 bot 做压力测试，让它连读 5 个大文件
python3 scripts/inbox-send.py <test-bot> "请依次 Read 这 5 个大文件不要停 ..."

# Step 4: 验收标准（两项都要满足才算 PASS）
#   ✅ peak cache_read > 250K        （证明 cap 没被钳到 200K）
#   ✅ 本次新增 compact 事件 = 0      （证明没 thrash）

# Step 5: 失败 → 立即回滚
~/.local/bin/claude install <known-good-version>

# Step 6: PASS 才推全 fleet

两个测量陷阱：

1. claude --version 查的是 PATH 上那个（可能是 npm 装的），不是 bot 实际调用的。要问就问代码：_resolve_config(bot)["claude_bin"] 再对它 --version。
2. 别把 claude_bin 写成 versions/2.1.143 这种绝对版本路径——那会让该 bot 永远停在那个版本，claude install 换的是 symlink，绕不过绝对路径。统一指向 ~/.local/bin/claude。

See CONTRIBUTING.md for guidelines.

Copyright 2025-2026 Chris Yang (yangwhale). Apache License 2.0 — see LICENSE.