Skip to content
Snow leopard edited this page Jul 16, 2026 · 1 revision

WeChat Integration

Connecting CogitoAgent with WeChat

将 CogitoAgent 与微信连接


CogitoAgent integrates with WeChat via the iLink protocol, allowing you to receive and reply to WeChat messages through the agent. Messages are stored in a dedicated WeChat session, displayed as tool call bubbles, and the login state persists across restarts.

CogitoAgent 通过 iLink 协议集成微信,让您可以通过 Agent 接收和回复微信消息。消息存储在独立的微信专属会话中,以工具调用气泡样式展示,登录状态在重启后依然保持。


WeChat Architecture | 微信架构

flowchart TB
    subgraph USER["WeChat User | 微信用户"]
        WECHAT_USER["WeChat Contact<br/>微信联系人"]
    end

    subgraph COGITO["CogitoAgent"]
        MANAGER["wechat-manager.ts<br/>Channel Manager"]
        TOOL["tools/wechat.ts<br/>WeChat Tools"]
        SESSION["session.ts<br/>WeChat Session"]
        AGENT["Agent.ts<br/>Think Cycle"]
    end

    subgraph EXTERNAL["External | 外部"]
        ILINK["iLink Protocol<br/>微信协议"]
        STATE["data/wechat/<br/>State & Messages"]
    end

    WECHAT_USER -->|"Send Message<br/>发送消息"| ILINK
    ILINK -->|"Polling<br/>轮询"| MANAGER
    MANAGER -->|"Store<br/>存储"| STATE
    MANAGER -->|"Route<br/>路由"| AGENT
    AGENT -->|"Reply<br/>回复"| TOOL
    TOOL -->|"Send<br/>发送"| ILINK
    ILINK --> WECHAT_USER

    MANAGER --> SESSION

    classDef user fill:#1a2332,stroke:#5eead4,color:#5eead4
    classDef cogito fill:#1a2332,stroke:#fbbf24,color:#fbbf24
    classDef external fill:#1a2332,stroke:#94a3b8,color:#94a3b8

    class WECHAT_USER user
    class MANAGER,TOOL,SESSION,AGENT cogito
    class ILINK,STATE external
Loading

Key Features | 核心特性

Feature Description 说明
QR Code Login Scan QR code to log in to WeChat 扫码登录微信
Message Receiving Receive WeChat messages in real-time 实时接收微信消息
Message Replying Reply to WeChat messages via the agent 通过 Agent 回复微信消息
Dedicated Session WeChat messages stored in a separate session 微信消息存储在独立会话中
Persistence Login state persists across restarts 登录状态持久化
Message Dual-Write Messages stored in both JSON and session history 消息双写存储

Setup & Login | 设置与登录

Step 1: Login to WeChat | 第一步:登录微信

Click the "连接微信" (Connect WeChat) button in the Dashboard sidebar, or use the CLI command:

点击仪表盘侧边栏的**"连接微信"**按钮,或使用 CLI 命令:

# CLI command | CLI 命令
/wechat login

Step 2: Scan QR Code | 第二步:扫码二维码

A QR code will appear in a popup window. Scan it with your WeChat app.

二维码将显示在弹窗中。使用微信应用扫码。

[微信] 请使用微信扫描二维码
[WeChat] Please scan the QR code with WeChat

Step 3: Start Polling | 第三步:启动轮询

After login, the agent automatically starts polling for messages.

登录后,Agent 自动启动消息轮询。

[微信通道] 消息轮询已启动
[WeChat Channel] Message polling started

CLI Commands | CLI 命令

Command Description 说明
/wechat Show WeChat channel status 显示微信通道状态
/wechat login Login via QR code 扫码登录
/wechat logout Logout from WeChat 退出登录
/wechat status Show detailed status 显示详细状态

Message Flow | 消息流程

sequenceDiagram
    participant WeChat as WeChat User<br/>微信用户
    participant iLink as iLink Protocol<br/>微信协议
    participant Manager as wechat-manager.ts<br/>通道管理器
    participant Session as session.ts<br/>会话管理
    participant Agent as Agent.ts<br/>思考引擎
    participant Tool as tools/wechat.ts<br/>微信工具

    WeChat->>iLink: Send message | 发送消息
    iLink->>Manager: Polling receives | 轮询接收

    Manager->>Manager: addWechatMessage()<br/>Add to weichat.json
    Manager->>Session: syncWechatHistoryToSession()<br/>Sync to session

    Session->>Agent: Switch to WeChat session<br/>切换到微信会话
    Agent->>Agent: thinkCycle() | 思考循环
    Agent-->>Agent: Generate reply | 生成回复

    Agent->>Tool: sendWechatMessage(to, text)<br/>发送微信消息
    Tool->>iLink: Send message | 发送消息
    iLink->>WeChat: Deliver message | 送达消息

    Manager->>Manager: addWechatMessage(sent)<br/>记录已发送
Loading

Message Storage | 消息存储

Dual-Write Mechanism | 双写机制

