weacpx

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

这是什么

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。

安装

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。

你的日常使用流程

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

启动后台服务：weacpx start
创建或切换会话：/ss ...、/use ...
直接发普通文本：让当前会话继续工作
必要时查看状态或取消当前任务：/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 update [--all\|<name>]`	检查并更新 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 <name>`	从内置模板添加 agent；已存在且配置不同的同名 agent 不会被覆盖
`weacpx agent rm <name>`	删除 agent
`weacpx workspace list`	查看本机已注册的 workspace
`weacpx workspace add [name] [--raw]`	把当前目录注册成 workspace；不传 `name` 时使用当前目录名，含特殊字符的名称会被自动规范化
`weacpx workspace rm <name>`	删除 workspace

首次运行 weacpx start 或 weacpx run 时，如果没有会话、workspace 和插件，CLI 会询问是否把当前目录创建为 workspace，并选择一个内置 agent 模板；服务启动后会通过正常会话创建流程创建初始 acpx 会话。

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 add [name] --raw`	保留原始名称（含空格等），后续命令需要用引号引用
`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 名称。含空格、中文等字符的名称会被自动规范化为 [a-zA-Z0-9._-]+（例如目录 My Project 会保存为 My-Project），重名时追加 -2、-3。如需保留原始名称，加 --raw；之后 weacpx workspace rm、/ws rm、--ws <name> 都需要用引号引用，例如 weacpx workspace rm "My Project"。

`agent` CLI 怎么用

weacpx agent 用来在电脑本机维护 ~/.weacpx/config.json 里的 agents 配置；agents 是同等别名。

命令	说明
`weacpx agent list`	列出已注册的 agent
`weacpx agent templates`	列出可添加的内置模板
`weacpx agent add <name>`	从内置模板添加 agent，例如 `kimi`、`opencode`
`weacpx agent rm <name>`	删除指定 agent

常见用法：

weacpx agent templates
weacpx agent add kimi
weacpx agents list
weacpx agent rm kimi

`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。如果你要使用其它 acpx 支持的 agent，可以先用 /agent add <name> 从内置模板添加。

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

当前内置模板与 acpx 的 built-in agents 对齐：

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/config-reference.md。

Workspace 管理

命令	说明
`/workspaces` / `/workspace` / `/ws`	查看 workspace 列表
`/ws new <name> -d <path> [--raw]`	添加 workspace，`path` 是电脑上的绝对路径，Windows 不用区分正反斜杠；含空格/中文等特殊字符的名称会被自动规范化，--raw 保留原名
`/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>`	快速委派一个子任务
`/tasks`	查看当前主线下的任务
`/task <id>`	查看单个任务详情
`/task approve <id>`	批准 `needs_confirmation` 任务
`/task cancel <id>`	取消任务；取消一个尚未批准的任务等同于拒绝

最常见例子：

/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

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：

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 命令格式错了，而是底层会话没有成功创建。

你可以先试这两步：

在终端里确认当前项目目录和 agent 本身可用
如果你熟悉 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

Name		Name	Last commit message	Last commit date
Latest commit History 264 Commits
.github/workflows		.github/workflows
assets		assets
docs		docs
packages		packages
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
bun.lock		bun.lock
bunfig.toml		bunfig.toml
config.example.json		config.example.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsconfig.plugin-api.json		tsconfig.plugin-api.json

Folders and files

Latest commit

History

Repository files navigation

weacpx

这是什么

适合谁

5 分钟快速开始

前置条件

安装

登录微信

启动服务

在微信里创建第一个会话

切换/添加其它频道

你的日常使用流程

1) 创建会话

2) 发普通消息

3) 看回复

4) 切换会话

常用 CLI 命令

workspace CLI 怎么用

agent CLI 怎么用

doctor 怎么用

常用聊天命令

Agent 管理

Workspace 管理

Session 会话

配置与权限

多 Agent 编排

MCP 集成：外部 coordinator

常见场景

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

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

配置与运行文件

常见问题

/ss new 失败怎么办？

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

从源码运行

更多文档

安装与配置

日常使用

排错与验证

开发与贡献

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 35

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`workspace` CLI 怎么用

`agent` CLI 怎么用

`doctor` 怎么用

`/ss new` 失败怎么办？

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

Packages