Popo-CC

通过网易 Popo 机器人远程操控本地 Claude Code。在手机上给机器人发消息，本地 Claude Code 自动执行并回复。

架构

Popo 用户
    │  STOMP 长连接
    ▼
Gateway 守护进程 (Bun)
    ├── 消息聚合 + 指令拦截
    ├── SQLite 入库
    ├── Bridge Socket (Unix socket)
    │         │
    │         ▼
    │   MCP Bridge（被 Claude Code spawn）
    │         │ stdio
    │         ▼
    │   Claude Code（tmux session，真实 TTY）
    │         │ popo_reply 工具
    │         ▼
    └── Popo REST API → 回复用户

Gateway 是独立守护进程，Claude Code 在 tmux session 中以交互模式运行。 MCP Bridge 由 Claude Code spawn，通过 Unix socket 与 Gateway 双向通信。

快速开始

1. 安装依赖

# 安装 tmux（Claude Code 需要真实 TTY）
brew install tmux

git clone <repo-url>
cd popo-remote-claudecode
bun install

2. 配置

在 Popo 机器人管理后台 创建或查看机器人凭据，然后初始化：

# 初始化配置和工作目录
bun run src/cli/index.ts init

编辑 ~/.config/popo-cc/config.json：

{
  "appId": "你的appId",
  "appKey": "你的appKey",
  "appSecret": "你的appSecret",
  "botName": "机器人名称",
  "aesKey": "32位AES密钥",
  "allowedSenders": ["[email protected]"],
  "leader_dir": "~/.config/popo-cc/leader",
  "aggregation_delay_ms": 500,
  "log_level": "info"
}

3. 前置依赖

| 依赖 | 说明 | |------|------| | Bun | JavaScript/TypeScript 运行时 | | tmux | 为 Claude Code 提供真实 TTY（brew install tmux） | | Claude Code | npm install -g @anthropic-ai/claude-code |

4. 启动

# 前台运行（开发用，Ctrl+C 停止）
bun run src/cli/index.ts start

# 后台运行
bun run src/cli/index.ts start --daemon

# 开机自启动
bun run src/cli/index.ts daemon install

启动后，Gateway 会在后台通过 tmux 启动 Claude Code 并自动确认提示。 在 Popo 上给机器人发消息即可开始使用。

5. 查看 Claude Code 运行状态

Claude Code 在 tmux 后台运行，随时可以接入查看完整 TUI 输出：

# 接入 Claude Code 的 tmux session，实时查看 TUI
tmux attach -t popo-cc

# 脱离查看（Ctrl+B 然后按 D），Claude Code 继续后台运行
Ctrl+B D

tmux 本身就是双模式 — 平时后台无感运行，想看时随时 attach。可以在 iTerm 里专门开一个标签长期 attach 着监控，关掉标签也不影响 Claude Code 运行。也可以通过 SSH 远程 attach 查看。

CLI 命令

popo-cc init [path]              # 初始化工作目录（默认 ~/.config/popo-cc/leader/）
popo-cc start [--daemon]         # 启动 Gateway
popo-cc stop                     # 停止 Gateway + Claude Code
popo-cc restart                  # 重启全部
popo-cc restart --claude-only    # 只重启 Claude Code（重建 tmux session）
popo-cc status                   # 查看运行状态
popo-cc logs                     # Gateway 日志（tail -f）
popo-cc logs --claude            # Claude Code 日志
popo-cc config list              # 列出配置
popo-cc config get <key>         # 查看配置项
popo-cc config set <key> <value> # 运行时改配置
popo-cc daemon install           # 安装 launchd 开机自启
popo-cc daemon uninstall         # 卸载
popo-cc daemon reinstall         # 重装

开发阶段用 bun run src/cli/index.ts 代替 popo-cc。

Popo 控制指令

在 Popo 聊天中发送以下指令，Gateway 直接处理（不转发给 Claude Code）：

