WeClawBot Bridge - 管理面板

添加 Agent

名称

切换命令

类型

描述

HTTP 端点

超时 (ms)

API Key (可选)

模型 (可选)

请求格式

已注册 Agent (0)

命令	名称	类型	描述	端点/命令	模型	操作
加载中...

Agent 测试

选择 Agent

测试消息

Bot 状态

在线状态：检查中...

发送通知

消息内容

通知规则

通知规则功能正在开发中

会话配置

最大对话轮次

过期时间

会话列表 (0)

用户ID	Agent	消息数	最后活跃	过期状态	操作
加载中...

修改管理密码

当前密码

新密码

确认新密码

配置备份

导出所有 Agent 配置、会话设置和管理密码为 JSON 文件，可用于迁移或恢复。

🤖 功能概览

WeClawBot Bridge 是一个微信 ↔ AI Agent 桥接网关，支持在单个微信 Bot 账号上接入多种 AI 服务，用户在微信中通过 #命令 自由切换。

🔀

多 Agent 切换

一个 Bot 接入多套 AI，发 #命令 随时切换，各自独立维护对话历史。

🌐

HTTP Agent

对接任意 OpenAI 兼容接口或自定义 REST API，支持流式输出与图片传输。

💻

CLI Agent

将本地命令行工具（如 claude、python 脚本）直接接入微信，支持持久会话。

📨

通知 & Webhook

外部系统通过 API 主动向微信推送消息，支持文字、图片、文件。

📱 微信使用方式

向 Bot 发送以下命令控制网关，或直接发普通消息与当前 Agent 对话。

命令	说明
`#help`	显示帮助信息与可用命令列表
`#agents`	列出所有已注册的 Agent
`#status`	查看 Bot 当前在线状态
`#<命令>`	切换到对应 Agent（命令在管理面板中配置）
任意文字/图片	转发给当前激活的 Agent 并回复结果

💡 切换 Agent 会自动清空该 Agent 的对话历史，开始新会话。

⚙️ Agent 配置说明

Agent 分两种类型，通过管理面板"Agent 管理"选项卡添加，或直接编辑 config/agents.json。

HTTP Agent（对接 REST API）

{
  "id": "my-gpt",
  "name": "GPT-4o",
  "command": "gpt",          // 微信发 #gpt 切换
  "type": "http",
  "description": "OpenAI GPT-4o",
  "endpoint": "https://api.openai.com/v1/chat/completions",
  "apiKey": "sk-...",
  "model": "gpt-4o",
  "format": "openai",        // openai | native
  "streaming": true,         // 流式输出（更快）
  "timeout": 60000
}

CLI Agent（对接本地命令行）

{
  "id": "claude-cli",
  "name": "Claude Code",
  "command": "claude",
  "type": "cli",
  "description": "Claude CLI 编程助手",
  "cliCommand": "claude",
  "cliArgs": ["-p", "--output-format", "text"],
  "cliWorkDir": "/workspace",
  "cliMode": "oneshot",      // oneshot | persistent
  "timeout": 120000
}

参数说明

字段	类型	说明
`format`	string	`openai` — OpenAI 兼容格式（支持图片）；`native` — 网关原生格式
`streaming`	boolean	开启 SSE 流式输出，边生成边返回，减少等待（需 `format: openai`）
`responsePath`	string	自定义响应取值路径，如 `data.answer`，适配非标准 API
`cliMode`	string	`oneshot` — 每次独立调用；`persistent` — 保持进程常驻，维护会话状态
`cliSentinel`	string	持久模式输出结束标记，默认 `__WCBOT_END__`

📨 消息格式支持

方向	类型	说明
微信 → Bot	文字	直接转发给 Agent
微信 → Bot	图片	下载后以 base64 传给 Agent；`openai` 格式自动构建 Vision 请求
微信 → Bot	语音 / 视频 / 文件	下载为二进制，通过 `native` 格式传给 Agent
Agent → 微信	文字	直接回复
Agent → 微信	图片 / 文件 / 视频	Agent 返回 Buffer，网关自动发送对应类型消息

⚠️ openai 格式下，图片会自动转换为 Vision 多模态请求，无需额外配置。

🔒 认证

需要认证的 API 接口使用 Bearer Token，即管理面板的登录密码。

Authorization: Bearer <你的管理密码>

接口	说明
`POST /api/auth/setup`	首次设置密码无需认证
`POST /api/auth/login`	登录，返回 token 无需认证
`GET /api/auth/status`	检查当前 token 是否有效
`POST /api/auth/change-password`	修改密码（需旧密码）

# 登录示例
curl -X POST /api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"password": "your-password"}'

# 响应
{"authenticated": true, "token": "your-password"}

🤖 Bot API

GET/api/bot/status 无需认证

获取 Bot 当前状态。

{
  "loggedIn": true,
  "accountId": "filehelper",
  "currentUser": "wxid_xxx",
  "qrUrl": null,
  "polling": true
}

