Repository navigation
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 接收和回复微信消息。消息存储在独立的微信专属会话中,以工具调用气泡样式展示,登录状态在重启后依然保持。
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
| 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 | 消息双写存储 |
Click the "连接微信" (Connect WeChat) button in the Dashboard sidebar, or use the CLI command:
点击仪表盘侧边栏的**"连接微信"**按钮,或使用 CLI 命令:
# CLI command | CLI 命令
/wechat loginA QR code will appear in a popup window. Scan it with your WeChat app.
二维码将显示在弹窗中。使用微信应用扫码。
[微信] 请使用微信扫描二维码
[WeChat] Please scan the QR code with WeChat
After login, the agent automatically starts polling for messages.
登录后,Agent 自动启动消息轮询。
[微信通道] 消息轮询已启动
[WeChat Channel] Message polling started
| Command | Description | 说明 |
|---|---|---|
/wechat |
Show WeChat channel status | 显示微信通道状态 |
/wechat login |
Login via QR code | 扫码登录 |
/wechat logout |
Logout from WeChat | 退出登录 |
/wechat status |
Show detailed status | 显示详细状态 |
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/>记录已发送
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
{
"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"
}
]
}WeChat messages appear as tool call bubbles in the Dashboard chat view:
微信消息在仪表盘聊天视图中显示为工具调用气泡:
┌─────────────────────────────────────────────┐
│ [TOOL] 微信收到 │
│ from: 张三 │
│ text: 你好,帮我查一下天气 │
├─────────────────────────────────────────────┤
│ [TOOL] 微信回复 │
│ to: 张三 │
│ text: 好的,今天天气晴朗,气温 28°C │
│ ✓ OK │
└─────────────────────────────────────────────┘
The WeChat button in the sidebar changes state based on connection:
侧边栏的微信按钮根据连接状态变化:
| State | Button Text | Color |
|---|---|---|
| Disconnected | 连接微信 | Default |
| Connected | 微信通道 | Phosphor (green) |
| Connecting | 连接中... | Amber |
| 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 | 生成二维码 |
[TOOL] loginWechat() [/TOOL]
[TOOL] sendWechatMessage("user123", "Hello from CogitoAgent!") [/TOOL]
[TOOL] sendWechatImage("user123", "/path/to/image.png") [/TOOL]
[TOOL] getWechatStatus() [/TOOL]
| 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 |
自动回复消息 |
data/wechat/
├── weichat.json # Message history | 消息历史
└── state.json # Login state | 登录状态
{
"loggedIn": true,
"accountId": "wxid_xxxxxx",
"botToken": "token_xxxxxx",
"baseUrl": "https://ilinkai.weixin.qq.com",
"userId": "user_xxxxxx",
"polling": true,
"wechatSessionId": "sess_xxxxxx"
}| 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 检查轮询状态 |
| 发不出消息 | 验证登录状态,检查网络 |
/wechat
[微信] 已登录账号: wxid_xxxxxx
[WeChat] Logged in as: wxid_xxxxxx
-
Deployment — Deploy to production
-
FAQ — Common questions and answers
-
部署指南 — 部署到生产环境
-
常见问题 — 常见问题与解答
Previous: Agent Cluster →
Next: Deployment →
上一篇: 智能体集群 →
下一篇: 部署指南 →