Command CLI Agent 是一个很小的工具。
它做的事情很简单：
- 把
Weixin/Telegram/QQ变成原生 agent 的外部对话框 - 让你直接把消息送到
codex/claude/opencode - 顺手提供一个本地 TUI 来做登录、切 backend、启停服务和看状态
它不是新的主脑，也不是新的 orchestrator。
主脑永远在原生 agent backend。cca 只是一个对话框。
如果你已经在深度使用 codex cli、claude code、open code，通常就不会太想再套一层更重的编排框架。
这个工具的想法就是：
- 不去重做 OpenClaw / Hermes 那种平台
- 不去重新定义 agent
- 只做一层薄薄的外部对话框
建议 Windows 10/11。从 GitHub Release 下载 command-cli-agent-<version>.tgz 后执行：
npm install -g .\command-cli-agent-<version>.tgz
cca安装后运行 cca 即可进入控制中心。
cca status 可以在不启动 TUI 的情况下快速查看所有频道的服务状态。
账号连接见 账号连接指南。
每个对话会话以确定性密钥（channel + account + 对话类型 + 对方 ID + 群组 ID + 工作目录）存入 session-store.json，所有读写通过互斥锁串行化，不会因并发写入损坏数据。
网关重启时自动恢复所有会话，不同后端的恢复策略不同：
- Codex 后端：与 app-server 交叉验证线程存活状态。已加载且仍在运行的 thread 直接恢复（用户无感），丢失的 thread 自动轮换创建新的
- Claude / OpenCode 后端：重启后子进程必然丢失，直接清除孤儿状态（卡在
running的会话重置为idle），下次对话从新线程开始 - 隔离绑定：每个会话创建时绑定到指定后端，不会被错误路由
- 同会话串行：同一个对话内的消息通过 Promise 链严格按顺序执行，不会并行冲突
- 跨会话并行：不同对话的 Promise 链完全独立，一个用户的长任务不会阻塞其他用户
- 5 秒去重：相同消息 5 秒内重复投递自动丢弃（最多缓存 100 条），防止网络重传导致重复处理
- 轮询不阻塞：消息投递是 fire-and-forget 的，即使后端响应很慢，新消息也能继续被接收和调度
双层守护机制，确保服务始终可用：
- 进程级看门狗：supervisor 每秒检测网关进程存活状态，崩溃后自动重启（500ms 起步线性退避，上限 10s，连续崩溃 5 次后放弃并报警）
- Turn 级 idle 看门狗：运行时持续记录 backend activity。只有子进程超过配置阈值无输出/无进度才判定为卡死并中断；持续活跃的长任务不会因为跑满 10 分钟被硬杀。Claude 后端中断采用 SIGINT → 5s → SIGKILL 两阶段清理，并保留后端自身的长时间安全网
- 独占锁：supervisor 启动时获取排他文件锁（原子创建 + PID 验证 + 陈旧锁自动恢复），防止意外启动多个 supervisor 导致重复消息
- 运行时开关：可在 TUI 或聊天命令中随时启用/禁用看门狗，无需重启 supervisor
运行 cca 后，默认进入控制中心 TUI。左侧页签，右侧面板，底部快捷键提示。支持中/英双语（L 切换）。
CCA CONTROL CENTER ZH Weixin | Telegram | QQ Q/ESC
+-- 页面 ----------++-- 频道概览 ------------------------------------------+
| 1 总览 || > Weixin 状态=running |
| 2 登录 || Telegram 状态=running |
| 3 后端 || |
| 4 服务 || 配置 data/weixin-gateway.json |
| 5 日志 || 账号 *********@im.bot |
| 6 系统 || 地址 https://ilinkai.weixin.qq.com |
| 7 工作空间 || 令牌 wxid_*****************a3f7 |
| || 存储 data/weixin-gateway |
| || 更新 2026/4/1 1:30:00 |
| || |
| || 后端 CLAUDE |
| || 看门狗 ENABLED |
| || |
| || |
| || |
| || |
| || |
+------------------+------------------------------------------------------+
R 刷新
就绪
←→ 频道 Tab 面板 ? 帮助 F 刷新 Q 退出
全局快捷键
| 按键 | 功能 |
|---|---|
Q / Ctrl+C |
退出 |
← → |
切换频道（Weixin / Telegram / QQ） |
Tab |
切换侧边栏 / 主面板焦点 |
F |
强制刷新 |
? |
帮助覆盖层 |
页签说明
| 页签 | 功能 | 快捷键 |
|---|---|---|
OVERVIEW |
频道状态、后端、看门狗概览 | R 刷新 |
LOGIN |
微信扫码登录 / Telegram 配置 token / QQ 官方机器人配置提示 | 微信: Enter 扫码；TG: T token I account U username M 模式；QQ: O 平台 A AppID S Secret M 模式 |
BACKEND |
切换 codex / opencode / claude | C O L 快捷切换，或 ↑ ↓ + Enter |
SERVICE |
启动 / 停止 / 重启网关服务 | E 启动 S 停止 R 重启 |
LOGS |
查看 supervisor 日志 | R 刷新 |
SYSTEM |
看门狗开关、语言切换、自启动 | W 看门狗 L 语言 |
WORKSPACE |
工作空间管理（树形 + 详情双面板） | Enter 激活 n 新建 d 删除 c 切换 r 重置 |
在微信、Telegram 或 QQ 对话中直接发送斜杠命令控制网关。QQ 客户端如果不好输入 /，可以直接发送裸命令，例如 mode agent、backend claude、ws list。
| 命令 | 功能 |
|---|---|
/help |
查看可用命令列表 |
/status |
查看当前会话状态（线程、后端、队列深度） |
/interrupt |
中断当前正在执行的任务 |
/reset |
重置当前会话线程，下次对话从新线程开始 |
| 命令 | 功能 |
|---|---|
/mode |
查看当前交互模式（cli / agent） |
/mode cli |
切回 CLI 直连模式 |
/mode agent |
切到 Agent Worker 模式 |
/backend |
查看当前后端 |
/backend codex |
切换到 Codex 后端 |
/backend claude |
切换到 Claude 后端 |
/backend opencode |
切换到 OpenCode 后端 |
/worker status |
查看当前对话的 Agent Worker 模式状态 |
/worker current <任务> |
将一条任务按短期连续任务投递给 Agent Worker |
/worker quest <任务> |
将一条任务按持久队列任务投递给 Agent Worker |
/worker urgent <任务> |
将一条任务按紧急任务投递给 Agent Worker |
/ws |
查看当前工作空间 |
/ws list |
列出所有工作空间（回复数字快速切换或 d+数字 删除） |
/ws create <name> |
新建工作空间 |
/ws delete <name> |
删除工作空间 |
/ws switch <name> |
切换工作空间 |
/ws cd <dir> |
设置工作目录 |
/ws reset |
重置工作空间会话 |
Agent Worker 是 agent 交互模式使用的 workspace 协议。cca 只做网关和心跳投递，任务规划由后端 LLM 根据 workspace 内的协议文件完成。
Worker workspace 会生成 AGENT_WORKER.md、QUEST.md、.worker/CURRENT_TASK.md、.worker/STATE.json 和 logs/WORKER-LOG.md。长期调研、报告、编码或并行任务必须把 PROGRESS.md、notes/、findings/ 等产物写入文件；聊天通道只用于简短进度、状态、阻塞点和产物路径。CCA 会提示后端不要把中间文档正文大段发送到微信 / Telegram / QQ。
切换到 /mode agent 后，channel gateway（微信 / Telegram / QQ）自动以 60 秒间隔发送心跳 prompt。心跳包含当前时间戳，LLM 据此判断是否有到期的定时任务需要执行。
- 定时提醒：在
.worker/CURRENT_TASK.md中记录trigger_at时间，心跳到达时 LLM 比较时间戳，到期则回复提醒内容（用户会收到消息） - 多轮延续：LLM 可将未完成任务留在 CURRENT_TASK.md，每次心跳自动继续
- 空闲抑制：如果没有可执行任务，LLM 回复
[HEARTBEAT_IDLE]，系统自动拦截不发送给用户 - 忙碌排队提示：同一会话已有任务运行时，新消息仍会入队，同时用户会收到“当前请求已排队”的简短提示，可用
/status查看或/interrupt中断 - 协议校验：Worker 回复会携带隐藏 sentinel，CCA 用它判断后端是否仍遵守 worker 协议；若协议上下文稀释，下一轮会提示后端重新读取 workspace 协议
worker.heartbeatIntervalMs 可在 gateway 配置文件中自定义心跳间隔（默认 60000 毫秒）。
初始化一个 worker workspace：
cca worker init D:\AgentWorkspace初始化会生成：
AGENT_WORKER.md：Agent Worker 身份、调度和安全规则QUEST.md：持久任务队列.worker/CURRENT_TASK.md：短期连续任务.worker/STATE.json：worker 状态.worker/PAUSE_REASON.md：紧急任务暂停原因logs/WORKER-LOG.md：完成记录AGENTS.md/.claude/CLAUDE.md：后端入口 shimprojects//output//logs/
单次试跑：
cca worker once .\data\agent-worker.json常驻心跳：
cca worker start .\data\agent-worker.json微信和 Telegram 双向支持图片、语音、视频和文件收发。QQ 当前使用官方机器人接口，默认通过官方 WebSocket 长连接接收消息，并通过 OpenAPI 文本回复；不需要公网 IP 或云服务器。QQ 媒体消息当前会把官方临时 URL / 元数据传给后端并发送接收确认，尚未自动下载到本地。
QQ 出站文本有额外保护：最终回复和错误回复不会复用可能过期的入站 msg_id/event_id，超长文本会被限制在稳定可发送范围内并提示查看工作区产物，避免客户端出现“消息加载失败”。
用户在微信发送媒体后，网关自动下载、解密并保存到本地 media/ 目录，将文件路径附带到发给后端的消息中：
- 图片：PNG, JPG, JPEG, GIF, WEBP, BMP
- 语音：SILK 格式自动转码为 WAV
- 视频：MP4, MOV, WEBM, MKV, AVI
- 文件：PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT, CSV, ZIP, TAR, GZ
单文件上限 100MB。
后端回复中的媒体文件（本地路径或远程 URL）会被自动上传并发送给用户：
- 微信：根据 MIME 类型自动走 CDN 上传流程，支持图片、视频、文件
- Telegram：通过 Multipart FormData 发送，自动识别为
sendPhoto/sendVideo/sendDocument
Weixin 扫码登录、Telegram Bot Token、QQ 官方机器人 WebSocket / Webhook 的连接方式见 账号连接指南。