cc-wechat-bot

在微信里和 Claude Code 对话。扫一次码，你的微信就变成 Claude Code 终端。

安装

npm install -g cc-wechat-bot@latest

需要已安装 Node.js >= 22 和 Claude Code。

快速开始

1. 登录（扫描微信二维码）

cc-wechat-bot login --name myname

浏览器会打开二维码页面。用微信扫码，并在手机上确认即可。

2. 启动守护进程

# 在你希望 Claude Code 工作的项目目录中运行
cd ~/my-project
cc-wechat-bot start myname

现在给已绑定的微信账号发消息，Claude Code 就会处理并回复。

3. 停止

cc-wechat-bot stop myname

使用 pm2 后台运行

如果你希望 cc-wechat-bot 在后台持续运行，并在机器重启后自动恢复，可以使用 pm2：

npm install -g pm2

# 在你希望 Claude Code 工作的项目目录中运行
cd ~/my-project
pm2 start cc-wechat-bot --name cc-wechat-bot -- start myname

# 查看日志
pm2 logs cc-wechat-bot

# 重启
pm2 restart cc-wechat-bot

# 停止
pm2 stop cc-wechat-bot

# 设置开机自启
pm2 save
pm2 startup

说明：

• pm2 start ... -- start myname 会把 start myname 传给 cc-wechat-bot。
• 当前工作目录依然很重要；请在目标项目目录里启动 pm2。
• 如果你使用多个微信账号，建议给每个进程使用不同的 pm2 名称。
• 如果 pm2 logs cc-wechat-bot 里提示“已在运行”，但微信没有回复，通常是残留的 login 进程占用了端口。可先执行 lsof -i :18081 -n -P 找到 PID，再执行 kill <PID>，确认端口释放后重新启动。

多账号

每个账号都有独立端口，彼此隔离：

cc-wechat-bot login --name work      # 端口 18081
cc-wechat-bot login --name personal  # 端口 18082（自动分配）

cc-wechat-bot start                  # 启动全部
cc-wechat-bot stop                   # 停止全部
cc-wechat-bot status                 # 查看全部状态

微信命令

用户可以在微信里发送这些命令：

| 命令 | 作用 | |------|------| | /new | 关闭当前会话，并新建一个会话 | | /exit 或 quit | 关闭当前会话 | | /help | 显示帮助 |

CLI 参考

cc-wechat-bot login [--name X]     Scan QR to login
cc-wechat-bot start [name]         Start daemon (one or all)
cc-wechat-bot stop [name]          Stop daemon (one or all)
cc-wechat-bot restart [name]       Restart daemon
cc-wechat-bot attach [name]        Attach/focus the active shared session
cc-wechat-bot status               Show all accounts & daemons
cc-wechat-bot rename old new       Rename an account

cc-wechat-bot --text "hello"       Reply to current WeChat context
cc-wechat-bot --image /tmp/s.png   Send image
cc-wechat-bot --file /tmp/f.pdf    Send file

cc-wechat-bot web [name]           Open ttyd Web Terminal in browser
cc-wechat-bot help                 Show help
cc-wechat-bot --version            Show version

配置

可选配置文件路径：~/.claude/channels/wechat-channel/config.json

{
  "delivery": "tmux",
  "backend": "claude-code",
  "port": 18081,
  "cwd": "/absolute/path/to/sandbox",
  "security": {
    "claudePermissionsMode": "default",
    "enableWebTerminal": false,
    "webTerminalWritable": false,
    "bindHost": "127.0.0.1",
    "requireExplicitCwd": true
  }
}

默认安全行为

• 默认使用 Claude 的普通权限确认模式。
• 默认关闭 Web Terminal。
• 如果启用 ttyd，默认绑定到 127.0.0.1，并且默认只读。
• 健康检查和二维码登录 HTTP 服务都绑定到 127.0.0.1。
• 会拒绝在过于宽泛的目录中启动，例如 ~ 或 ~/Documents/GitHub。
• 保存的账号文件会尽量强制设置为 0600 权限。

推荐用法：

• 在专用的 sandbox 或项目目录中运行 cc-wechat-bot。
• 不要在包含密钥、生产配置或无关私有仓库的目录里使用它。
• 只有在你确实需要浏览器访问时，才启用 security.enableWebTerminal。
• 只有在你明确接受风险时，才把 claudePermissionsMode 切换到 bypassPermissions 或 dangerously-skip-permissions。

security.claudePermissionsMode 支持的值：

• default
• bypassPermissions
• dangerously-skip-permissions

传输模式

当前仅支持 tmux 模式。

{
  "delivery": "tmux"
}

未显式配置时也会默认使用 tmux。除非显式开启，否则 Web Terminal 保持关闭。

使用前请确保本机已安装 tmux。

brew install tmux

或在 Linux 上使用对应包管理器安装。

apt install tmux

如果 tmux 不可用，daemon 会直接报错退出，而不会再回退到其他模式。

工作原理

WeChat App  -->  iLink Bot API (long-poll)  -->  cc-wechat-bot daemon  -->  Claude Code (tmux)
                                                      |                       |
                                                      v                       v
WeChat App  <--  iLink Bot API (send)       <--  Reply via WeChat API   ttyd Web Terminal
                                                                        (browser access)

• 不需要公网 IP — 完全运行在你的本地机器上
• 不需要云服务器 — 微信消息直接通过 iLink API 轮询
• 多会话 — 每个微信用户都有自己的 Claude Code tmux 会话
• 自动去 markdown — Claude 的 markdown 输出会清理成适合微信的纯文本
• 自动分片 — 长消息会按 3900 字符拆分

架构（v5）

当前固定使用 tmux 作为唯一运行模式：

• Tmux session：为每个微信用户维护一个独立的 Claude Code 会话
• Backend：使用 Claude Code CLI
• Router：把微信消息注入对应 tmux 会话，并将结果回发微信
• Attach：本地可随时附着到已有 tmux 会话继续操作

连接已有会话

如果某条微信消息已经创建了一个 Claude 会话，你可以在本地 CLI 里直接接入同一个共享会话：

cc-wechat-bot attach myname

• 这会对现有共享会话执行 tmux attach。
• attach 不会创建新会话；它只会连接到已经存在的会话。

Web Terminal

使用 tmux 传输模式时，cc-wechat-bot 可以通过 ttyd 暴露 Claude Code 会话的 Web Terminal，让你能在浏览器里查看或交互。

# 为指定账号打开 Web Terminal
cc-wechat-bot web myname

Web Terminal 默认关闭。要使用它，请在配置里把 security.enableWebTerminal 设为 true。cc-wechat-bot web 命令默认把 ttyd 绑定到 127.0.0.1，并以只读模式打开。

注意：ttyd 1.7.7+ 默认就是只读模式。除非你显式开启可写模式，否则本项目会保持这个默认值。可通过 brew install ttyd（macOS）或你的系统包管理器安装 ttyd。

运行要求

• Node.js >= 22
• 已安装 Claude Code CLI
• macOS / Linux 均可使用，但都依赖 tmux
• 使用前需先安装 tmux
• 如果 tmux 不可用，daemon 会直接报错退出

License

MIT