wechat-agent

在微信里操控任意 AI Agent。一行命令，即刻接入。

微信  ───>  iLink 协议  ───>  桥接服务  ───>  任意 AI 终端  ───>  微信回复

English | 中文文档

为什么做这个

你的 Mac 上装着 Claude Code、Codex —— 但只能坐在电脑前用。

如果出门在外，也能用微信远程操控呢？

本项目通过腾讯 2026 年官方开放的 iLink 协议，将微信消息桥接到任意终端 AI Agent。不是逆向破解，是有《微信ClawBot功能使用条款》背书的官方接口。

三步上手

# 安装
npm install -g wechat-agent@latest

# 扫码登录 —— 终端弹出二维码，用微信扫一扫
wechat-agent setup

# 启动 —— 搞定，在微信里发消息试试
wechat-agent start

实际使用场景

| 场景 | 怎么用 | |:-----|:-------| | 出门在外 | SSH 到 Mac，wechat-agent start。通勤路上用微信跟 Claude 聊。| | 24/7 助手 | Mac Mini 上 wechat-agent install-service，开机自启、崩溃自恢复。微信里随时有 AI。| | 团队工具 | 部署到共享服务器，多人通过微信用同一个 Agent，allowedUsers 白名单控制权限。| | 多 Agent 协作 | Claude 写代码 → /agent codex 切到 Codex 审查，同一个微信窗口搞定。|

支持的 Agent

| Agent | 说明 | |:------|:-----| | claude | Claude Code — 使用你 CLI 的默认模型 | | codex | OpenAI Codex — 使用你 CLI 的默认模型 |

在微信里切换：

/agent claude    切换到 Claude
/agent codex     切换到 Codex
/agents          列出所有可用

模型由你本地 CLI 配置决定。要切模型请在 CLI 中设置（如 claude /model 或 codex /model）。

微信命令

在微信里给 Bot 发送以下命令：

| 命令 | 功能 | |:-----|:-----| | /agent <name> | 切换 Agent（claude 或 codex）| | /agents | 列出所有可用 Agent | | /reset | 重置当前会话 | | /status | 查看运行状态、在线时长 | | /help | 显示帮助 |

命令行参考

wechat-agent setup                # 扫码登录
wechat-agent start                # 启动桥接
wechat-agent start --agent codex  # 启动并指定默认 Agent
wechat-agent start -d             # 调试模式
wechat-agent status               # 查看状态
wechat-agent config               # 查看当前配置
wechat-agent install-service      # 安装开机自启（macOS）
wechat-agent uninstall-service    # 移除开机自启

配置

配置文件位于 ~/.wechat-agent/config.json，首次运行自动生成默认配置。

{
  "defaultAgent": "claude",

  // 白名单（空数组 = 允许所有人，适合个人使用）
  "allowedUsers": [],

  // Agent 进程的工作目录
  "workingDirectory": "/Users/you",

  // 预配置 Agent —— 在这里添加自定义 Agent
  "agents": {
    "claude": {
      "adapter": "piped",
      "options": {
        "command": "claude",
        "args": ["-p", "--dangerously-skip-permissions"],
        "timeout": 600000
      }
    },
    "codex": {
      "adapter": "piped",
      "options": {
        "command": "codex",
        "args": ["exec", "--sandbox", "danger-full-access", "--skip-git-repo-check"],
        "inputMode": "arg",
        "timeout": 600000
      }
    }
  },

  // 会话过期时间（小时），默认 7 天
  "sessionTTLHours": 168,

  // 微信回复最大字数
  "maxResponseLength": 4000
}

添加自定义 Agent

在 agents 下加一个条目即可：

{
  "agents": {
    "my-agent": {
      "adapter": "generic-cli",
      "options": {
        "command": "/path/to/my-cli",
        "args": ["--interactive"],
        "responseIdleTimeout": 5000
      }
    }
  }
}

环境变量

ANTHROPIC_API_KEY=sk-ant-...                      # claude-sdk 适配器必需
[email protected],user2@...    # 覆盖配置文件白名单
LOG_LEVEL=info                                     # debug | info | warn | error

适配器

generic-cli — 通用终端适配器

默认适配器，最通用。为每个微信用户创建一个持久子进程，通过 stdin/stdout 通信。进程在多条消息间保持存活，天然维护对话上下文。

claude-sdk — Claude Agent SDK 深度集成

与 @anthropic-ai/claude-agent-sdk 深度集成，支持跨桥接重启恢复会话。需额外安装：