WeChat messages are stored in two locations:

微信消息存储在两个位置:

flowchart LR
    subgraph INPUT["Incoming Message | 收到消息"]
        MSG["WeChat Message<br/>微信消息"]
    end

    MSG --> STORE1["weichat.json<br/>Structured Storage<br/>结构化存储"]
    MSG --> STORE2["Session History<br/>AI Context<br/>AI 上下文"]

    STORE1 --> DISPLAY["Tool Bubbles<br/>工具气泡"]
    STORE2 --> AGENT["Agent Context<br/>Agent 上下文"]

    classDef input fill:#1a2332,stroke:#5eead4,color:#5eead4
    classDef store fill:#1a2332,stroke:#fbbf24,color:#fbbf24
    classDef output fill:#1a2332,stroke:#38bdf8,color:#38bdf8

    class MSG input
    class STORE1,STORE2 store
    class DISPLAY,AGENT output
Loading

Message Format | 消息格式

{
  "messages": [
    {
      "id": "1718000000000-abc123",
      "timestamp": "2026-07-16T10:30:00.000Z",
      "direction": "received",
      "from": "张三",
      "text": "你好,帮我查一下天气"
    },
    {
      "id": "1718000005000-def456",
      "timestamp": "2026-07-16T10:30:05.000Z",
      "direction": "sent",
      "to": "张三",
      "text": "好的,今天天气晴朗,气温 28°C"
    }
  ]
}

UI Integration | UI 集成

Dashboard Display | 仪表盘显示

WeChat messages appear as tool call bubbles in the Dashboard chat view:

微信消息在仪表盘聊天视图中显示为工具调用气泡:

┌─────────────────────────────────────────────┐
│  [TOOL] 微信收到                             │
│  from: 张三                                 │
│  text: 你好,帮我查一下天气                  │
├─────────────────────────────────────────────┤
│  [TOOL] 微信回复                             │
│  to: 张三                                   │
│  text: 好的,今天天气晴朗,气温 28°C        │
│  ✓ OK                                       │
└─────────────────────────────────────────────┘

WeChat Button | 微信按钮

The WeChat button in the sidebar changes state based on connection:

侧边栏的微信按钮根据连接状态变化:

State Button Text Color
Disconnected 连接微信 Default
Connected 微信通道 Phosphor (green)
Connecting 连接中... Amber

Tools Reference | 工具参考

Tool Parameters Description 说明
loginWechat — Login via QR code 扫码登录
logoutWechat — Logout from WeChat 退出登录
sendWechatMessage to, text Send text message 发送文本消息
sendWechatImage to, imagePath Send image 发送图片
getWechatStatus — Get connection status 获取连接状态
generateWechatQRCode — Generate QR code 生成二维码

Usage Examples | 使用示例

[TOOL] loginWechat() [/TOOL]
[TOOL] sendWechatMessage("user123", "Hello from CogitoAgent!") [/TOOL]
[TOOL] sendWechatImage("user123", "/path/to/image.png") [/TOOL]
[TOOL] getWechatStatus() [/TOOL]

Configuration | 配置

Environment Variable Default Description
COGITO_WECHAT_API_BASE_URL https://ilinkai.weixin.qq.com WeChat API endpoint
COGITO_WECHAT_POLLING_INTERVAL 2000 Polling interval (ms)
COGITO_WECHAT_AUTO_REPLY true Auto-reply to messages
环境变量 默认值 说明
COGITO_WECHAT_API_BASE_URL https://ilinkai.weixin.qq.com 微信 API 地址
COGITO_WECHAT_POLLING_INTERVAL 2000 轮询间隔(毫秒)
COGITO_WECHAT_AUTO_REPLY true 自动回复消息

File Structure | 文件结构

data/wechat/
├── weichat.json          # Message history | 消息历史
└── state.json            # Login state | 登录状态

State File | 状态文件

{
  "loggedIn": true,
  "accountId": "wxid_xxxxxx",
  "botToken": "token_xxxxxx",
  "baseUrl": "https://ilinkai.weixin.qq.com",
  "userId": "user_xxxxxx",
  "polling": true,
  "wechatSessionId": "sess_xxxxxx"
}

Troubleshooting | 故障排除

Common Issues | 常见问题

Issue Solution
QR code not showing Check network connection, try /wechat login again
Login timeout Scan QR code within 2 minutes
Messages not received Check polling status with /wechat status
Messages not sent Verify login status, check network
问题 解决方案
二维码不显示 检查网络连接,重试 /wechat login
登录超时 在 2 分钟内扫码
收不到消息 使用 /wechat status 检查轮询状态
发不出消息 验证登录状态,检查网络

Check Status | 检查状态

/wechat
[微信] 已登录账号: wxid_xxxxxx
[WeChat] Logged in as: wxid_xxxxxx

Next Steps | 下一步


Previous: Agent Cluster →

Next: Deployment →

上一篇: 智能体集群 →

下一篇: 部署指南 →

Clone this wiki locally