weacpx

用微信、飞书或元宝远程驱动 Codex、Claude Code 等 acpx 会话。

这是什么

weacpx 是一个可以通过微信、飞书或元宝直接控制 Codex / Claude Code / Gemini / OpenCode 的工具。它把聊天消息通过 acpx 连接到 Agent CLI 会话上，让你直接在手机里：

• 新建和切换会话
• 让 Agent 继续在指定项目目录里工作
• 查看流式回复、最终结果和工具调用摘要
• 调整权限策略
• 在需要时做多 Agent 编排

如果你需要临时远程编码或办公，weacpx 提供的是一个方便快捷的远程入口，让你在微信或飞书里就能随时随地干活。

适合谁

weacpx 适合轻量临时使用多 Agent 办公的用户。你可以用微信、飞书或元宝盯任务、发指令、看结果，并在同一个聊天里管理多个会话。

weacpx 的会话是跟本地隔离的，它目前还不能使用 CLI 已有的会话，你在 weacpx 也无法看到本地的 CLI 会话记录。

5 分钟快速开始

前置条件

开始前，你至少需要：

• Node.js 22+ 或 Bun
• 已可用的 Codex / Claude Code / Gemini / OpenCode
• 一台装了微信、飞书或元宝的手机

微信频道基于 weixin-agent-sdk 工作，飞书频道使用飞书自建应用凭据，元宝频道使用 appKey / appSecret；底层 Agent 会话由 acpx 驱动。正常情况下，你不需要额外全局安装 acpx。

安装

npm install -g weacpx --registry=https://registry.npmjs.org
# 或
bun add -g weacpx

登录微信

weacpx login

终端会显示二维码，请继续用微信扫码登录。

如果你想使用飞书或元宝而不是微信，请先看下面的“切换/添加其它频道”。

启动服务

weacpx start

在微信里创建第一个会话

把下面两条消息发到微信：

/ss codex -d /absolute/path/to/your/repo
/help

然后直接发普通文本，例如：

hello

如果一切正常，普通文本会进入当前会话，Agent 的回复会回到微信。

切换/添加其它频道

微信是内置默认频道。飞书和元宝以官方插件包分发，第三方频道也走同样的插件流程。如果记不住包名，先看一眼官方插件清单：

weacpx plugin known
# 安装：weacpx plugin add <package>

# 飞书
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/plugin-development.md。

你的日常使用流程

最常见的使用顺序只有四步：

1. 启动后台服务：weacpx start
2. 创建或切换会话：/ss ...、/use ...
3. 直接发普通文本：让当前会话继续工作
4. 必要时查看状态或取消当前任务：/status、/cancel

1) 创建会话

最常用命令：

/ss codex -d /absolute/path/to/your/repo

它会使用 codex，绑定这个工作目录，并自动切换到新会话。

2) 发普通消息

非 / 开头的文本，都会发送到当前会话。

修一下最近这个接口超时问题

3) 看回复

weacpx 支持三种常用回复模式：

• stream：流式返回中间文本
• final：只返回最终结果
• verbose：默认，在流式文本之外，额外显示工具调用摘要

例如 verbose 模式下，你会看到：

📖 sed -n '1,220p' README.md
🔍 rg -n 'session new' src tests
💻 bun test tests/unit/main.test.ts
✏️ Edit parse-command.ts

4) 切换会话

/ss
/use backend:codex

这样你可以在同一个微信聊天里切换不同项目、不同 agent 的会话。

常用 CLI 命令

这些命令在电脑终端里运行。

命令	说明
weacpx login	登录微信
weacpx logout	清除本机保存的微信登录凭证
weacpx run	前台运行，适合调试
weacpx start	后台启动服务
weacpx status	查看后台状态、PID、配置路径、日志路径
weacpx stop	停止后台实例
weacpx restart	重启后台实例，让频道配置变更生效
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 workspace list	查看本机已注册的 workspace
weacpx workspace add [name]	把当前目录注册成 workspace；不传 name 时使用当前目录名
weacpx workspace rm <name>	删除 workspace

workspace 也可以简写为 ws：

weacpx ws add
weacpx ws list
weacpx ws rm backend

workspace CLI 怎么用

weacpx workspace 用来在电脑本机维护 ~/.weacpx/config.json 里的 workspaces 配置。它适合先在终端里注册常用项目目录，然后在微信里用 --ws <name> 直接引用。

命令	说明
weacpx workspace list	列出已注册的 workspace 及其路径
weacpx workspace add	把当前目录注册为 workspace，名称默认取当前目录名
weacpx workspace add <name>	把当前目录注册为指定名称
weacpx workspace rm <name>	删除指定 workspace

常见用法：

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

注册后，你可以在微信里直接使用：

/ss codex --ws backend
/ss new claude --ws frontend

注意：workspace add 总是注册当前终端所在目录；如果不传名称，会用当前目录名作为 workspace 名称。

doctor 怎么用

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。

Agent 管理

已内置常用的 Codex 与 Claude Code；

可以使用 /agent add opencode 添加你所需要的 agents。

