https://github.com/gadzan/weacpx
用微信 ClawBot 远程控制 Codex/Claude Code/Gemini/OpenCode 会话的服务
https://github.com/gadzan/weacpx
acpx claude-code codex gemini opencode weixin-agent-sdk
Last synced: 21 days ago
JSON representation
用微信 ClawBot 远程控制 Codex/Claude Code/Gemini/OpenCode 会话的服务
- Host: GitHub
- URL: https://github.com/gadzan/weacpx
- Owner: gadzan
- License: mit
- Created: 2026-03-26T11:46:20.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-05-19T09:05:33.000Z (26 days ago)
- Last Synced: 2026-05-19T11:28:09.663Z (26 days ago)
- Topics: acpx, claude-code, codex, gemini, opencode, weixin-agent-sdk
- Language: TypeScript
- Homepage:
- Size: 1.64 MB
- Stars: 6
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# weacpx
> 用微信、飞书或元宝远程驱动 Codex、Claude Code 等 acpx 会话。
[](https://www.npmjs.com/package/weacpx)
[](https://nodejs.org)
[](https://zread.ai/gadzan/weacpx)
[](./LICENSE)
## 这是什么
`weacpx` 是一个可以通过微信、飞书或元宝直接控制 Codex / Claude Code / Gemini / OpenCode 等 ACP Agent 的工具。它把聊天消息通过 `acpx` 连接到 Agent CLI 会话上，让你直接在手机里：
- 新建和切换会话
- 让 Agent 继续在指定项目目录里工作
- 查看流式回复、最终结果和工具调用摘要
- 调整权限策略
- 在需要时做多 Agent 编排
如果你需要临时远程编码或办公，`weacpx` 提供的是一个方便快捷的**远程入口**，让你在微信或飞书里就能随时随地干活。
## 适合谁
`weacpx` 适合轻量临时使用多 Agent 办公的用户。你可以用微信、飞书或元宝盯任务、发指令、看结果，并在同一个聊天里管理多个会话。
> `weacpx` 的会话是跟本地隔离的，它目前还不能使用 CLI 已有的会话，你在 weacpx 也无法看到本地的 CLI 会话记录。
## 5 分钟快速开始
### 前置条件
开始前，你至少需要：
- Node.js 22+ 或 Bun
- 已可用的 Codex / Claude Code / Gemini / OpenCode 等你要使用的 Agent CLI
- 一台装了微信、飞书或元宝的手机
> 微信频道基于 `weixin-agent-sdk` 工作，飞书频道使用飞书自建应用凭据，元宝频道使用 `appKey` / `appSecret`；底层 Agent 会话由 `acpx` 驱动。正常情况下，你不需要额外全局安装 `acpx`。
### 安装
```bash
npm install -g weacpx --registry=https://registry.npmjs.org
# 或
bun add -g weacpx
```
### 登录微信
```bash
weacpx login
```
终端会显示二维码，请继续用微信扫码登录。
如果你想使用飞书或元宝而不是微信，请先看下面的“切换/添加其它频道”。
### 启动服务
```bash
weacpx start
```
### 在微信里创建第一个会话
把下面两条消息发到微信：
```text
/ss codex -d /absolute/path/to/your/repo
/help
```
然后直接发普通文本，例如：
```text
hello
```
如果一切正常，普通文本会进入当前会话，Agent 的回复会回到微信。
### 切换/添加其它频道
微信是内置默认频道。飞书和元宝以官方插件包分发，第三方频道也走同样的插件流程。如果记不住包名，先看一眼官方插件清单：
```bash
weacpx plugin known
# 安装：weacpx plugin add
```
```bash
# 飞书
weacpx plugin add @ganglion/weacpx-channel-feishu
weacpx channel add feishu # 按提示输入 appId/appSecret
weacpx restart
# 元宝
weacpx plugin add @ganglion/weacpx-channel-yuanbao
weacpx channel add yuanbao # 按提示输入 appKey/appSecret
weacpx restart
```
完整的密钥配置、参数、`enable/disable/rm` 等管理命令见 [docs/channel-management.md](./docs/channel-management.md)。如果你想自己写一个频道插件，见 [docs/plugin-development.md](./docs/plugin-development.md)。
## 你的日常使用流程
最常见的使用顺序只有四步：
1. **启动后台服务**：`weacpx start`
2. **创建或切换会话**：`/ss ...`、`/use ...`
3. **直接发普通文本**：让当前会话继续工作
4. **必要时查看状态或取消当前任务**：`/status`、`/cancel`
### 1) 创建会话
最常用命令：
```text
/ss codex -d /absolute/path/to/your/repo
```
它会使用 `codex`，绑定这个工作目录，并自动切换到新会话。
### 2) 发普通消息
非 `/` 开头的文本，都会发送到当前会话。
```text
修一下最近这个接口超时问题
```
### 3) 看回复
`weacpx` 支持三种常用回复模式：
- `stream`：流式返回中间文本
- `final`：只返回最终结果
- `verbose`：默认，在流式文本之外，额外显示工具调用摘要
例如 `verbose` 模式下，你会看到：
```text
📖 sed -n '1,220p' README.md
🔍 rg -n 'session new' src tests
💻 bun test tests/unit/main.test.ts
✏️ Edit parse-command.ts
```
### 4) 切换会话
```text
/ss
/use backend:codex
```
这样你可以在同一个微信聊天里切换不同项目、不同 agent 的会话。
## 常用 CLI 命令
这些命令在电脑终端里运行。
| 命令 | 说明 |
|------|------|
| `weacpx login` | 登录微信 |
| `weacpx logout` | 清除本机保存的微信登录凭证 |
| `weacpx run` | 前台运行，适合调试 |
| `weacpx start` | 后台启动服务 |
| `weacpx status` | 查看后台状态、PID、配置路径、日志路径 |
| `weacpx stop` | 停止后台实例 |
| `weacpx restart` | 重启后台实例，让频道配置变更生效 |
| `weacpx update [--all\|]` | 检查并更新 weacpx 与已安装插件；安装了插件时会交互式选择更新项 |
| `weacpx channel list` | 查看已配置的消息频道 |
| `weacpx plugin known` | 查看官方插件清单（飞书/元宝包名） |
| `weacpx plugin add @ganglion/weacpx-channel-feishu && weacpx channel add feishu` | 安装并添加飞书频道，会提示输入飞书应用凭据 |
| `weacpx plugin add @ganglion/weacpx-channel-yuanbao && weacpx channel add yuanbao` | 安装并添加元宝频道，会提示输入元宝 appKey/appSecret |
| `weacpx doctor` | 运行环境诊断 |
| `weacpx version` | 查看当前版本 |
| `weacpx agent list` | 查看本机已注册的 agent |
| `weacpx agent add ` | 从内置模板添加 agent；已存在且配置不同的同名 agent 不会被覆盖 |
| `weacpx agent rm ` | 删除 agent |
| `weacpx workspace list` | 查看本机已注册的 workspace |
| `weacpx workspace add [name] [--raw]` | 把当前目录注册成 workspace；不传 `name` 时使用当前目录名，含特殊字符的名称会被自动规范化 |
| `weacpx workspace rm ` | 删除 workspace |
首次运行 `weacpx start` 或 `weacpx run` 时，如果没有会话、workspace 和插件，CLI 会询问是否把当前目录创建为 workspace，并选择一个内置 agent 模板；服务启动后会通过正常会话创建流程创建初始 acpx 会话。
`workspace` 也可以简写为 `ws`：
```bash
weacpx ws add
weacpx ws list
weacpx ws rm backend
```
### `workspace` CLI 怎么用
`weacpx workspace` 用来在电脑本机维护 `~/.weacpx/config.json` 里的 `workspaces` 配置。它适合先在终端里注册常用项目目录，然后在微信里用 `--ws ` 直接引用。
| 命令 | 说明 |
|------|------|
| `weacpx workspace list` | 列出已注册的 workspace 及其路径 |
| `weacpx workspace add` | 把当前目录注册为 workspace，名称默认取当前目录名（自动规范化） |
| `weacpx workspace add ` | 把当前目录注册为指定名称（含特殊字符时自动规范化） |
| `weacpx workspace add [name] --raw` | 保留原始名称（含空格等），后续命令需要用引号引用 |
| `weacpx workspace rm ` | 删除指定 workspace |
常见用法：
```bash
cd /absolute/path/to/backend
weacpx workspace add backend
cd /absolute/path/to/frontend
weacpx ws add frontend
weacpx ws list
weacpx ws rm frontend
```
注册后，你可以在微信里直接使用：
```text
/ss codex --ws backend
/ss new claude --ws frontend
```
注意：`workspace add` 总是注册**当前终端所在目录**。如果不传名称，会用当前目录名作为 workspace 名称。含空格、中文等字符的名称会被自动规范化为 `[a-zA-Z0-9._-]+`（例如目录 `My Project` 会保存为 `My-Project`），重名时追加 `-2`、`-3`。如需保留原始名称，加 `--raw`；之后 `weacpx workspace rm`、`/ws rm`、`--ws ` 都需要用引号引用，例如 `weacpx workspace rm "My Project"`。
### `agent` CLI 怎么用
`weacpx agent` 用来在电脑本机维护 `~/.weacpx/config.json` 里的 `agents` 配置；`agents` 是同等别名。
| 命令 | 说明 |
|------|------|
| `weacpx agent list` | 列出已注册的 agent |
| `weacpx agent templates` | 列出可添加的内置模板 |
| `weacpx agent add ` | 从内置模板添加 agent，例如 `kimi`、`opencode` |
| `weacpx agent rm ` | 删除指定 agent |
常见用法：
```bash
weacpx agent templates
weacpx agent add kimi
weacpx agents list
weacpx agent rm kimi
```
### `doctor` 怎么用
```bash
weacpx doctor
weacpx doctor --verbose
weacpx doctor --smoke
weacpx doctor --smoke --agent codex --workspace backend
```
说明：
- `--verbose` 会展开每项检查的细节
- `--smoke` 会额外执行一次真实 transport 级别的最小 prompt 检查
- `--agent` / `--workspace` 只影响 `--smoke`
- 如果不传 `--smoke`，相关检查会显示为 `SKIP`
## 常用聊天命令
这些命令在微信或飞书聊天里发送。完整命令参考见：[docs/commands.md](./docs/commands.md)。
### Agent 管理
默认配置通常已包含 `codex` 与 `claude`。如果你要使用其它 acpx 支持的 agent，可以先用 `/agent add ` 从内置模板添加。
| 命令 | 说明 |
|------|------|
| `/agents` | 查看 agent 列表 |
| `/agent add gemini` | 添加 `Gemini` Agent |
| `/agent add opencode` | 添加 `OpenCode` Agent |
| `/agent rm ` | 删除 agent |
当前内置模板与 acpx 的 built-in agents 对齐：
```text
codex, claude, pi, openclaw, gemini, cursor, copilot, droid,
factory-droid, factorydroid, iflow, kilocode, kimi, kiro,
opencode, qoder, qwen, trae
```
这些模板只写入 `driver`，实际启动命令交给 acpx 解析；例如 `/agent add kimi` 会保存 `{ "driver": "kimi" }`。完整命令说明见 [docs/commands.md](./docs/commands.md)，配置字段见 [docs/config-reference.md](./docs/config-reference.md)。
### Workspace 管理
| 命令 | 说明 |
|------|------|
| `/workspaces` / `/workspace` / `/ws` | 查看 workspace 列表 |
| `/ws new -d [--raw]` | 添加 workspace，`path` 是电脑上的绝对路径，Windows 不用区分正反斜杠；含空格/中文等特殊字符的名称会被自动规范化，--raw 保留原名 |
| `/workspace rm ` | 删除 workspace |
### Session 会话
| 命令 | 说明 |
|------|------|
| `/sessions` / `/session` / `/ss` | 查看会话列表 |
| `/ss (-d \| --ws )` | 创建或复用当前最常用的会话 |
| `/ss new (-d \| --ws )` | 强制新建会话 |
| `/use ` | 切换当前会话 |
| `/status` | 查看当前会话状态 |
| `/mode` / `/mode ` | 查看或设置底层 `acpx` mode |
| `/replymode` | 查看当前回复模式 |
| `/replymode stream` | 流式回复 |
| `/replymode verbose` | 流式 + 工具调用摘要 |
| `/replymode final` | 只返回最终结果 |
| `/replymode reset` | 回退到全局默认 reply mode |
| `/session reset` | 重置当前会话上下文 |
| `/clear` | `/session reset` 的快捷别名 |
| `/cancel` / `/stop` | 停止当前任务 |
建议你优先记住这三个：
```text
/ss codex -d /absolute/path/to/repo
/use
/cancel
```
### 定时任务（/later）
让 agent 在未来某个时间自动收到一条消息。任务绑定「创建时的当前会话」，到点后把这条消息作为普通 prompt 发给那个会话。
| 命令 | 说明 |
|------|------|
| `/lt <时间> <消息>` | 创建一次性定时任务（`/later` 同义） |
| `/lt list` | 查看全局待执行任务 |
| `/lt cancel ` | 取消待执行任务 |
最常见例子：
```text
/lt in 2h 检查 CI 是否通过
/lt 明天 09:00 看 PR
/lt list
```
说明：
- 只支持一次性任务，时间必须在 10 秒之后、7 天之内
- 时间格式是固定白名单（相对时间 / 今天·明天·后天 / 星期几 + 时刻），不支持自然语言
- 完整时间格式、任务状态与限制见 [docs/later-command.md](./docs/later-command.md)
### 配置与权限
| 命令 | 说明 |
|------|------|
| `/config` | 查看支持通过聊天命令修改的配置路径 |
| `/config set ` | 修改一个白名单配置项 |
| `/pm` / `/permission` | 查看当前权限模式 |
| `/pm set allow` | 切到 `approve-all` |
| `/pm set read` | 切到 `approve-reads` |
| `/pm set deny` | 切到 `deny-all` |
| `/pm auto` | 查看当前非交互权限策略 |
| `/pm auto deny` | 切到 `deny` |
| `/pm auto fail` | 切到 `fail` |
最常见例子：
```text
/config set wechat.replyMode final
/pm set read
/pm auto deny
```
### 多 Agent 编排
README 里只保留用户视角的最常用命令。
| 命令 | 说明 |
|------|------|
| `/dg ` | 快速委派一个子任务 |
| `/tasks` | 查看当前主线下的任务 |
| `/task ` | 查看单个任务详情 |
| `/task approve ` | 批准 `needs_confirmation` 任务 |
| `/task cancel ` | 取消任务；取消一个尚未批准的任务等同于拒绝 |
最常见例子：
```text
/dg claude 审查当前方案的 3 个高风险点
/tasks
/task approve task_123
```
说明：
- 当前会话就是主控会话
- 被委派出去的是独立子任务会话
- agent 发起的委派请求默认需要人工确认
- 如果你在用外部 MCP host（Codex / Claude Code），用 `delegate_batch` 一次派发多个并行子任务：传一个 `tasks` 数组，底层自动建组，全部结果一次性回注，无需手动维护 groupId
如果你想先理解什么时候该用 delegate、什么时候应该并行派出多个子任务，请看：
- [docs/weacpx-group-usage-guide.md](./docs/weacpx-group-usage-guide.md)
### MCP 集成：外部 coordinator
如果你想让 Codex、Claude Code 等外部 MCP host 直接使用 weacpx 的多 Agent 编排能力，可以把 `weacpx mcp-stdio` 配成一个 stdio MCP server。
`delegate_request` 支持 MCP Tasks：支持该能力的 host 可以让委派请求立即返回原生 task handle，之后通过 `tasks/get` / `tasks/result` / `tasks/cancel` 获取状态、结果或取消任务；worker 输出的 `[PROGRESS] ...` 会显示在 `tasks/get` / `tasks/list` 的 `statusMessage` 里；`input_required` 状态下的 `tasks/result` 会返回下一步操作提示并结束本次 result stream，而不是长时间阻塞；client 按提示调用 `task_get` / `task_approve` / `coordinator_answer_question` 等工具后，再继续 `tasks/get` / `tasks/result` 轮询。不支持 MCP Tasks 的 host 仍可使用兼容工具 `task_get` / `task_list` / `task_watch` / `task_cancel`。
先启动 daemon：
```bash
weacpx start
```
MCP 配置推荐保持简单，不要在启动参数里绑定 workspace：
```json
{
"mcpServers": {
"weacpx": {
"command": "weacpx",
"args": ["mcp-stdio"]
}
}
}
```
外部 host 调用 `delegate_request` 时传 `workingDirectory`，weacpx 会让被委派的 worker 在这个目录工作：
```json
{
"targetAgent": "claude",
"task": "审查这个改动的风险点",
"workingDirectory": "/absolute/path/to/your/repo"
}
```
Windows 上如果 MCP host 不会帮你解析带参数的 `command`，把 `node.exe` 放在 `command`，把 weacpx 脚本和参数放在 `args`：
```json
{
"type": "stdio",
"command": "D:\\Users\\you\\.nvmd\\versions\\22.19.0\\node.exe",
"args": [
"E:\\projects\\weacpx\\dist\\cli.js",
"mcp-stdio"
]
}
```
更多身份规则、`workingDirectory` 语义、工具列表、流程图和故障排查见：[docs/external-mcp.md](./docs/external-mcp.md)。
## 常见场景
### 在手机上继续盯一个本地项目
```text
/ss codex -d /absolute/path/to/backend
看一下今天这个接口超时问题
```
### 同一个聊天里切换两个项目
```text
/ss codex -d /absolute/path/to/backend
/ss new codex -d /absolute/path/to/frontend
/ss
/use backend:codex
/use frontend:codex
```
## 配置与运行文件
默认文件位置：
- 配置文件：`~/.weacpx/config.json`
- 状态文件：`~/.weacpx/state.json`
- 运行日志：`~/.weacpx/runtime/app.log`
更多运行时文件会放在 `~/.weacpx/runtime/` 下。
## 常见问题
### `/ss new` 失败怎么办？
如果你在微信里创建会话失败，最常见的情况不是 `weacpx` 命令格式错了，而是底层会话没有成功创建。
你可以先试这两步：
1. 在终端里确认当前项目目录和 agent 本身可用
2. 如果你熟悉 `acpx`，先手动创建一个会话，再在微信里挂回去
例如，你可以先在本地创建一个会话：
```bash
./node_modules/.bin/acpx --verbose --cwd /absolute/workspace/path codex sessions new --name existing-demo
```
然后在微信里把它挂回来：
```text
/ss attach demo -a codex --ws backend --name existing-demo
```
### `/mode ` 里的 `` 是什么？
`/mode` 的可用值取决于你当前使用的 agent，`weacpx` 不会替你统一转换这些值。
当前比较明确的已知值：
- `codex`: `plan`
- `cursor`: `agent`、`plan`、`ask`
如果你不确定某个值能不能用，优先查对应 agent 的文档；如果填错，通常会直接收到无效参数之类的报错。
## 从源码运行
如果你是从仓库源码直接使用：
```bash
bun install
bun run login
bun run dev
```
## 更多文档
如果你现在要做的是下面这些事，可以直接从这里继续：
### 安装与配置
- 想配置微信、飞书、元宝、或第三方插件频道：[docs/channel-management.md](./docs/channel-management.md)
- 想自己写一个频道插件：[docs/plugin-development.md](./docs/plugin-development.md)
- 想看完整配置字段：[docs/config-reference.md](./docs/config-reference.md)
- 想在微信里改配置：[docs/config-command.md](./docs/config-command.md)
### 日常使用
- 想查看完整聊天命令参考：[docs/commands.md](./docs/commands.md)
- 想用定时任务（`/later`）安排一次性的未来消息：[docs/later-command.md](./docs/later-command.md)
- 想理解什么时候该用 delegate、什么时候该开 group：[docs/weacpx-group-usage-guide.md](./docs/weacpx-group-usage-guide.md)
### 排错与验证
- 想跑测试或了解测试分层：[docs/testing.md](./docs/testing.md)
### 开发与贡献
- 想从源码开发、调试或参与贡献：[docs/developments.md](./docs/developments.md)