| 指令 | 说明 | |------|------| | /restart | 重启 Claude Code（重建 tmux session） | | /status | 查看 Gateway 和 Claude Code 运行状态 | | /stop | 停止 Gateway | | /config | 查看当前配置 | | /config set <key> <value> | 修改配置 | | /help | 帮助信息 |

自定义 Leader 行为

Leader 的行为由 ~/.config/popo-cc/leader/CLAUDE.md 控制。你可以：

• 编辑 CLAUDE.md 修改调度规则
• 在 skills/ 目录添加自定义 skills
• 在 .claude/settings.local.json 配置权限

支持的消息类型

| 类型 | msgType | 说明 | |------|---------|------| | 普通文本 | 1 | 直接转发 | | 语音消息 | 141 | 自动语音转文字 | | 引用回复 | 211 | 包含引用上下文 | | 多条引用 | 213 | 多条引用列表 | | 文件消息 | 171 | 显示文件名和大小 | | 视频消息 | 142 | 显示视频文件名 | | 合并转发 | 161 | 摘要前 5 条 | | 云文档 | 182 | 云文档链接 | | 快捷指令 | - | 指令名称 + 变量参数 | | 撤回/编辑 | - | 事件通知 |

配置项

| 配置项 | 默认值 | 说明 | |--------|--------|------| | appId | - | Popo 开放平台 appId | | appKey | - | Popo 开放平台 appKey | | appSecret | - | Popo 开放平台 appSecret | | botName | - | 机器人名称 | | aesKey | - | 32 位 AES 密钥 | | allowedSenders | [] | 发送者白名单（空 = 不限制） | | leader_dir | ~/.config/popo-cc/leader | Leader 工作目录 | | aggregation_delay_ms | 500 | 消息聚合延迟（ms） | | claude_restart_max_retries | 5 | Claude Code 崩溃重启最大次数 | | log_level | info | 日志级别（debug/info/warn/error） | | log_max_size_mb | 10 | 单日志文件上限 | | log_max_files | 5 | 日志轮转保留数 |

文件布局

~/.config/popo-cc/
├── config.json           # 配置文件
├── popo-cc.db            # SQLite 数据库
├── gateway.sock          # CLI ↔ Gateway 通信
├── bridge.sock           # Gateway ↔ MCP Bridge 通信
├── gateway.pid           # PID 文件
├── leader/               # Leader 工作目录
│   ├── CLAUDE.md         # Leader 行为指令
│   ├── .claude/
│   │   └── settings.local.json
│   └── skills/           # 自定义 skills
└── logs/
    ├── gateway.log       # Gateway 日志
    └── claude.log        # Claude Code 日志

MCP 工具

Gateway 通过 MCP Bridge 向 Claude Code 暴露 5 个工具：

| 工具 | 说明 | |------|------| | popo_reply | 回复 Popo 用户（文本/图片） | | query_messages | 查询历史消息 | | update_task | 更新任务状态 | | report_progress | 更新多任务进度卡片（当前暂未完整支持） | | log_teammate | 记录 Teammate 执行日志 |

已知限制

• 流式卡片暂不支持：SessionWatcher 模块已保留但未启用，流式打字机效果尚未对接到 tmux 模式
• 多 Teammate 进度卡片：report_progress 工具存在但进度卡片推送依赖流式卡片能力，暂不可用
• tmux 必须安装：Claude Code 需要真实 TTY，必须预装 tmux

技术栈

• Runtime: Bun
• 语言: TypeScript
• 存储: SQLite (bun:sqlite)
• 协议: MCP (stdio) + STOMP over WebSocket
• TTY: tmux（Claude Code 运行环境）
• 加密: AES-128-CBC
• 认证: Popo 开放平台 appKey/appSecret

旧版兼容

原有的单体 popo-channel.ts 仍然保留，可通过以下方式使用：

claude --dangerously-load-development-channels server:popo

新架构推荐使用 popo-cc start 启动 Gateway。