命令	说明
/agents	查看 agent 列表
/agent add gemini	添加 Gemini Agent
/agent add opencode	添加 OpenCode Agent
/agent rm <name>	删除 agent

Workspace 管理

命令	说明
/workspaces / /workspace / /ws	查看 workspace 列表
/ws new <name> -d <path>	添加 workspace，path 是电脑上的绝对路径，Windows 不用区分正反斜杠
/workspace rm <name>	删除 workspace

Session 会话

命令	说明
/sessions / /session / /ss	查看会话列表
/ss <agent> (-d <path> | --ws <name>)	创建或复用当前最常用的会话
/ss new <agent> (-d <path> | --ws <name>)	强制新建会话
/use <alias>	切换当前会话
/status	查看当前会话状态
/mode / /mode <id>	查看或设置底层 acpx mode
/replymode	查看当前回复模式
/replymode stream	流式回复
/replymode verbose	流式 + 工具调用摘要
/replymode final	只返回最终结果
/replymode reset	回退到全局默认 reply mode
/session reset	重置当前会话上下文
/clear	/session reset 的快捷别名
/cancel / /stop	停止当前任务

建议你优先记住这三个：

/ss codex -d /absolute/path/to/repo
/use <alias>
/cancel

配置与权限

命令	说明
/config	查看支持通过聊天命令修改的配置路径
/config set <path> <value>	修改一个白名单配置项
/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

最常见例子：

/config set wechat.replyMode final
/pm set read
/pm auto deny

多 Agent 编排

README 里只保留用户视角的最常用命令。

命令	说明
/dg <agent> <task>	快速委派一个子任务
/group new <title>	创建任务组
/group add <groupId> <agent> <task>	往任务组里加子任务
/groups	查看任务组列表
/group <id>	查看单个任务组
/group cancel <groupId>	取消组内未结束任务
/tasks	查看当前主线下的任务
/task <id>	查看单个任务详情
/task approve <id>	批准 needs_confirmation 任务
/task cancel <id>	取消任务

最常见例子：

/dg claude 审查当前方案的 3 个高风险点
/group new review
/group add review claude 审查接口设计
/tasks
/task approve task_123

说明：

• 当前会话就是主控会话
• 被委派出去的是独立子任务会话
• agent 发起的委派请求默认需要人工确认
• group 适合把 2~3 个独立子任务并行派出去，再把结果汇总回主线

如果你想先理解什么时候该用 delegate、什么时候该开 group，请看：

• docs/weacpx-group-usage-guide.md

MCP 集成：外部 coordinator

如果你想让 Codex、Claude Code 等外部 MCP host 直接使用 weacpx 的多 Agent 编排能力，可以把 weacpx mcp-stdio 配成一个 stdio MCP server。

先启动 daemon：

weacpx start

MCP 配置推荐保持简单，不要在启动参数里绑定 workspace：

{
  "mcpServers": {
    "weacpx": {
      "command": "weacpx",
      "args": ["mcp-stdio"]
    }
  }
}

外部 host 调用 delegate_request 时传 workingDirectory，weacpx 会让被委派的 worker 在这个目录工作：

{
  "targetAgent": "claude",
  "task": "审查这个改动的风险点",
  "workingDirectory": "/absolute/path/to/your/repo"
}

Windows 上如果 MCP host 不会帮你解析带参数的 command，把 node.exe 放在 command，把 weacpx 脚本和参数放在 args：

{
  "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。

常见场景

在手机上继续盯一个本地项目

/ss codex -d /absolute/path/to/backend
看一下今天这个接口超时问题

同一个聊天里切换两个项目

/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，先手动创建一个会话，再在微信里挂回去

例如，你可以先在本地创建一个会话：

./node_modules/.bin/acpx --verbose --cwd /absolute/workspace/path codex sessions new --name existing-demo

然后在微信里把它挂回来：

/ss attach demo -a codex --ws backend --name existing-demo

/mode <id> 里的 <id> 是什么？

/mode 的可用值取决于你当前使用的 agent，weacpx 不会替你统一转换这些值。

当前比较明确的已知值：

• codex: plan
• cursor: agent、plan、ask

如果你不确定某个值能不能用，优先查对应 agent 的文档；如果填错，通常会直接收到无效参数之类的报错。

从源码运行

如果你是从仓库源码直接使用：

bun install
bun run login
bun run dev

更多文档

如果你现在要做的是下面这些事，可以直接从这里继续：

安装与配置

• 想配置微信、飞书、元宝、或第三方插件频道：docs/channel-management.md
• 想自己写一个频道插件：docs/plugin-development.md
• 想看完整配置字段：docs/config-reference.md
• 想在微信里改配置：docs/config-command.md

日常使用

• 想查看完整聊天命令参考：docs/commands.md
• 想理解什么时候该用 delegate、什么时候该开 group：docs/weacpx-group-usage-guide.md

排错与验证

• 想跑测试或了解测试分层：docs/testing.md

开发与贡献

• 想从源码开发、调试或参与贡献：docs/developments.md