Skip to content

weixin-config.md

Latest commit

 

History

History
200 lines (138 loc) · 4.3 KB

weixin-config.md

File metadata and controls

200 lines (138 loc) · 4.3 KB

微信个人号配置指南

本文档说明如何配置微信个人号以接入 OpenCode Bridge。

1. 配置概览

微信个人号适配器支持通过 HTTP 长轮询获取消息，实现私人微信与 OpenCode 的对接。

重要说明: 微信个人号通过数据库配置，不使用环境变量。

2. 前置条件

微信个人号适配器需要配合微信开放平台使用，需要先获取以下信息：

信息 说明
ilinkBotId 机器人账号 ID
botToken 机器人 Token
baseUrl API 基础地址（可选）
cdnBaseUrl CDN 基础地址（可选）

3. 配置方式

微信个人号通过数据库配置，需要在 weixin_accounts 表中配置账号信息。

3.1 账号配置表结构

字段名 类型 说明
account_id TEXT 账号唯一标识
token TEXT 机器人 Token
base_url TEXT API 基础地址
cdn_base_url TEXT CDN 基础地址
enabled INTEGER 是否启用（1=启用，0=禁用）

3.2 添加账号示例

INSERT INTO weixin_accounts (account_id, token, base_url, cdn_base_url, enabled)
VALUES (
  'my-weixin-bot',
  'your-bot-token-here',
  'https://ilinkai.weixin.qq.com',
  'https://novac2c.cdn.weixin.qq.com/c2c',
  1
);

3.3 通过 Web 面板配置

  1. 访问 Web 管理面板 http://localhost:4098
  2. 进入"平台接入" → "微信个人号"
  3. 添加账号信息
  4. 启用账号

4. 功能特性

  • ✅ 支持多账号管理
  • ✅ 支持文本、图片、语音、视频、文件等消息类型
  • ✅ 支持输入状态提示
  • ✅ 支持会话过期自动暂停
  • ✅ 支持消息去重

5. 消息类型支持

消息类型 发送 接收 说明
文本 ✅ ✅ 支持，自动去除 Markdown 格式
图片 ❌ ✅ 仅支持接收
语音 ❌ ✅ 仅支持接收
视频 ❌ ✅ 仅支持接收
文件 ❌ ✅ 仅支持接收
卡片 ⚠️ ❌ 降级为纯文本

6. 限制说明

限制 说明
仅支持私聊 不支持群聊消息
不支持消息删除 微信协议限制
不支持消息更新 微信协议限制
文本格式限制 仅支持纯文本，Markdown 会自动转换为纯文本

7. ChatId 格式

微信个人号的 ChatId 格式为：

weixin::<accountId>::<peerUserId>
  • accountId - 机器人账号 ID
  • peerUserId - 对方用户 ID

8. 会话管理

8.1 会话过期处理

当收到 errcode -14 时，表示会话已过期，适配器会自动暂停该账号的消息轮询。

8.2 重启账号

可通过管理接口重启指定账号：

# 通过 Admin API 重启账号
POST /admin/weixin/restart
Content-Type: application/json

{
  "accountId": "my-weixin-bot"
}

8.3 查看账号状态

# 通过 Admin API 查看状态
GET /admin/weixin/status?accountId=my-weixin-bot

返回示例：

{
  "active": true,
  "paused": false,
  "reason": null
}

9. 输入状态

微信个人号支持发送输入状态提示：

await weixinAdapter.sendTypingIndicator(chatId, TypingStatus.Typing);

状态值：

  • 0 - 停止输入
  • 1 - 正在输入

10. 验证

配置完成后，在微信中验证：

  1. 向机器人账号发送消息
  2. 如果配置正确，机器人应该会响应
  3. 测试命令如 /help、/panel

11. 故障排查

常见问题

问题 可能原因 解决方案
账号自动暂停 会话过期（errcode -14） 检查 Token 是否有效，必要时重新获取
消息发送失败 context_token 失效 确保接收过对方消息以获取 token
收不到消息 账号未启用 检查 enabled 字段是否为 1

日志关键词

[Weixin] Poll loop started     # 轮询启动
[Weixin] Poll error            # 轮询错误
[Weixin] Session expired       # 会话过期
[Weixin] Send text failed      # 发送失败

12. 安全建议

  1. Token 保护: Token 应存储在加密数据库中
  2. 定期更换: 定期更换 Token
  3. 权限控制: 限制账号权限，避免过度授权
  4. 活动监控: 监控异常消息活动