POST/api/bot/login

重新获取微信登录二维码（Bot 掉线时使用）。

# 响应
{
  "qrUrl": "https://liteapp.weixin.qq.com/q/...",
  "status": "waiting_for_scan"
}

GET/api/health 无需认证

健康检查，可用于监控探针。

{"status": "ok", "bot": {"loggedIn": true, ...}}

GET/api/metrics 无需认证

Prometheus 格式监控指标，可接入 Grafana 等可视化工具。

📦 Agent API

GET/api/agents 无需认证

列出所有已注册的 Agent。

POST/api/agents

注册新 Agent，Body 为 Agent 配置对象（见上方"Agent 配置"章节）。

PUT/api/agents/:id

更新指定 Agent 的配置，Body 为需要修改的字段。

DELETE/api/agents/:id

删除指定 Agent。

POST/api/agents/:id/test

向指定 Agent 发送测试消息，验证接入是否正常。

# 请求
{"text": "你好，测试一下"}

# 响应
{"text": "你好！我是 GPT-4o，有什么可以帮你？", "elapsed": 1234}

💬 会话 API

管理用户与 Agent 之间的对话会话，支持查看历史、配置过期策略。

GET/api/sessions

列出所有会话摘要（userId、agentId、消息数、最后活跃时间）。

[
  {
    "userId": "wxid_xxx",
    "agentId": "gpt",
    "messageCount": 12,
    "lastActive": 1710000000000
  }
]

GET/api/sessions/detail?userId=&agentId=

查看指定会话的完整对话历史。

{
  "userId": "wxid_xxx",
  "agentId": "gpt",
  "history": [
    { "role": "user", "content": "你好", "timestamp": 1710000000000 },
    { "role": "assistant", "content": "你好！有什么可以帮你？", "timestamp": 1710000001000 }
  ],
  "lastActive": 1710000001000
}

DELETE/api/sessions/clear

删除指定会话（传入 userId + agentId）或清空全部（空 body）。

# 删除单个会话
curl -X DELETE /api/sessions/clear \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{"userId": "wxid_xxx", "agentId": "gpt"}'

# 清空全部会话
curl -X DELETE /api/sessions/clear \
  -H "Authorization: Bearer ***"

GET/api/sessions/config

获取当前会话配置。

{"maxRounds": 0, "expireMs": 0}

PUT/api/sessions/config

更新会话配置（maxRounds / expireMs），持久化保存。expireMs 设为 0 表示永不过期。

# 设永不过期，最大 20 轮
curl -X PUT /api/sessions/config \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{"maxRounds": 20, "expireMs": 0}'

🔔 通知 API

通过 API 主动向当前 Bot 登录用户发送消息（需 Bot 已登录）。

POST/api/notify

# 发送文字通知
curl -X POST /api/notify \
  -H "Authorization: Bearer your-password" \
  -H "Content-Type: application/json" \
  -d '{"content": {"text": "服务器告警：CPU 使用率 95%"}}'

🔗 Webhook

外部系统通过 Webhook 向指定微信用户推送消息，无需认证，适合服务器告警、CI/CD 通知等场景。

POST/api/webhook 无需认证

# 请求体
{
  "userId": "wxid_xxx",         // 目标微信用户 ID（可选，留空自动用 Bot 账号）
  "content": {
    "text": "部署完成 ✅"
  }
}

# 响应
{"ok": true, "recipient": "wxid_xxx"}

💡 userId 留空时，自动向当前 Bot 登录的微信账号本身发消息（方便自用场景）。

GitHub Actions 集成示例

项目已内置 CI workflow（.github/workflows/ci.yml），push 到 main 时自动构建并推送微信通知。只需在仓库 Secrets 中添加 WECLAW_WEBHOOK_URL 即可。

# .github/workflows/ci.yml 中的通知步骤
- name: 通知微信
  if: success()
  run: |
    curl -s -X POST ${{ secrets.WECLAW_WEBHOOK_URL }} \
      -H "Content-Type: application/json" \
      -d '{"content":{"text":"✅ CI 通过"}}'

🌿 环境变量

变量名	默认值	说明
`PORT`	3000	服务监听端口
`API_KEY`	—	管理面板密码（留空则首次访问时设置）
`ENCRYPTION_KEY`	—	凭证加密密钥，32 字节十六进制字符串
`STORAGE_DIR`	.wechatbot-gateway	数据持久化目录
`LOG_LEVEL`	info	日志级别：trace / debug / info / warn / error
`SESSION_MAX_ROUNDS`	0	每个 Agent 保留的最大对话轮次，0 = 不限制
`SESSION_EXPIRE_MS`	0	会话过期时间（毫秒），0 = 永不过期
`ALLOWED_ORIGINS`	—	CORS 允许的来源，逗号分隔

# 生成 32 字节加密密钥
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"