npm install @anthropic-ai/claude-agent-sdk

piped — 管道模式

每条消息创建新进程，适合无状态的命令行工具。

开机自启

macOS LaunchAgent —— 重启不掉线，崩溃自恢复：

wechat-agent install-service      # 安装
wechat-agent uninstall-service    # 卸载

日志位于 ~/.wechat-agent/logs/

架构

                          +-----------------------+
  微信 (iOS)              |   wechat-agent |
       |                  |                       |
       | iLink 长轮询     |  Poller ──> Router    |──> claude      (claude-stream)
       +----------------->|            |          |
       |                  |            v          |
       | iLink 发送       |  Sender <── Adapter   |──> codex       (piped)
       <------------------+                       |──> 任意 CLI...
                          +-----------------------+

关键设计：

• 至少一次投递 —— 消息处理完成后才提交 cursor，不会丢消息
• 用户级进程隔离 —— 每个微信用户拥有独立的 CLI 子进程
• 会话串行化 —— 同一用户的消息严格按顺序处理，不乱序
• 优雅停机 —— AbortController 立即中断进行中的长轮询
• 单实例锁 —— 锁文件防止多个桥接实例同时运行

安全

| 特性 | 说明 | |:-----|:-----| | 用户白名单 | allowedUsers 限制谁可以使用 Bot | | 单实例保护 | 锁文件防止多个桥接进程并发运行 | | 文件权限 | 状态文件 0600，配置目录 0700 | | 日志脱敏 | 消息内容仅在 debug 级别记录 |

作为库使用

除了命令行，也可以作为 Node.js 库导入：

import { Bridge, loadConfig, StateStore } from "wechat-agent";

const config = loadConfig();
const store = new StateStore();
const bridge = new Bridge(config, store);

await bridge.start();

iLink 协议

本项目使用腾讯 2026 年通过 OpenClaw 框架正式开放的微信个人 Bot API。这是官方产品，有《微信ClawBot功能使用条款》法律文件背书，不是灰色地带。

| | | |:-------|:------| | 接入域名 | ilinkai.weixin.qq.com | | 协议 | HTTP / JSON | | 认证 | QR 码扫码 → Bearer Token | | 消息 | 长轮询（35 秒 hold） | | 媒体 | CDN + AES-128-ECB 加密 |

前置条件

• Node.js >= 18
• 微信 iOS 最新版（需支持 ClawBot 功能）
• 至少安装一个终端 AI Agent（claude、codex 等）

给 AI Agent 的自安装指令

本节面向正在阅读本 README 的 AI Agent（Claude Code、Codex 等）。 当用户要求你部署 wechat-agent 时，按以下步骤操作。

自动安装（执行这些命令）

# 1. 全局安装
npm install -g wechat-agent@latest

# 2. 运行 setup —— 终端会出现二维码，告诉用户用微信扫码
wechat-agent setup

# 3. 启动桥接
wechat-agent start

# 4. （可选）安装为持久化服务 —— 开机自启
wechat-agent install-service

你需要知道的

• 桥接将微信消息路由到 CLI Agent（包括你自己）。
• 默认 Agent 是 claude（Claude Code -p 模式）。
• 配置文件 ~/.wechat-agent/config.json，状态文件 ~/.wechat-agent/state.json。
• 用户在微信里发 /agent claude 或 /agent codex 切换。
• 预配置 Agent：claude、codex。
• 添加新 Agent：在 config.json 的 agents 下加条目，指定 adapter 类型（piped 或 generic-cli）和命令。
• 使用腾讯官方 iLink 协议（微信 ClawBot），登录需要扫码。
• wechat-agent install-service 在 ~/Library/LaunchAgents/com.wechat-agent.bridge.plist 创建 LaunchAgent。

告诉用户怎么用

桥接启动后，用户可以：

1. 打开手机微信
2. 找到 ClawBot 聊天窗口（扫码后自动出现）
3. 发任何消息 —— 会转发到默认 AI Agent，回复自动返回
4. 发 /agents 查看所有可用 Agent
5. 发 /agent codex 切换到 Codex
6. 发 /reset 开始新对话

常见问题排查

• wechat-agent setup 扫码后空白页 → 版本可能过旧，npm install -g wechat-agent@latest
• 收到消息但不回复 → 检查默认 Agent 的 CLI 是否在 PATH 中（如 which claude）
• 之前正常现在不工作 → bot token 可能过期，重新 wechat-agent setup
• 作为服务运行时的日志在 ~/.wechat-agent/logs/

License

MIT