wx-agent 是一个独立运行的企业微信 Agent。它通过企业微信智能机器人 WebSocket 长连接接收文本消息，调用 OpenAI 兼容模型，并可使用通用 MCP Server 与企业微信官方 MCP 工具回答问题或执行操作。
它不依赖 OpenClaw。企业微信连接基于官方 @wecom/aibot-node-sdk，扫码接入流程兼容企业微信官方 OpenClaw CLI 当前使用的授权方式。
- 首次启动终端扫码，凭据安全保存，后续自动登录
- 企业微信私聊和群聊文本消息、流式回复
- OpenAI 兼容的 Chat Completions 与工具调用
- MCP Streamable HTTP 和 stdio
- 企业微信联系人、文档、会议、日程、待办、消息等动态 MCP 品类
- SQLite 持久会话、消息去重、同会话串行处理
- 写操作发起人确认与超时取消
- CLI 诊断、Docker 和 Compose 部署
- 通过受控 tmux 会话远程启动并持续操作 Codex CLI
首版不处理图片、文件、语音、卡片、Webhook、自建应用模式、主动推送或多机器人。
- Node.js 24 或更高版本
- pnpm 11
- 支持 Chat Completions 流式输出和 function calling 的 OpenAI 兼容模型
- 如需 Codex 管理：Codex CLI、tmux，以及可用的 Codex 登录态
pnpm install
cp config.example.toml config.toml
cp .env.example .env编辑 .env：
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_API_KEY=replace-me
OPENAI_MODEL=gpt-4.1-mini启动开发版本：
pnpm dev首次启动会在终端展示企业微信二维码和网页链接。扫码成功后，凭据保存在 data/credentials.json，权限为 0600。后续启动不会重复扫码。
构建并运行：
pnpm build
node dist/cli.js startwx-agent start --config ./config.toml --data-dir ./data
wx-agent login --force --data-dir ./data
wx-agent logout --data-dir ./data
wx-agent doctor --config ./config.toml --data-dir ./data也可以设置 WECOM_BOT_ID 和 WECOM_BOT_SECRET 跳过扫码。环境变量始终优先于本地凭据文件。
企微聊天命令：
/help：查看帮助/status：查看企微及 MCP 状态/reset：清空当前私聊或群聊上下文/codex help：查看 Codex 会话命令确认 <ID>：执行本人发起的待审批工具调用取消 <ID>：取消本人发起的待审批工具调用
完整配置见 config.example.toml。字符串中的 ${ENV_NAME} 会在加载 TOML 后替换；变量缺失时，错误会指出具体配置路径。
[mcp.servers.knowledge]
transport = "streamable-http"
url = "${KNOWLEDGE_MCP_URL}"
timeout_ms = 30000
[mcp.servers.knowledge.headers]
Authorization = "Bearer ${KNOWLEDGE_MCP_TOKEN}"stdio 命令通过 command 和 args 直接启动，不经过 shell：
[mcp.servers.local_tools]
transport = "stdio"
command = "node"
args = ["./mcp/local-server.js"]
cwd = "."
[mcp.servers.local_tools.env]
SERVICE_TOKEN = "${SERVICE_TOKEN}"MCP 工具在模型侧命名为 mcp__<server>__<tool>。一个普通 MCP 连接失败不会阻止 Agent 启动。
[mcp.wecom]
enabled = true
categories = ["contact", "doc", "meeting", "schedule", "todo", "msg"]Agent 使用 wecom_mcp_list 查询品类工具，再用 wecom_mcp_call 调用。每个 MCP 会话按品类和当前发言人隔离，并向官方服务传递当前企业微信 userid。实际品类和工具取决于企业授权。
默认规则：
- MCP 标注为只读且非破坏性的工具自动执行。
- 企业微信工具名中独立包含
get、list、search或check的调用自动执行。 - 其他工具在企微中展示脱敏参数，等待原发起人确认。
- 每个会话仅保留一个待审批操作，默认 5 分钟过期，进程重启后作废。
可使用 glob 覆盖默认判断：
[approval]
read_only_tools = ["mcp__trusted__read_*"]
always_confirm_tools = ["*delete*", "*send*"]
expires_seconds = 300普通 MCP 使用服务级身份，并对所有被允许与机器人对话的用户开放。请确保 MCP 凭据和数据权限符合这一访问范围。
启用后，wx-agent 会在 tmux 中运行交互式 Codex CLI。每个会话都绑定创建者的企业微信 userid 和当前 chatid；其他用户、其他群聊或私聊都不能读取、输入或停止该会话。wx-agent 重启不会主动终止 tmux 中仍在执行的任务，重新启动后仍可继续查看和操作。
CodexManager 同时以工具注册给主 Agent，因此日常使用不需要记忆斜杠命令。例如可以直接发送：
在 r9s-main 用 gpt-5.6-sol 启动 Codex，检查失败测试并修复
查看刚才 Codex 的进度
让 Codex 继续运行测试并解释失败原因
停止刚才的 Codex 会话
主 Agent 会自行选择列出、启动、续聊、读取终端、操作菜单或停止 Codex 会话。列出和读取属于只读操作，会自动执行；启动、发送、按键和停止可能修改代码或进程，默认进入现有企微确认流程。斜杠命令仍保留，供模型不可用或需要精确人工控制时使用。
如果部署者确认允许主 Agent 无需逐次确认地管理 Codex，可显式放行相关工具：
[approval]
read_only_tools = ["codex_session_*"]
always_confirm_tools = []这会允许 Codex 修改已配置工作区，应仅在工作区沙箱和代码备份策略可接受时启用。
主 Agent 可以在允许的工作区执行受控命令，用于查看 Git 状态、搜索代码、运行测试或构建：
[command]
enabled = true
allowed_commands = ["git", "pnpm", "npm", "node", "rg", "ls", "pwd"]
allowed_workspaces = ["r9s-main"]
timeout_seconds = 120
max_output_bytes = 50000allowed_workspaces 引用 [codex.workspaces.<名称>] 中的路径。工具使用进程参数直接执行，不经过 shell，因此不支持 |、>、&&、变量展开或 $(...)。命令有独立超时和合并输出上限，超时后会终止命令进程组。
如需允许当前系统用户可执行的任意程序，可以使用完整通配符：
[command]
enabled = true
allowed_commands = ["*"]
allowed_workspaces = ["r9s-main"]allowed_commands 使用 glob 匹配完整命令字符串，例如 "git*"、"python?"、"/usr/local/bin/*"；不含通配符的值仍为精确匹配，独立的 "*" 匹配任意命令。不支持以 ! 开头的否定模式。通配符不会启用 shell，命令和参数仍通过 spawn 分开执行，但程序本身可能读写工作区之外的内容，因此强烈建议保留逐次确认并使用低权限系统用户运行 wx-agent。
可以直接对 Agent 说：
在 r9s-main 查看 git 状态
在 r9s-main 运行 pnpm test，并总结失败原因
用 rg 搜索项目里所有 TODO
命令参数可能具备访问工作区外资源的能力，实际边界仍取决于运行 wx-agent 的系统用户权限。agent_command_run 默认需要企微确认；如部署者接受风险，可通过 approval.read_only_tools 显式放行它。
先安装并登录 Codex CLI，再在 TOML 中明确列出允许操作的工作区：
[codex]
enabled = true
tmux_command = "tmux"
codex_command = "codex"
session_prefix = "wx-agent-codex"
max_sessions_per_user = 2
response_timeout_seconds = 180
poll_interval_ms = 750
stable_seconds = 4
capture_lines = 240
[codex.workspaces.wx-agent]
path = "/absolute/path/to/wx-agent"
sandbox = "workspace-write"
approval_policy = "never"
# model = "gpt-5.4"
# profile = "work"工作区名称只接受字母、数字、下划线和短横线。path 是部署者的显式允许列表，企微用户不能传入任意路径。当前版本固定要求 approval_policy = "never"，并只允许 read-only 或 workspace-write 沙箱：远程聊天无法可靠操作 Codex 的本地审批选择器，因此越界操作会失败，不会通过危险的全权限模式绕过保护。
企微命令：
/codex new wx-agent 修复失败的测试：使用工作区默认模型启动并提交首个任务/codex new wx-agent --model gpt-5.4 修复失败的测试：为本次会话指定模型/codex new wx-agent：只启动会话/codex list：列出本人在当前聊天中的会话/codex send abc123 继续实现并运行测试：继续交互/codex tail abc123：查看最近的终端输出/codex key abc123 down、/codex key abc123 enter：处理首次启动、更新提示或其他终端菜单；仅允许方向、确认、返回和中断键/codex stop abc123：停止会话
交互等待超时不会终止 Codex；任务会留在 tmux 中继续运行，可用 tail 查看进度。启动参数使用 Codex 的 --no-alt-screen 保存可捕获的终端历史，并使用 --sandbox 和 --ask-for-approval never 固定安全边界。Codex CLI 参数可参考官方命令行文档。
cp config.example.toml config.toml
cp .env.example .env
docker compose up --build二维码和扫码链接会出现在容器日志中，凭据与 SQLite 数据保存在 wx-agent-data 卷。stdio MCP 所需程序必须存在于容器内；可以基于本项目镜像扩展安装。
镜像已安装 tmux 和固定版本的 Codex CLI。Compose 会把当前项目挂载为 /workspace/wx-agent，并把宿主机 ${HOME}/.codex 挂载为容器内 Codex 登录目录；请确保该目录可由容器内 UID 1000 读取。若使用 API Key，也可按 Codex CLI 支持的方式向容器注入。启用示例工作区时，将路径设置为 /workspace/wx-agent。
pnpm typecheck
pnpm test
pnpm build真实企业微信和真实 MCP 的人工验收需要有效企业授权，自动化测试不会创建或修改企业数据。