kaiyuan/chatgpt-on-wechat
1
0
Fork 0
mirror of https://github.com/zhayujie/chatgpt-on-wechat.git synced 2026-06-02 00:57:41 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: make English the default docs language and fix link paths

Browse Source
This commit is contained in:
zhayujie
2026-05-31 17:52:22 +08:00
parent 126649f70f
commit 7bf4ef3d05
231 changed files with 8999 additions and 8974 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
docs/channels/dingtalk.mdx
View File

@@ -1,35 +1,35 @@
---
title: 钉钉
description: 将 CowAgent 接入钉钉应用
title: DingTalk
description: Integrate CowAgent into DingTalk application
---
通过钉钉开放平台创建智能机器人应用，将 CowAgent 接入钉钉。
Integrate CowAgent into DingTalk by creating an intelligent robot app on the DingTalk Open Platform.
## 一、创建应用
## 1. Create App
1. 进入 [钉钉开发者后台](https://open-dev.dingtalk.com/fe/app#/corp/app)，登录后点击 **创建应用**，填写应用相关信息：
1. Go to [DingTalk Developer Console](https://open-dev.dingtalk.com/fe/app#/corp/app), log in and click **Create App**, fill in the app information:
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/dingtalk-create-app.png" width="800"/>
2. 点击添加应用能力，选择 **机器人** 能力，点击 **添加**：
2. Click **Add App Capability**, select **Robot** capability and click **Add**:
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/dingtalk-add-bot.png" width="800"/>
3. 配置机器人信息后点击 **发布**。发布后，点击 "**点击调试**"，会自动创建测试群聊，可在客户端查看：
3. Configure the robot information and click **Publish**. After publishing, click "**Debug**" to automatically create a test group chat, which can be viewed in the client:
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/dingtalk-config-bot.png" width="600"/>
4. 点击 **版本管理与发布**，创建新版本发布：
4. Click **Version Management & Release**, create a new version and publish:
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/dingtalk-publish-bot.png" width="700"/>
## 二、项目配置
## 2. Project Configuration
1. 点击 **凭证与基础信息**，获取 `Client ID` 和 `Client Secret`：
1. Click **Credentials & Basic Info**, get the `Client ID` and `Client Secret`:
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/dingtalk-get-secret.png" width="700"/>
2. 将以下配置加入项目根目录的 `config.json` 文件：
2. Add the following configuration to `config.json` in the project root:
```json
{
@@ -39,18 +39,20 @@ description: 将 CowAgent 接入钉钉应用
}
```
3. 安装依赖：
3. Install the dependency:
```bash
pip3 install dingtalk_stream
```
4. 启动项目后，在钉钉开发者后台点击 **事件订阅**，点击 **已完成接入，验证连接通道**，显示 **连接接入成功** 即表示配置完成：
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/dingtalk-app-config.png" width="700"/>
4. After starting the project, go to the DingTalk Developer Console, click **Event Subscription**, then click **Connection verified, verify channel**. When "**Connection successful**" is displayed, the configuration is complete:
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/dingtalk-event-sub.png" width="700"/>
## 三、使用
## 3. Usage
与机器人私聊或将机器人拉入企业群中均可开启对话：
Chat privately with the robot or add it to an enterprise group to start a conversation:
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/dingtalk-hosting-demo.png" width="650"/>

80
docs/channels/discord.mdx
View File

@@ -1,51 +1,51 @@
---
title: Discord
description: 将 CowAgent 接入 Discord Bot
description: Integrate CowAgent with a Discord Bot
---
> 通过 Discord Bot 的 **Gateway 长连接** 接入 CowAgent，支持私聊（DM）与服务器频道（@机器人 / 回复机器人触发）。Gateway 基于 WebSocket 长连接，无需公网 IP 与回调地址，开箱即用。
> Integrate CowAgent into Discord via a Discord Bot using the **Gateway** (persistent WebSocket). Supports direct messages (DM) and server channels (triggered by @mention or replying to the bot). The Gateway uses a persistent WebSocket connection — no public IP or callback URL required, works out of the box.
## 一、接入步骤
## 1. Setup
### 步骤一：创建 Discord 应用与 Bot
### Step 1: Create a Discord Application and Bot
1. 打开 [Discord 开发者后台](https://discord.com/developers/applications)，点击 **New Application**，填写名称（如 `CowAgent`）并创建。
2. 左侧菜单进入 **Bot** 页面，点击 **Reset Token** 生成 Bot Token，复制并妥善保存（仅显示一次）。
1. Open the [Discord Developer Portal](https://discord.com/developers/applications), click **New Application**, enter a name (e.g. `CowAgent`), and create it.
2. Go to the **Bot** page in the left sidebar, click **Reset Token** to generate a Bot Token, then copy and store it safely (shown only once).
<Tip>
这个 Token 等同于 Bot 的密码，请勿泄露。若意外泄漏，在 Bot 页面再次点击 **Reset Token** 重置即可。
This token is your bot's password — keep it secret. If it leaks, click **Reset Token** again on the Bot page to regenerate it.
</Tip>
### 步骤二：开启 Message Content Intent
### Step 2: Enable the Message Content Intent
私聊与频道读取文本均依赖该权限。
Reading message text in both DMs and channels depends on this privileged intent.
1. 在 **Bot** 页面下方找到 **Privileged Gateway Intents**。
2. 打开 **Message Content Intent** 开关并保存。
1. On the **Bot** page, find **Privileged Gateway Intents**.
2. Turn on **Message Content Intent** and save.
<Note>
未开启该开关时，机器人收到的消息内容会为空，导致无响应。
Without this intent enabled, incoming message content will be empty and the bot will not respond.
</Note>
### 步骤三：邀请 Bot 进入服务器
### Step 3: Invite the Bot to a Server
1. 左侧菜单进入 **OAuth2 → URL Generator**。
2. **Scopes** 勾选 `bot`。
3. **Bot Permissions** 至少勾选：`Send Messages`、`Read Message History`、`Attach Files`、`View Channels`。
4. 复制底部生成的授权链接，在浏览器打开，选择目标服务器完成授权。
1. Go to **OAuth2 → URL Generator** in the left sidebar.
2. Under **Scopes**, check `bot`.
3. Under **Bot Permissions**, check at least: `Send Messages`, `Read Message History`, `Attach Files`, `View Channels`.
4. Copy the generated authorization URL at the bottom, open it in a browser, and authorize it for your target server.
<Note>
仅需私聊（DM）可跳过此步，但仍需先在任意共同服务器中与机器人建立 DM 通道，或由用户主动私聊机器人。
You can skip this step if you only need DMs, but you still need a DM channel with the bot (e.g. the user messages the bot directly).
</Note>
### 步骤四：接入 CowAgent
### Step 4: Connect to CowAgent
<Tabs>
<Tab title="Web 控制台（推荐）">
打开 Web 控制台（本地链接：http://127.0.0.1:9899 ），选择 **通道** 菜单，点击 **接入通道**，选择 **Discord**，填入 Bot Token，点击接入即可。
<Tab title="Web Console (Recommended)">
Open the Web Console (default `http://127.0.0.1:9899`), go to **Channels**, click **Add Channel**, choose **Discord**, paste the Bot Token, and click connect.
</Tab>
<Tab title="配置文件">
在 `config.json` 中添加以下配置后启动：
<Tab title="Config File">
Add the following to `config.json` and start Cow:
```json
{
@@ -55,39 +55,39 @@ description: 将 CowAgent 接入 Discord Bot
}
```
| 参数 | 说明 | 默认值 |
| Key | Description | Default |
| --- | --- | --- |
| `discord_token` | 开发者后台 Bot 页面生成的 Bot Token | - |
| `discord_group_trigger` | 频道触发方式：`mention_or_reply`（@或回复机器人）/ `mention_only`（仅@） / `all`（所有消息） | `mention_or_reply` |
| `discord_token` | Bot Token generated on the Bot page of the Developer Portal | - |
| `discord_group_trigger` | Channel trigger: `mention_or_reply` (@ or reply to bot) / `mention_only` (@ only) / `all` (all messages) | `mention_or_reply` |
</Tab>
</Tabs>
启动 Cow 后，日志中出现以下输出即表示接入成功：
The integration is ready when you see logs like:
```
[Discord] Bot logged in as CowAgent#1234 (id=123456789)
[Discord] ✅ Discord bot ready, listening for messages
```
## 二、功能说明
## 2. Capabilities
| 功能 | 支持情况 |
| Feature | Support |
| --- | --- |
| 私聊（DM） | ✅ |
| 服务器频道（@机器人 / 回复机器人） | ✅ |
| 文本消息 | ✅ 收发 |
| 图片消息 | ✅ 收发 |
| 文件消息 | ✅ 收发（PDF / Word / Excel 等） |
| Direct message (DM) | ✅ |
| Server channel (@bot / reply to bot) | ✅ |
| Text messages | ✅ send / receive |
| Image messages | ✅ send / receive |
| File messages | ✅ send / receive (PDF / Word / Excel, etc.) |
<Note>
Discord 单条消息上限为 2000 字符，超长回复会自动按换行拆分为多条发送。
A single Discord message is capped at 2000 characters; long replies are automatically split across multiple messages by line breaks.
</Note>
## 三、使用
## 3. Usage
完成接入后：
Once connected:
- **私聊（DM）**：在服务器成员列表中找到你的机器人，点击头像直接发消息对话。
- **频道**：在已邀请机器人的频道中，使用 `@你的机器人 你好` 或 **回复机器人的某条消息** 触发对话。
- **Direct message (DM)**: find your bot in the server member list, click its avatar, and message it directly.
- **Channel**: in a channel where the bot is invited, trigger it with `@your-bot hello` or by **replying to one of the bot's messages**.
发送图片或文件时，可以在附件的输入框中 **添加文字说明**（描述/问题）一并发送，机器人会结合附件回答。也支持先发附件再发问题，两条消息会自动合并提问。
When sending an image or file, you can **add a text caption** (description / question) in the attachment input — the bot will answer based on both. Sending an attachment first and then a follow-up question also works; the two messages are merged automatically.

85
docs/channels/feishu.mdx
View File

@@ -1,45 +1,44 @@
---
title: 飞书
description: 将 CowAgent 接入飞书应用
title: Feishu (Lark)
description: Integrate CowAgent into Feishu via a custom enterprise app
---
> 通过飞书自建应用接入 CowAgent，支持单聊与群聊（@机器人），使用 WebSocket 长连接模式，无需公网 IP，支持流式打字机回复、语音消息收发。
> Integrate CowAgent into Feishu via a custom enterprise app. Supports p2p chat and group chat (@bot), uses WebSocket long connection (no public IP needed), supports streaming typewriter replies and voice messages.
<Note>
接入需要是飞书企业用户且具有企业管理权限。
You need to be a Feishu enterprise user with admin privileges.
</Note>
## 一、接入方式
## 1. Setup
### 方式一：扫码一键接入（推荐）
启动 Cow 项目后在终端中即可完成扫码创建。或打开 Web 控制台（本地链接：http://127.0.0.1:9899 ），选择 **通道** 菜单，点击 **接入通道**，选择 **飞书**，点击 **一键创建飞书应用**，使用 **飞书 App** 扫描二维码即可自动完成应用创建并接入:
### Option 1: One-click Scan to Create (Recommended)
No need to manually create an app on the Feishu Developer Platform. Start the Cow project, open the web console (default `http://127.0.0.1:9899/`), go to **Channels**, click **Add Channel**, choose **Feishu**, then under the **Scan QR** tab click **One-click Create Feishu App** and scan with the **Feishu App** to complete app creation and connection automatically.
<img src="https://cdn.link-ai.tech/doc/20260505181126.png" width="800"/>
<Note>
1. `lark-oapi` 依赖版本需要 >=1.5.5
2. 扫码创建出的应用会自动预置全部所需权限（消息收发、卡片读写、群聊事件等）和事件订阅，无需到开发者后台手动配置。
1. Requires `lark-oapi` ≥ 1.5.5.
2. The created app comes with all required permissions (messaging, card read/write, group events, etc.) and event subscriptions pre-configured — no manual setup on the developer console needed. Currently only the Feishu mainland version is supported (Lark international not yet supported).
</Note>
When starting from CLI without `feishu_app_id` configured, the QR code is also printed to the terminal.
### 方式二：手动创建接入
### Option 2: Manual Setup
需要先在飞书开放平台创建自建应用并配置权限，再通过 Web 控制台或配置文件接入。
Manually create a custom app on the Feishu Developer Platform, then connect via Web Console or config file.
**步骤一：创建应用**
**Step 1: Create the App**
1. 进入 [飞书开发平台](https://open.feishu.cn/app/)，点击 **创建企业自建应用**：
1. Go to [Feishu Developer Platform](https://open.feishu.cn/app/), click **Create Enterprise Custom App**:
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/feishu-hosting-create-app.jpg" width="500"/>
2. 在 **添加应用能力** 中，为应用添加 **机器人** 能力：
2. In **Add App Capabilities**, add the **Bot** capability:
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/feishu-hosting-add-bot.jpg" width="800"/>
3. 在 **权限管理** 中，将以下权限粘贴到输入框，全选并 **批量开通**：
3. In **Permission Management**, paste the following permissions and **Batch Enable** all:
```
im:message,im:message.group_at_msg,im:message.group_at_msg:readonly,im:message.p2p_msg,im:message.p2p_msg:readonly,im:message:send_as_bot,im:resource,cardkit:card:write
@@ -47,18 +46,18 @@ im:message,im:message.group_at_msg,im:message.group_at_msg:readonly,im:message.p
<img src="https://cdn.link-ai.tech/doc/feishu-hosting-add-auth2.png" width="800"/>
4. 在 **凭证与基础信息** 中获取 `App ID` 和 `App Secret`：
4. Get `App ID` and `App Secret` from **Credentials & Basic Info**:
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/feishu-hosting-appid-secret.jpg" width="800"/>
**步骤二：接入 CowAgent**
**Step 2: Connect to CowAgent**
<Tabs>
<Tab title="Web 控制台">
打开 Web 控制台，选择 **通道** 菜单，点击 **接入通道**，选择 **飞书**，切换到「手动填写」Tab，输入 App ID 和 App Secret，点击接入即可。
<Tab title="Web Console">
Open the web console, go to **Channels**, click **Add Channel**, choose **Feishu**, switch to the **Manual** tab, enter App ID and App Secret, then click connect.
</Tab>
<Tab title="配置文件">
在 `config.json` 中添加以下配置后启动程序：
<Tab title="Config File">
Add the following to `config.json` and start the program:
```json
{
@@ -69,43 +68,43 @@ im:message,im:message.group_at_msg,im:message.group_at_msg:readonly,im:message.p
}
```
| 参数 | 说明 | 默认值 |
| Parameter | Description | Default |
| --- | --- | --- |
| `feishu_app_id` | 飞书应用 App ID | - |
| `feishu_app_secret` | 飞书应用 App Secret | - |
| `feishu_stream_reply` | 是否开启流式打字机回复 | `true` |
| `feishu_app_id` | Feishu app App ID | - |
| `feishu_app_secret` | Feishu app App Secret | - |
| `feishu_stream_reply` | Enable streaming typewriter reply | `true` |
</Tab>
</Tabs>
**步骤三：发布应用**
**Step 3: Publish the App**
1. 启动 Cow 项目后，在飞书开放平台点击 **事件与回调**，选择 **长连接** 模式并保存：
1. After Cow is running, go to **Events & Callbacks** in the Feishu Developer Platform, choose **Long Connection** mode and save:
<img src="https://cdn.link-ai.tech/doc/202601311731183.png" width="600"/>
2. 点击 **添加事件**，搜索 "接收消息"，选择 **接收消息 v2.0** 并确认。
2. Click **Add Event**, search for "Receive Message" and choose **Receive Message v2.0**.
3. 点击 **版本管理与发布**，创建版本并申请 **线上发布**，在飞书客户端审核通过：
3. Click **Version Management & Release**, create a version and apply for **Production Release**. Approve the request in the Feishu client:
<img src="https://cdn.link-ai.tech/doc/202601311807356.png" width="600"/>
## 二、功能说明
## 2. Features
| 功能 | 支持情况 |
| Feature | Status |
| --- | --- |
| 单聊 | ✅ |
| 群聊（@机器人） | ✅ |
| 文本消息 | ✅ 收发 |
| 图片消息 | ✅ 收发 |
| 语音消息 | ✅ 收发 |
| 流式回复 | ✅（通过 `feishu_stream_reply` 配置控制，默认开启） |
| P2P chat | ✅ |
| Group chat (@bot) | ✅ |
| Text messages | ✅ send/receive |
| Image messages | ✅ send/receive |
| Voice messages | ✅ send/receive |
| Streaming reply | ✅ (powered by Feishu cardkit streaming card) |
<Note>
流式回复需要机器人具备 `cardkit:card:write` 权限（一键创建已默认开通），且接收方飞书客户端版本 ≥ 7.20。低版本客户端会显示升级提示，权限或版本不满足时自动降级为普通文本回复。
Streaming reply requires the `cardkit:card:write` permission (already enabled by one-click creation) and Feishu client version ≥ 7.20. Older clients see an upgrade prompt; if the permission or version is not satisfied, replies fall back to plain text automatically.
</Note>
## 三、使用
## 3. Usage
完成接入后，在飞书中搜索机器人名称即可开始单聊对话。
After connection, search for the bot name in Feishu to start a chat.
如需在群聊中使用，将机器人添加到群中，@机器人发送消息即可。
To use in groups, add the bot to a group and @-mention it.

56
docs/channels/index.mdx
View File

@@ -1,45 +1,45 @@
---
title: 通道概览
description: CowAgent 支持的通道及能力矩阵
title: Channels Overview
description: Channels supported by CowAgent and their capability matrix
---
CowAgent 支持接入多种聊天通道，启动时通过 `channel_type` 切换。Web 控制台默认开启，可与其他接入通道并行运行。
CowAgent supports multiple chat channels. Switch between them at startup via `channel_type`. The Web Console is enabled by default and can run in parallel with other channels.
## 能力矩阵
## Capability Matrix
下表汇总各通道支持的入站消息类型、机器人回复类型与群聊能力，方便按场景选择。
The table below summarizes the inbound message types, bot reply types, and group chat capabilities supported by each channel, making it easy to choose by scenario.
| 通道 | 文本 | 图片 | 文件 | 语音 | 群聊 |
| Channel | Text | Image | File | Voice | Group Chat |
| --- | :-: | :-: | :-: | :-: | :-: |
| [微信](/channels/weixin) | ✅ | ✅ | ✅ | ✅ | |
| [Web 控制台](/channels/web) | ✅ | ✅ | ✅ | ✅ | |
| [飞书](/channels/feishu) | ✅ | ✅ | ✅ | ✅ | ✅ |
| [钉钉](/channels/dingtalk) | ✅ | ✅ | ✅ | ✅ | ✅ |
| [企微智能机器人](/channels/wecom-bot) | ✅ | ✅ | ✅ | ✅ | ✅ |
| [WeChat](/channels/weixin) | ✅ | ✅ | ✅ | ✅ | |
| [Web Console](/channels/web) | ✅ | ✅ | ✅ | ✅ | |
| [Feishu](/channels/feishu) | ✅ | ✅ | ✅ | ✅ | ✅ |
| [DingTalk](/channels/dingtalk) | ✅ | ✅ | ✅ | ✅ | ✅ |
| [WeCom Bot](/channels/wecom-bot) | ✅ | ✅ | ✅ | ✅ | ✅ |
| [QQ](/channels/qq) | ✅ | ✅ | ✅ | | ✅ |
| [企业微信应用](/channels/wecom) | ✅ | ✅ | ✅ | ✅ | |
| [公众号](/channels/wechatmp) | ✅ | ✅ | | ✅ | |
| [WeCom App](/channels/wecom) | ✅ | ✅ | ✅ | ✅ | |
| [Official Account](/channels/wechatmp) | ✅ | ✅ | | ✅ | |
| [Telegram](/channels/telegram) | ✅ | ✅ | ✅ | ✅ | ✅ |
| [Slack](/channels/slack) | ✅ | ✅ | ✅ | | ✅ |
| [Discord](/channels/discord) | ✅ | ✅ | ✅ | | ✅ |
- **图片 / 文件 / 语音**列表示通道支持收发对应消息类型，具体细节详见各通道文档
- **群聊**列指可识别并响应群消息
- The **Image / File / Voice** columns indicate that the channel can send and receive the corresponding message types; see each channel's docs for details
- The **Group Chat** column indicates the ability to recognize and respond to group messages
<Tip>
每个通道的语音 / 图像能力依赖对应模型厂商的配置，详见 [模型概览](/models)。
The voice / image capabilities of each channel depend on the configuration of the corresponding model provider. See [Models Overview](/models/index) for details.
</Tip>
## 通道一览
## Channel List
- [Web 控制台](/channels/web) — 内置浏览器对话和管理面板，默认开启
- [微信](/channels/weixin) — 通过个人微信扫码登录
- [飞书](/channels/feishu) — 飞书自建机器人
- [钉钉](/channels/dingtalk) — 钉钉自建机器人
- [企微智能机器人](/channels/wecom-bot) — 企业微信智能机器人
- [QQ](/channels/qq) — QQ 官方机器人开放平台
- [企业微信应用](/channels/wecom) — 企业微信自建应用接入
- [公众号](/channels/wechatmp) — 微信公众号（订阅号 / 服务号）
- [Telegram](/channels/telegram) — 海外 IM，5 分钟接入，无需公网 IP
- [Slack](/channels/slack) — 团队协作 IM，Socket Mode 接入，无需公网 IP
- [Discord](/channels/discord) — 社区 IM，Gateway 长连接接入，无需公网 IP
- [Web Console](/channels/web) — built-in browser-based chat and management panel, enabled by default
- [WeChat](/channels/weixin) — log in via personal WeChat QR scan
- [Feishu](/channels/feishu) — Feishu custom bot
- [DingTalk](/channels/dingtalk) — DingTalk custom bot
- [WeCom Bot](/channels/wecom-bot) — WeCom AI Bot via WebSocket long connection
- [QQ](/channels/qq) — QQ Official Bot open platform
- [WeCom App](/channels/wecom) — WeCom custom app integration
- [Official Account](/channels/wechatmp) — WeChat Official Account (subscription / service)
- [Telegram](/channels/telegram) — global IM, 5-minute setup, no public IP needed
- [Slack](/channels/slack) — team collaboration IM, Socket Mode integration, no public IP needed
- [Discord](/channels/discord) — community IM, Gateway connection, no public IP needed

76
docs/channels/qq.mdx
View File

@@ -1,44 +1,44 @@
---
title: QQ 机器人
description: 将 CowAgent 接入 QQ 机器人（WebSocket 长连接模式）
title: QQ Bot
description: Connect CowAgent to QQ Bot (WebSocket long connection)
---
> 通过 QQ 开放平台的机器人接口接入 CowAgent，支持 QQ 单聊、QQ 群聊（@机器人）、频道消息和频道私信，无需公网 IP，使用 WebSocket 长连接模式。
> Connect CowAgent via QQ Open Platform's bot API, supporting QQ direct messages, group chats (@bot), guild channel messages, and guild DMs. No public IP required — uses WebSocket long connection.
<Note>
QQ 机器人通过 QQ 开放平台创建，使用 WebSocket 长连接接收消息，通过 OpenAPI 发送消息，无需公网 IP 和域名。
QQ Bot is created through the QQ Open Platform. It uses WebSocket long connection to receive messages and OpenAPI to send messages. No public IP or domain is required.
</Note>
## 一、创建 QQ 机器人
## 1. Create a QQ Bot
> 进入[QQ 开放平台](https://q.qq.com)，QQ扫码登录，如果未注册开放平台账号，请先完成[账号注册](https://q.qq.com/#/register)。
> Visit the [QQ Open Platform](https://q.qq.com), sign in with QQ. If you haven't registered, please complete [account registration](https://q.qq.com/#/register) first.
1.在 [QQ开放平台-机器人列表页](https://q.qq.com/#/apps)，点击创建机器人:
1.Go to the [QQ Open Platform - Bot List](https://q.qq.com/#/apps), and click **Create Bot**:
<img src="https://cdn.link-ai.tech/doc/20260317162900.png" width="800"/>
2.填写机器人名称、头像等基本信息，完成创建：
2.Fill in the bot name, avatar, and other basic information to complete the creation:
<img src="https://cdn.link-ai.tech/doc/20260317163005.png" width="800"/>
3.点击进入机器人配置页面，选择**开发管理**菜单，完成以下步骤：
3.Enter the bot configuration page, go to **Development Management**, and complete the following steps:
- 复制并记录 **AppID**（机器人ID）
- 生成并记录 **AppSecret**（机器人秘钥）
- Copy and save the **AppID** (Bot ID)
- Generate and save the **AppSecret** (Bot Secret)
<img src="https://cdn.link-ai.tech/doc/20260317164955.png" width="800"/>
## 二、配置和运行
## 2. Configuration and Running
### 方式一：Web 控制台接入
### Option A: Web Console
启动 Cow项目后打开 Web 控制台 (本地链接为: http://127.0.0.1:9899/ )，选择 **通道** 菜单，点击 **接入通道**，选择 **QQ 机器人**，填写上一步保存的 AppID 和 AppSecret，点击接入即可。
Start the program and open the Web console (local access: http://127.0.0.1:9899/). Go to the **Channels** tab, click **Connect Channel**, select **QQ Bot**, fill in the AppID and AppSecret from the previous step, and click Connect.
<img src="https://cdn.link-ai.tech/doc/20260317165425.png" width="800"/>
### 方式二：配置文件接入
### Option B: Config File
在 `config.json` 中添加以下配置：
Add the following to your `config.json`:
```json
{
@@ -48,41 +48,41 @@ description: 将 CowAgent 接入 QQ 机器人（WebSocket 长连接模式）
}
```
| 参数 | 说明 |
| Parameter | Description |
| --- | --- |
| `qq_app_id` | QQ 机器人的 AppID，在开放平台开发管理中获取 |
| `qq_app_secret` | QQ 机器人的 AppSecret，在开放平台开发管理中获取 |
| `qq_app_id` | AppID of the QQ Bot, found in Development Management on the open platform |
| `qq_app_secret` | AppSecret of the QQ Bot, found in Development Management on the open platform |
配置完成后启动程序，日志显示 `[QQ] ✅ Connected successfully` 即表示连接成功。
After configuration, start the program. The log message `[QQ] ✅ Connected successfully` indicates a successful connection.
## 三、使用
## 3. Usage
在 QQ开放平台 - 管理 - **使用范围和人员** 菜单中，使用QQ客户端扫描 "添加到群和消息列表" 的二维码，即可开始与QQ机器人的聊天：
In the QQ Open Platform, go to **Management → Usage Scope & Members**, scan the "Add to group and message list" QR code with your QQ client to start chatting with the bot:
<img src="https://cdn.link-ai.tech/doc/20260317165947.png" width="800"/>
对话效果：
Chat example:
<img src="https://cdn.link-ai.tech/doc/20260317171508.png" width="800"/>
## 四、功能说明
## 4. Supported Features
> 注意：若需在群聊及频道中使用QQ机器人，需完成发布上架审核并在使用范围配置权限使用范围。
> Note: To use the QQ bot in group chats and guild channels, you need to complete the publishing review and configure usage scope permissions.
| 功能 | 支持情况 |
| Feature | Status |
| --- | --- |
| QQ 单聊 | ✅ |
| QQ 群聊（@机器人） | ✅ |
| 频道消息（@机器人） | ✅ |
| 频道私信 | ✅ |
| 文本消息 | ✅ 收发 |
| 图片消息 | ✅ 收发（群聊和单聊） |
| 文件消息 | ✅ 发送（群聊和单聊） |
| 定时任务 | ✅ 主动推送（每月每用户限 4 条） |
| QQ Direct Messages | ✅ |
| QQ Group Chat (@bot) | ✅ |
| Guild Channel (@bot) | ✅ |
| Guild DM | ✅ |
| Text Messages | ✅ Send & Receive |
| Image Messages | ✅ Send & Receive (group & direct) |
| File Messages | ✅ Send (group & direct) |
| Scheduled Tasks | ✅ Active push (4 per user per month) |
## 五、注意事项
## 5. Notes
- **被动消息限制**：QQ 单聊被动消息有效期为 60 分钟，每条消息最多回复 5 次；QQ 群聊被动消息有效期为 5 分钟。
- **主动消息限制**：单聊和群聊每月主动消息上限为 4 条，在使用定时任务功能时需要注意这个限制
- **事件权限**：默认订阅 `GROUP_AND_C2C_EVENT`（QQ群/单聊）和 `PUBLIC_GUILD_MESSAGES`（频道公域消息），如需其他事件类型请在开放平台申请权限。
- **Passive message limits**: QQ direct message replies are valid for 60 minutes (max 5 replies per message); group chat replies are valid for 5 minutes.
- **Active message limits**: Both direct and group chats have a monthly limit of 4 active messages. Keep this in mind when using the scheduled tasks feature.
- **Event permissions**: By default, `GROUP_AND_C2C_EVENT` (QQ group/direct) and `PUBLIC_GUILD_MESSAGES` (guild public messages) are subscribed. Apply for additional permissions on the open platform if needed.

84
docs/channels/slack.mdx
View File

@@ -1,29 +1,29 @@
---
title: Slack
description: 将 CowAgent 接入 Slack App
description: Integrate CowAgent with a Slack App
---
> 通过 Slack App 的 **Socket Mode** 接入 CowAgent，支持私聊（DM）与频道（@机器人 / 线程内回复触发）。Socket Mode 基于长连接，无需公网 IP 与回调地址，开箱即用。
> Integrate CowAgent into Slack via a Slack App in **Socket Mode**. Supports direct messages (DM) and channels (triggered by @mention or replying within a thread). Socket Mode uses a persistent WebSocket connection — no public IP or callback URL required, works out of the box.
## 一、接入步骤
## 1. Setup
### 步骤一：创建 Slack App
### Step 1: Create a Slack App
1. 打开 [Slack API 应用管理页](https://api.slack.com/apps)，点击 **Create New App** → **From scratch**。
2. 填写 **App Name**（如 `CowAgent`），选择要安装的 **Workspace**，点击创建。
1. Open the [Slack API apps page](https://api.slack.com/apps), click **Create New App** → **From scratch**.
2. Enter an **App Name** (e.g. `CowAgent`), pick the **Workspace** to install into, and create it.
### 步骤二：开启 Socket Mode 并获取 App Token
### Step 2: Enable Socket Mode and get the App Token
1. 左侧菜单进入 **Settings → Socket Mode**，打开 **Enable Socket Mode**。
2. 系统会提示生成一个 **App-Level Token**，作用域勾选 `connections:write`，生成后保存这串以 `xapp-` 开头的 Token。
1. In the left sidebar go to **Settings → Socket Mode** and turn on **Enable Socket Mode**.
2. You will be prompted to generate an **App-Level Token** with the `connections:write` scope. Save this token starting with `xapp-`.
<Tip>
Socket Mode 通过 WebSocket 长连接接收事件，无需在公网暴露回调 URL，适合本地或内网部署。
Socket Mode receives events over a WebSocket connection, so you don't need to expose a public callback URL — ideal for local or intranet deployments.
</Tip>
### 步骤三：配置 Bot 权限并安装
### Step 3: Configure bot scopes and install
1. 进入 **Features → OAuth & Permissions**，在 **Bot Token Scopes** 中点击 **Add an OAuth Scope**，逐项添加以下权限：
1. Go to **Features → OAuth & Permissions**, click **Add an OAuth Scope** under **Bot Token Scopes**, and add the following scopes one by one:
```
app_mentions:read
@@ -39,10 +39,10 @@ description: 将 CowAgent 接入 Slack App
```
<Note>
`files:read` / `files:write` 用于图片、文件的收发；若仅需文本对话可省略。
`files:read` / `files:write` are used for sending/receiving images and files; omit them if you only need text conversations.
</Note>
2. 进入 **Features → Event Subscriptions**，打开 **Enable Events**，在 **Subscribe to bot events** 中点击 **Add Bot User Event** 添加以下事件：
2. Go to **Features → Event Subscriptions**, turn on **Enable Events**, and under **Subscribe to bot events** click **Add Bot User Event** to add:
```
app_mention
@@ -51,23 +51,23 @@ description: 将 CowAgent 接入 Slack App
```
<Note>
如需在私有频道使用，再添加 `message.groups`。
Add `message.groups` if you need to use the bot in private channels.
</Note>
3. 进入 **Features → App Home**，在 **Show Tabs** 区域勾选 **Messages Tab**，并勾选下方的 **Allow users to send Slash commands and messages from the messages tab**（允许用户从消息标签页发送消息），否则私聊输入框会被关闭、无法给机器人发消息。
4. 回到 **OAuth & Permissions**，点击 **Install to Workspace** 完成安装，安装后获取以 `xoxb-` 开头的 **Bot User OAuth Token**。
3. Go to **Features → App Home**, enable **Messages Tab** under **Show Tabs**, and check **Allow users to send Slash commands and messages from the messages tab**. Otherwise the DM input box is disabled and users cannot message the bot.
4. Back in **OAuth & Permissions**, click **Install to Workspace**. After installing, copy the **Bot User OAuth Token** starting with `xoxb-`.
<Tip>
若 Slack 客户端仍提示「向此应用发送消息的功能已关闭」，请确认已完成上一步的 App Home 设置，并刷新或重启 Slack 客户端（必要时把 App 从对话列表移除后重新打开）。
If the Slack client still shows "Sending messages to this app has been turned off", make sure you completed the App Home step above, then refresh or restart the Slack client (remove the app from your conversations and reopen it if needed).
</Tip>
### 步骤四：接入 CowAgent
### Step 4: Connect to CowAgent
<Tabs>
<Tab title="Web 控制台（推荐）">
打开 Web 控制台（本地链接：http://127.0.0.1:9899 ），选择 **通道** 菜单，点击 **接入通道**，选择 **Slack**，分别填入 Bot Token（`xoxb-`）和 App Token（`xapp-`），点击接入即可。
<Tab title="Web Console (Recommended)">
Open the Web Console (default `http://127.0.0.1:9899`), go to **Channels**, click **Add Channel**, choose **Slack**, paste the Bot Token (`xoxb-`) and App Token (`xapp-`), and click connect.
</Tab>
<Tab title="配置文件">
在 `config.json` 中添加以下配置后启动：
<Tab title="Config File">
Add the following to `config.json` and start Cow:
```json
{
@@ -78,41 +78,41 @@ description: 将 CowAgent 接入 Slack App
}
```
| 参数 | 说明 | 默认值 |
| Key | Description | Default |
| --- | --- | --- |
| `slack_bot_token` | Bot User OAuth Token，形如 `xoxb-...` | - |
| `slack_app_token` | App-Level Token（开启 Socket Mode 后生成），形如 `xapp-...` | - |
| `slack_group_trigger` | 频道触发方式：`mention_or_reply`（@或线程内回复）/ `mention_only`（仅@） / `all`（所有消息） | `mention_or_reply` |
| `slack_bot_token` | Bot User OAuth Token, like `xoxb-...` | - |
| `slack_app_token` | App-Level Token (generated after enabling Socket Mode), like `xapp-...` | - |
| `slack_group_trigger` | Channel trigger: `mention_or_reply` (@ or reply in thread) / `mention_only` (@ only) / `all` (all messages) | `mention_or_reply` |
</Tab>
</Tabs>
启动 Cow 后，日志中出现以下输出即表示接入成功：
The integration is ready when you see logs like:
```
[Slack] Bot logged in as user_id=U0XXXXXXX, team=Txxxxxxxx
[Slack] ✅ Slack bot ready, listening for events
```
## 二、功能说明
## 2. Capabilities
| 功能 | 支持情况 |
| Feature | Support |
| --- | --- |
| 私聊（DM） | ✅ |
| 频道（@机器人 / 线程内回复） | ✅ |
| 文本消息 | ✅ 收发 |
| 图片消息 | ✅ 收发 |
| 文件消息 | ✅ 收发（PDF / Word / Excel 等） |
| 线程回复 | ✅ 回复发送至触发消息所在线程 |
| Direct message (DM) | ✅ |
| Channel (@bot / reply in thread) | ✅ |
| Text messages | ✅ send / receive |
| Image messages | ✅ send / receive |
| File messages | ✅ send / receive (PDF / Word / Excel, etc.) |
| Thread replies | ✅ replies are posted to the thread of the triggering message |
<Note>
Slack 通过线程（Thread）组织对话。机器人会把回复发送到触发消息所在的线程，频道内更整洁。
Slack organizes conversations into threads. The bot posts replies into the thread of the triggering message, keeping channels tidy.
</Note>
## 三、使用
## 3. Usage
完成接入后：
Once connected:
- **私聊（DM）**：在 Slack 左侧 **Apps** 中找到你的 App，直接发消息对话。
- **频道**：把 App 邀请进频道（`/invite @你的App`），使用 `@你的App 你好` 触发对话；后续在同一线程内直接回复即可继续对话。
- **Direct message (DM)**: find your App under **Apps** in the Slack sidebar and message it directly.
- **Channel**: invite the App into a channel (`/invite @your-app`), then trigger it with `@your-app hello`; continue the conversation by replying within the same thread.
发送图片或文件时，可以在附件的输入框中 **添加文字说明**（描述/问题）一并发送，机器人会结合附件回答。也支持先发附件再发问题，两条消息会自动合并提问。
When sending an image or file, you can **add a text caption** (description / question) in the attachment input — the bot will answer based on both. Sending an attachment first and then a follow-up question also works; the two messages are merged automatically.

111
docs/channels/telegram.mdx
View File

@@ -1,47 +1,47 @@
---
title: Telegram
description: 将 CowAgent 接入 Telegram Bot
description: Integrate CowAgent with Telegram via the Bot API
---
> 通过 Telegram Bot API 接入 CowAgent，支持单聊与群聊（@机器人 / 回复机器人触发），使用 Long Polling 模式无需公网 IP，开箱即用。
> Integrate CowAgent into Telegram via the official Bot API. Supports private chat and group chat (triggered by @mention or replying to the bot). Uses Long Polling — no public IP required, works out of the box.
## 一、接入步骤
## 1. Setup
### 步骤一：通过 BotFather 创建 Bot
### Step 1: Create a Bot via BotFather
1. 在 Telegram 中搜索并打开官方账号 [@BotFather](https://t.me/BotFather)。
2. 发送 `/newbot` 命令，按提示输入：
- **Bot 名称**（显示名，可中文，例如 `My CowAgent Bot`）
- **Bot 用户名**（必须以 `bot` 结尾，例如 `my_cowagent_bot`）
3. 创建成功后，BotFather 会返回一段 **HTTP API Token**（形如 `123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ`），妥善保存。
1. Open the official account [@BotFather](https://t.me/BotFather) in Telegram.
2. Send `/newbot` and follow the prompts:
- **Bot name** (display name, e.g. `My CowAgent Bot`)
- **Bot username** (must end with `bot`, e.g. `my_cowagent_bot`)
3. Once created, BotFather returns an **HTTP API Token** (e.g. `123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ`). Keep it safe.
<Tip>
这个 Token 等同于 Bot 的密码，请勿泄露。如果意外泄漏可向 `@BotFather` 发送 `/revoke` 重置。
The token is the password of your bot — never share it. If it leaks, send `/revoke` to `@BotFather` to reset it.
</Tip>
### 步骤二：（群聊使用）关闭 Privacy Mode
### Step 2: (Group chat only) Disable Privacy Mode
仅使用单聊可跳过此步。Telegram Bot 默认开启 **Privacy Mode**，群聊中只能收到带 `@bot` 的命令（如 `/start@your_bot`）以及对 bot 消息的 reply；**普通的 `@bot 你好` 文字消息收不到**，会导致群聊无响应。
Skip this step if you only use private chat. Telegram bots run in **Privacy Mode** by default — in groups they can only see commands suffixed with `@bot` (e.g. `/start@your_bot`) and replies to bot messages; **plain `@bot hello` text messages are not delivered**, so the bot will appear unresponsive in groups.
向 `@BotFather` 发送：
Send the following to `@BotFather`:
1. `/setprivacy`
2. 选择刚才创建的 bot
3. 选择 `Disable`
2. Pick the bot you just created
3. Choose `Disable`
<Note>
若设置后群聊仍无响应，可尝试把 Bot 从群里移除并重新拉入。
If the bot is still silent in groups after this, try removing it from the group and adding it back.
</Note>
### 步骤三：接入 CowAgent
### Step 3: Connect to CowAgent
<Tabs>
<Tab title="Web 控制台（推荐）">
打开 Web 控制台（本地链接：http://127.0.0.1:9899 ），选择 **通道** 菜单，点击 **接入通道**，选择 **Telegram**，填入 Bot Token，点击接入即可。
<Tab title="Web Console (Recommended)">
Open the Web Console (default `http://127.0.0.1:9899`), go to **Channels**, click **Add Channel**, choose **Telegram**, paste the Bot Token, and click connect.
</Tab>
<Tab title="配置文件">
在 `config.json` 中添加以下配置后启动：
<Tab title="Config File">
Add the following to `config.json` and start Cow:
```json
{
@@ -51,16 +51,15 @@ description: 将 CowAgent 接入 Telegram Bot
}
```
| 参数 | 说明 | 默认值 |
| Key | Description | Default |
| --- | --- | --- |
| `telegram_token` | BotFather 返回的 HTTP API Token | - |
| `telegram_group_trigger` | 群聊触发方式：`mention_or_reply`（@或回复机器人）/ `mention_only`（仅@） / `all`（所有消息） | `mention_or_reply` |
| `telegram_register_commands` | 启动时是否自动向 BotFather 注册命令菜单 | `true` |
| `telegram_proxy` | （可选）代理地址，如 `http://127.0.0.1:7890`、`socks5://127.0.0.1:1080`；运行环境无法直连 `api.telegram.org` 时配置，留空则使用环境变量 `HTTPS_PROXY` | `""` |
| `telegram_token` | HTTP API Token returned by BotFather | - |
| `telegram_group_trigger` | Group trigger: `mention_or_reply` (@ or reply) / `mention_only` (@ only) / `all` (all messages) | `mention_or_reply` |
| `telegram_register_commands` | Whether to register the command menu with BotFather on startup | `true` |
</Tab>
</Tabs>
启动 Cow 后，日志中出现以下输出即表示接入成功：
The integration is ready when you see logs like:
```
[Telegram] Bot logged in as @my_cowagent_bot (id=123456789)
@@ -68,45 +67,45 @@ description: 将 CowAgent 接入 Telegram Bot
[Telegram] ✅ Telegram bot ready, polling for updates
```
## 二、功能说明
## 2. Capabilities
| 功能 | 支持情况 |
| Feature | Support |
| --- | --- |
| 单聊 | ✅ |
| 群聊（@机器人 / 回复机器人） | ✅ |
| 文本消息 | ✅ 收发 |
| 图片消息 | ✅ 收发 |
| 语音消息 | ✅ 收发（接收 OGG/Opus，发送 OGG/Opus） |
| 视频消息 | ✅ 收发 |
| 文件消息 | ✅ 收发（PDF / Word / Excel 等） |
| 命令菜单 | ✅ 与 Web 控制台 slash 命令一致 |
| Private chat | ✅ |
| Group chat (@bot / reply to bot) | ✅ |
| Text messages | ✅ send / receive |
| Image messages | ✅ send / receive |
| Voice messages | ✅ send / receive (OGG/Opus) |
| Video messages | ✅ send / receive |
| File messages | ✅ send / receive (PDF / Word / Excel, etc.) |
| Command menu | ✅ aligned with Web Console slash commands |
### 命令菜单
### Command Menu
启动时会自动向 BotFather 注册命令菜单，用户在 Telegram 输入框输入 `/` 会出现下拉提示：
On startup, the channel registers a command menu with BotFather. Typing `/` in Telegram shows a dropdown:
| 命令 | 说明 |
| Command | Description |
| --- | --- |
| `/help` | 显示命令帮助 |
| `/status` | 查看运行状态 |
| `/context` | 查看对话上下文（`/context clear` 清除） |
| `/skill` | 技能管理（`/skill list`、`/skill install` 等） |
| `/memory` | 记忆管理（`/memory dream`） |
| `/knowledge` | 知识库管理（`/knowledge list` / `on` / `off`） |
| `/config` | 查看当前配置 |
| `/cancel` | 中止当前正在运行的 Agent 任务 |
| `/logs` | 查看最近日志 |
| `/version` | 查看版本 |
| `/help` | Show command help |
| `/status` | View runtime status |
| `/context` | View conversation context (`/context clear` to clear) |
| `/skill` | Skill management (`/skill list`, `/skill install`, ...) |
| `/memory` | Memory management (`/memory dream`) |
| `/knowledge` | Knowledge base (`/knowledge list` / `on` / `off`) |
| `/config` | View current config |
| `/cancel` | Cancel the running Agent task |
| `/logs` | View recent logs |
| `/version` | Show version |
<Note>
Telegram 命令菜单只能展示一级命令，子命令通过空格输入即可，例如 `/skill list`、`/context clear`。
Telegram's command menu only displays top-level commands; subcommands are entered with a space, e.g. `/skill list`, `/context clear`.
</Note>
## 三、使用
## 3. Usage
完成接入后：
Once connected:
- **单聊**：在 Telegram 中搜索你创建的 Bot 用户名（如 `@my_cowagent_bot`），点击 `Start` 即可开始对话。
- **群聊**：把 Bot 拉进群，使用 `@bot 你好` 或 **回复 Bot 的某条消息** 触发对话。若群聊无响应，请检查 Privacy Mode 是否已按 [步骤二](#步骤二-群聊使用-关闭-privacy-mode) 关闭。
- **Private chat**: search for your bot username (e.g. `@my_cowagent_bot`) in Telegram, click `Start` and chat away.
- **Group chat**: add the bot to a group, then trigger it with `@bot hello` or by **replying to one of the bot's messages**. If the bot doesn't respond in groups, double-check Privacy Mode in [Step 2](#step-2-group-chat-only-disable-privacy-mode).
发送图片或文件时，可以直接在附件上方的输入框中 **添加 Caption**（描述/问题）一并发送，机器人会结合附件回答。也支持先发附件再发问题，两条消息会自动合并提问。
When sending an image or file, you can **add a caption** (description / question) directly in the attachment input — the bot will answer based on both. Sending an attachment first and then a follow-up question also works; the two messages are merged automatically.

80
docs/channels/web.mdx
View File

@@ -1,11 +1,11 @@
---
title: Web 控制台
description: 通过 Web 控制台使用 CowAgent
title: Web Console
description: Use CowAgent through the Web Console
---
Web 控制台是 CowAgent 的默认通道，启动后会自动运行，通过浏览器即可与 Agent 对话，并支持在线管理模型、技能、记忆、通道等配置。
The Web Console is CowAgent's default channel. It runs automatically once started, letting you chat with the Agent in a browser and manage models, skills, memory, channels, and other configuration online.
## 配置
## Configuration
```json
{
@@ -17,79 +17,79 @@ Web 控制台是 CowAgent 的默认通道，启动后会自动运行，通过浏
}
```
| 参数 | 说明 | 默认值 |
| Parameter | Description | Default |
| --- | --- | --- |
| `channel_type` | 设为 `web` | `web` |
| `web_host` | Web 服务监听地址，默认监听 `127.0.0.1`（仅本机），如需公网访问请改为 `0.0.0.0` 并设置密码 | `""` |
| `web_port` | Web 服务监听端口 | `9899` |
| `web_password` | 访问密码，留空表示不启用密码保护；监听 `0.0.0.0` 时建议设置 | `""` |
| `web_session_expire_days` | 登录会话有效天数 | `30` |
| `web_file_serve_root` | web 端可直接读取/发送的文件根目录，默认仅限用户主目录及 agent 工作空间；设为 `/` 可放开整个文件系统 | `"~"` |
| `enable_thinking` | 是否启用深度思考模式 | `false` |
| `channel_type` | Set to `web` | `web` |
| `web_host` | Web service listen address. Defaults to `127.0.0.1` (local only); set to `0.0.0.0` for public access and configure a password | `""` |
| `web_port` | Web service listen port | `9899` |
| `web_password` | Access password. Leave empty to disable password protection; recommended when listening on `0.0.0.0` | `""` |
| `web_session_expire_days` | Login session validity in days | `30` |
| `web_file_serve_root` | Root directory the web console can directly read/send files from. Defaults to the user home dir and agent workspace only; set to `/` to allow the whole filesystem | `"~"` |
| `enable_thinking` | Whether to enable deep thinking mode | `false` |
配置密码后，访问控制台时需先输入密码完成登录。登录状态默认保持 30 天，期间重启服务也无需重新登录。密码也支持在控制台的「配置」页面中在线修改。
Once a password is configured, you must enter it to log in when accessing the console. The login session is kept for 30 days by default, so restarting the service during that period does not require re-login. The password can also be changed online from the "Configuration" page in the console.
## 访问地址
## Access URL
启动项目后访问：
After starting the project, visit:
- 本地运行：`http://localhost:9899`
- 服务器运行：`http://<server-ip>:9899`
- Local: `http://localhost:9899`
- Server: `http://<server-ip>:9899`
<Note>
请确保服务器防火墙和安全组已放行对应端口。
Ensure the server firewall and security group allow the corresponding port.
</Note>
## 功能介绍
## Features
### 对话界面
### Chat Interface
支持流式输出，可实时展示 Agent 的思考过程（Reasoning）和工具调用过程（Tool Calls），更直观地观察 Agent 的决策过程。深度思考功能可通过配置或控制台的「Agent 配置」开关控制。
Supports streaming output with real-time display of the Agent's reasoning process and tool calls, providing intuitive observation of the Agent's decision-making. Deep thinking can be toggled via configuration or the "Agent Configuration" switch in the console.
<img width="850" src="https://cdn.link-ai.tech/doc/20260227180120.png" />
#### 多会话管理
#### Multi-Session Management
对话界面支持多会话（Session）管理，所有会话记录持久化存储在数据库中：
The chat interface supports multi-session management. All session records are persistently stored in the database:
- **会话列表**：点击左侧历史会话图标可展开/收起会话列表面板，支持滚动加载全部历史会话
- **AI 生成标题**：新会话在首轮对话完成后，自动调用模型生成简短的会话摘要标题
- **新建会话**：点击会话列表顶部的「新对话」按钮或输入区的 `+` 按钮创建新会话
- **删除会话**：点击会话项的删除按钮，确认后永久删除该会话及其所有消息
- **清除上下文**：点击输入区的清除按钮，在当前会话中插入一条分隔线，分隔线以上的消息仍然展示但不再作为模型的上下文输入
- **Session List**: Click the history icon on the left to expand/collapse the session list panel, with scroll-to-load support for all historical sessions
- **AI-Generated Titles**: After the first exchange in a new session, the model is automatically called to generate a short summary title
- **New Session**: Click the "New Chat" button at the top of the session list or the `+` button in the input area to create a new session
- **Delete Session**: Click the delete button on a session item and confirm to permanently delete the session and all its messages
- **Clear Context**: Click the clear button in the input area to insert a divider in the current session. Messages above the divider are still displayed but no longer included as context for the model
### 模型管理
### Model Management
支持在线管理不同模型厂商的文本、图像、语音、向量模型配置，无需手动编辑配置文件：
Manage text, image, voice, and embedding model configurations for different providers online — no need to edit config files manually:
<img width="850" src="https://cdn.link-ai.tech/doc/20260521212949.png" />
### 技能管理
### Skill Management
支持在线查看和管理 Agent 技能（Skills）：
View and manage Agent skills (Skills) online:
<img width="850" src="https://cdn.link-ai.tech/doc/20260227173403.png" />
### 记忆管理
### Memory Management
支持在线查看和管理 Agent 记忆：
View and manage Agent memory online:
<img width="850" src="https://cdn.link-ai.tech/doc/20260227173349.png" />
### 通道管理
### Channel Management
支持在线管理接入通道，支持实时连接/断开操作：
Manage connected channels online with real-time connect/disconnect operations:
<img width="850" src="https://cdn.link-ai.tech/doc/20260227173331.png" />
### 定时任务
### Scheduled Tasks
支持在线查看和管理定时任务，包括一次性任务、固定间隔、Cron 表达式等多种调度方式的可视化管理：
View and manage scheduled tasks online, including one-time tasks, fixed intervals, and Cron expressions:
<img width="850" src="https://cdn.link-ai.tech/doc/20260227173704.png" />
### 日志
### Logs
支持在线实时查看 Agent 运行日志，便于监控运行状态和排查问题：
View Agent runtime logs in real time for monitoring and troubleshooting:
<img width="850" src="https://cdn.link-ai.tech/doc/20260227173514.png" />

90
docs/channels/wechat-kf.mdx
View File

@@ -1,60 +1,60 @@
---
title: 微信客服
description: 将 CowAgent 接入微信客服（WeCom Customer Service）
title: WeCom Customer Service
description: Integrate CowAgent into WeCom Customer Service (微信客服)
---
通过把企业微信自建应用绑定到「微信客服」账号，CowAgent 可以接管来自外部微信用户的客服咨询，并可在小程序、公众号、视频号及视频号小店等场景中通过链接或二维码触达微信用户。
By binding a WeCom custom enterprise app to a WeCom Customer Service (微信客服) account, CowAgent can take over inbound inquiries from external WeChat users and serve them through links or QR codes embedded in WeChat Mini Programs, Official Accounts, Video Channels, and Video Channel stores.
<Note>
微信客服只能使用 Docker 部署或服务器 Python 部署，需要公网可达的回调地址，不支持本地运行模式。
WeCom Customer Service only supports Docker deployment or server Python deployment. A publicly reachable callback URL is required; local run mode is not supported.
</Note>
## 一、准备
## 1. Prerequisites
需要的资源：
Required resources:
1. 一台服务器（有公网 IP）
2. 注册并已认证的企业微信
3. 已开通「微信客服」能力
1. A server with a public IP
2. A registered and verified WeCom account
3. WeCom Customer Service capability enabled
<Note>
建议**单独再创建一个企微自建应用**用于微信客服，不要复用已有的 `wechatcom_app` 应用，否则两个通道会争抢同一个回调地址。
It is recommended to create a **dedicated** WeCom custom app for Customer Service rather than reusing the existing `wechatcom_app` one — otherwise the two channels will compete for the same callback URL.
</Note>
## 二、创建企业微信自建应用
## 2. Create a WeCom Custom App
1. 在 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame#apps)，点击 **应用管理 → 创建应用**：
1. In the [WeCom Admin Console](https://work.weixin.qq.com/wework_admin/frame#apps), go to **Application Management → Create Application**:
<img src="https://cdn.link-ai.tech/doc/20260228103156.png" width="480"/>
2. 点击 **我的企业**，在最下方获取 **企业ID**（后续填写到 `wechat_kf_corp_id`）：
2. Click **My Enterprise** and find the **Corp ID** at the bottom of the page (it goes into `wechat_kf_corp_id`):
<img src="https://cdn.link-ai.tech/doc/wechatcom-hosting-companyid.png" width="600"/>
3. 进入上一步创建的应用，点击 Secret 旁的「**查看**」，Secret 会推送到管理员手机端的企业微信里查看：
3. Open the app you just created and click **"View"** next to Secret. The Secret will be pushed to the admin's phone via the WeCom app, where it can be viewed:
<img src="https://cdn.link-ai.tech/doc/wechatcom-hosting-agent-secret.png" width="600"/>
4. 进入应用 **接收消息 → 设置API接收**，点击右侧「**随机获取**」生成 **Token** 和 **EncodingAESKey** 并保存：
4. Open the app's **Receive Messages → Set API Reception** page, click **"Random Generate"** to generate the **Token** and **EncodingAESKey**, and save them:
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wechatcom-hosting-token-aeskey.jpg" width="600"/>
<Note>
此时保存 API 接收配置会失败，因为程序还未启动，等项目运行后再回来保存。
Saving the API reception configuration will fail at this point because the program has not started yet. Come back to save it after the project is running.
</Note>
## 三、配置和运行
## 3. Configuration and Run
填入上一步收集到的 4 个字段（Corp ID / Secret / Token / EncodingAESKey）：
Fill in the 4 fields collected from the previous step (Corp ID / Secret / Token / EncodingAESKey):
<Tabs>
<Tab title="Web 控制台">
启动 Cow 项目后打开 Web 控制台，选择 **通道** 菜单，点击 **接入通道**，选择 **微信客服**，依次填入 Corp ID / Secret / Token / AES Key（端口默认 9888，可改），点击接入即可。
<Tab title="Web Console">
Start the Cow project and open the Web Console. Go to the **Channels** menu, click **Connect**, choose **WeCom Customer Service**, fill in Corp ID / Secret / Token / AES Key (port defaults to 9888, configurable), and click Connect.
<img src="https://cdn.link-ai.tech/doc/cow-weixinkefu-web-control.png" width="800"/>
</Tab>
<Tab title="配置文件">
在 `config.json` 中添加以下配置（各参数与企业微信后台的对应关系见上方截图）：
<Tab title="Config File">
Add the following configuration to `config.json` (each parameter maps to a field shown in the screenshots above):
```json
{
@@ -67,34 +67,34 @@ description: 将 CowAgent 接入微信客服（WeCom Customer Service）
}
```
| 参数 | 说明 |
| Parameter | Description |
| --- | --- |
| `wechat_kf_corp_id` | 企业 ID |
| `wechat_kf_secret` | 绑定到微信客服的那个企微自建应用的 Secret |
| `wechat_kf_token` | API 接收配置中的 Token |
| `wechat_kf_aes_key` | API 接收配置中的 EncodingAESKey |
| `wechat_kf_port` | 监听端口，默认 9888 |
| `wechat_kf_corp_id` | Corp ID |
| `wechat_kf_secret` | Secret of the WeCom custom app bound to Customer Service |
| `wechat_kf_token` | Token from the API reception config |
| `wechat_kf_aes_key` | EncodingAESKey from the API reception config |
| `wechat_kf_port` | Listening port, default 9888 |
</Tab>
</Tabs>
接入完成后启动程序（Web 控制台方式会自动重启），日志中出现 `Listening on http://0.0.0.0:9888/wxkf/` 表示运行成功，需要将该端口对外开放（如在云服务器安全组中放行）。
After connecting, start the program (the Web Console method restarts the channel automatically). When the log shows `Listening on http://0.0.0.0:9888/wxkf/`, the program is running successfully. You need to open this port externally (e.g., allow it in the cloud server security group).
接着回到企业微信「接收消息 → 设置API接收」，将回调 URL 填为 `http://<your-host>:9888/wxkf/`，点击保存。保存成功后还需将服务器 IP 添加到 **企业可信IP** 中，否则无法收发消息：
Then go back to **Receive Messages → Set API Reception** in the WeCom console and set the callback URL to `http://<your-host>:9888/wxkf/`, then click Save. After saving successfully, you also need to add the server IP to **Enterprise Trusted IPs**, otherwise messages cannot be sent or received:
<img src="https://cdn.link-ai.tech/doc/wechat-com_config.png" width="600"/>
<img src="https://cdn.link-ai.tech/doc/20260228103224.png" width="520"/>
<Warning>
如遇到 URL 配置回调不通过或配置失败：
1. 确保服务器防火墙关闭且安全组放行监听端口（默认 9888）
2. 仔细检查 Token、Secret、EncodingAESKey 等参数配置是否一致，URL 格式是否正确
3. 认证企业微信需要配置与主体一致的备案域名
If URL verification fails or the configuration is unsuccessful:
1. Ensure the server firewall is disabled and the security group allows the listening port (default 9888)
2. Carefully check that Token, Secret, EncodingAESKey and other parameters are consistent, and the URL format is correct
3. Verified WeCom accounts must use a filed domain matching the entity
</Warning>
## 四、绑定微信客服账号
## 4. Bind a WeCom Customer Service Account
进入企业微信管理后台 **微信客服** 页面，创建客服账号并与上一步的企微自建应用绑定：
In the WeCom Admin Console, go to **WeCom Customer Service**, create a customer service account, and bind it to the custom app you created above:
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-step1.jpg" width="600"/>
@@ -102,28 +102,28 @@ description: 将 CowAgent 接入微信客服（WeCom Customer Service）
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-step3.jpg" width="600"/>
绑定完成后，进入 **微信客服 → 微信客服账号详情**，在「**接入链接**」一栏：
After binding, go to **WeCom Customer Service → Account Details**, and under **"Access Link"**:
- 点击「**复制链接**」可获得形如 `https://work.weixin.qq.com/kfid/kfcd83e5896b9ba07be` 的访问链接
- 点击「**生成二维码**」可获得对应的二维码
- Click **"Copy Link"** to get an access link like `https://work.weixin.qq.com/kfid/kfcd83e5896b9ba07be`
- Click **"Generate QR Code"** to get the corresponding QR code
把链接或二维码推给微信客户使用即可：
Distribute the link or QR code to your WeChat customers:
<img src="https://cdn.link-ai.tech/doc/wechat-customer-service_use.png" width="600"/>
## 五、使用
## 5. Usage
微信用户通过链接或二维码进入客服对话后，即可与 AI 进行多轮对话，支持文本、图片、语音等消息：
After WeChat users enter the customer service conversation via the link or QR code, they can chat with the AI across multiple turns, with support for text, image, and voice messages:
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-chat-demo.jpg" width="900"/>
除此之外，基于微信生态官方能力，还可将微信客服应用在公众号、小程序、视频号及视频号小店等场景，详情可查看企业微信管理后台 [微信客服 → 接入场景](https://work.weixin.qq.com/wework_admin/frame#/app/servicer) 的相关说明：
Beyond that, leveraging the official WeChat ecosystem, WeCom Customer Service can also be embedded into Official Accounts, Mini Programs, Video Channels and more. See the **WeCom Customer Service → Access Scenarios** section in the [WeCom Admin Console](https://work.weixin.qq.com/wework_admin/frame#/app/servicer) for details:
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-interface-demo.png" width="800"/>
## 常见问题
## FAQ
需要确保已安装以下依赖：
Make sure the following dependencies are installed:
```bash
pip install websocket-client pycryptodome

46
docs/channels/wechatmp.mdx
View File

@@ -1,22 +1,22 @@
---
title: 微信公众号
description: 将 CowAgent 接入微信公众号
title: WeChat Official Account
description: Integrate CowAgent with WeChat Official Accounts
---
CowAgent 支持接入个人订阅号和企业服务号两种公众号类型。
CowAgent supports both personal subscription accounts and enterprise service accounts.
| 类型 | 要求 | 特点 |
| Type | Requirements | Features |
| --- | --- | --- |
| **个人订阅号** | 个人可申请 | 收到消息时会回复一条提示，回复生成后需用户主动发消息获取 |
| **企业服务号** | 企业申请，需通过微信认证开通客服接口 | 回复生成后可主动推送给用户 |
| **Personal Subscription** | Available to individuals | Sends a placeholder reply first; users must send a message to retrieve the full response |
| **Enterprise Service** | Enterprise with verified customer service API | Can proactively push replies to users |
<Note>
公众号仅支持服务器和 Docker 部署，不支持本地运行。需额外安装扩展依赖：`pip3 install -r requirements-optional.txt`
Official Accounts only support server and Docker deployment, not local run mode. Install extended dependencies: `pip3 install -r requirements-optional.txt`
</Note>
## 一、个人订阅号
## 1. Personal Subscription Account
在 `config.json` 中添加以下配置：
Add the following configuration to `config.json`:
```json
{
@@ -30,34 +30,34 @@ CowAgent 支持接入个人订阅号和企业服务号两种公众号类型。
}
```
### 配置步骤
### Setup Steps
这些配置需要和 [微信公众号后台](https://mp.weixin.qq.com/advanced/advanced?action=dev&t=advanced/dev) 中的保持一致，进入页面后，在左侧菜单选择 **设置与开发 → 基本配置 → 服务器配置**，按下图进行配置：
These configurations must be consistent with the [WeChat Official Account Platform](https://mp.weixin.qq.com/advanced/advanced?action=dev&t=advanced/dev). Navigate to **Settings & Development → Basic Configuration → Server Configuration** and configure as shown below:
<img src="https://cdn.link-ai.tech/doc/20260228103506.png" width="480"/>
1. 在公众平台启用开发者密码（对应配置 `wechatmp_app_secret`），并将服务器 IP 填入白名单
2. 按上图填写 `config.json` 中与公众号相关的配置，要与公众号后台的配置一致
3. 启动程序，启动后会监听 80 端口（若无权限监听，则在启动命令前加上 `sudo`；若 80 端口已被占用，则关闭该占用进程）
4. 在公众号后台 **启用服务器配置** 并提交，保存成功则表示已成功配置。注意 **"服务器地址(URL)"** 需要配置为 `http://{HOST}/wx` 的格式，其中 `{HOST}` 可以是服务器的 IP 或域名
1. Enable the developer secret on the platform (corresponds to `wechatmp_app_secret`), and add the server IP to the whitelist
2. Fill in the `config.json` with the official account parameters matching the platform configuration
3. Start the program, which listens on port 80 (use `sudo` if you don't have permission; stop any process occupying port 80)
4. **Enable server configuration** on the official account platform and submit. A successful save means the configuration is complete. Note that the **"Server URL"** must be in the format `http://{HOST}/wx`, where `{HOST}` can be the server IP or domain
随后关注公众号并发送消息即可看到以下效果：
After following the account and sending a message, you should see the following result:
<img src="https://cdn.link-ai.tech/doc/20260228103522.png" width="720"/>
由于受订阅号限制，回复内容较短的情况下（15s 内），可以立即完成回复，但耗时较长的回复则会先回复一句 "正在思考中"，后续需要用户输入任意文字主动获取答案，而服务号则可以通过客服接口解决这一问题。
Due to subscription account limitations, short replies (within 15s) can be returned immediately, but longer replies will first send a "Thinking..." placeholder, requiring users to send any text to retrieve the answer. Enterprise service accounts can solve this with the customer service API.
<Tip>
**语音识别**：可利用微信自带的语音识别功能，需要在公众号管理页面的 "设置与开发 → 接口权限" 页面开启 "接收语音识别结果"。
**Voice Recognition**: You can use WeChat's built-in voice recognition. Enable "Receive Voice Recognition Results" under "Settings & Development → API Permissions" on the official account management page.
</Tip>
## 二、企业服务号
## 2. Enterprise Service Account
企业服务号与上述个人订阅号的接入过程基本相同，差异如下：
The setup process for enterprise service accounts is essentially the same as personal subscription accounts, with the following differences:
1. 在公众平台申请企业服务号并完成微信认证，在接口权限中确认已获得 **客服接口** 的权限
2. 在 `config.json` 中设置 `"channel_type": "wechatmp_service"`，其他配置与上述订阅号相同
3. 交互效果上，即使是较长耗时的回复，也可以主动推送给用户，无需用户手动获取
1. Register an enterprise service account on the platform and complete WeChat certification. Confirm that the **Customer Service API** permission has been granted
2. Set `"channel_type": "wechatmp_service"` in `config.json`; other configurations remain the same
3. Even for longer replies, they can be proactively pushed to users without requiring manual retrieval
```json
{

72
docs/channels/wecom-bot.mdx
View File

@@ -1,56 +1,56 @@
---
title: 企微智能机器人
description: 将 CowAgent 接入企业微信智能机器人（长连接模式）
title: WeCom Bot
description: Connect CowAgent to WeCom AI Bot (WebSocket long connection)
---
> 通过企业微信智能机器人接入CowAgent，支持企业内部单聊和内部群聊，无需公网 IP，使用 WebSocket 长连接模式，支持Markdown渲染和流式输出。
> Connect CowAgent via WeCom AI Bot, supporting both internal direct messages and group chats. No public IP required — uses a WebSocket long connection, with Markdown rendering and streaming output.
<Note>
智能机器人与企业微信自建应用是两种不同的接入方式。智能机器人使用 WebSocket 长连接，无需服务器公网 IP 和域名，配置更简单。
WeCom Bot and WeCom App are two different integration methods. WeCom Bot uses a WebSocket long connection and requires no public IP or domain, making setup much simpler.
</Note>
## 一、接入方式
## 1. Connection methods
### 方式一：扫码一键接入（推荐）
### Option A: One-click QR scan (recommended)
无需提前创建机器人，启动 Cow 项目后打开 Web 控制台（本地链接：http://127.0.0.1:9899/），选择 **通道** 菜单，点击**接入通道**，选择**企微智能机器人**，切换到「扫码接入」模式，使用**企业微信**扫码即可自动完成机器人创建和接入。
No need to create the bot ahead of time. Start CowAgent and open the Web console (local URL: http://127.0.0.1:9899/), go to the **Channels** tab, click **Connect Channel**, choose **WeCom Bot**, switch to **QR scan** mode, and scan the QR code with **WeCom** — bot creation and connection complete automatically.
<img src="https://cdn.link-ai.tech/doc/20260401121213.png" width="800"/>
<Note>
扫码成功后，可在企业微信工作台 - **智能机器人**页面对机器人进行进一步配置，包括修改名称、头像、可见范围等。
After a successful scan, you can further configure the bot (name, avatar, visibility scope, etc.) in **WeCom Workbench → AI Bot**.
</Note>
### 方式二：手动创建接入
### Option B: Manual creation
需要先在企业微信中创建智能机器人并获取 Bot ID 和 Secret，再通过 Web 控制台或配置文件接入。
Create the AI Bot in WeCom and obtain the Bot ID and Secret, then connect via the Web console or config file.
**步骤一：创建智能机器人**
**Step 1: Create the AI Bot**
1. 打开企业微信客户端，进入工作台，点击**智能机器人**：
1. Open the WeCom client, go to **Workbench**, and click **AI Bot**:
<img src="https://cdn.link-ai.tech/doc/20260316180959.png" width="800"/>
2. 点击创建机器人 - 手动创建：
2. Click **Create Bot → Manual Creation**:
<img src="https://cdn.link-ai.tech/doc/20260316181118.png" width="800"/>
3. 右侧窗口拖到最下方，选择**API模式创建**：
3. Scroll to the bottom of the right panel and select **API Mode**:
<img src="https://cdn.link-ai.tech/doc/20260316181215.png" width="800"/>
4. 设置机器人名称、头像、可见范围，并选择**长连接模式**，记录下 **Bot ID** 和 **Secret** 信息后点击保存。
4. Set the bot name, avatar, and visibility scope. Choose **Long Connection** mode, save the **Bot ID** and **Secret**, then click Save.
**步骤二：接入 CowAgent**
**Step 2: Connect to CowAgent**
<Tabs>
<Tab title="Web 控制台">
打开 Web 控制台，选择**通道**菜单，点击**接入通道**，选择**企微智能机器人**，切换到「手动填写」模式，输入 Bot ID 和 Secret，点击接入即可。
<Tab title="Web Console">
Open the Web console, go to the **Channels** tab, click **Connect Channel**, choose **WeCom Bot**, switch to **Manual** mode, enter the Bot ID and Secret, and click Connect.
<img src="https://cdn.link-ai.tech/doc/20260316181711.png" width="800"/>
</Tab>
<Tab title="配置文件">
在 `config.json` 中添加以下配置后启动程序：
<Tab title="Config File">
Add the following to `config.json`, then start CowAgent:
```json
{
@@ -60,31 +60,31 @@ description: 将 CowAgent 接入企业微信智能机器人（长连接模式）
}
```
| 参数 | 说明 |
| Parameter | Description |
| --- | --- |
| `wecom_bot_id` | 智能机器人的 BotID |
| `wecom_bot_secret` | 智能机器人的 Secret |
| `wecom_bot_id` | Bot ID of the AI Bot |
| `wecom_bot_secret` | Secret of the AI Bot |
</Tab>
</Tabs>
日志显示 `[WecomBot] Subscribe success` 即表示连接成功。
The log line `[WecomBot] Subscribe success` confirms the connection is established.
## 二、功能说明
## 2. Supported features
| 功能 | 支持情况 |
| Feature | Status |
| --- | --- |
| 单聊 | ✅ |
| 群聊（@机器人） | ✅ |
| 文本消息 | ✅ 收发 |
| 图片消息 | ✅ 收发 |
| 文件消息 | ✅ 收发 |
| 流式回复 | ✅ |
| 定时任务主动推送 | ✅ |
| Direct chat | ✅ |
| Group chat (@bot) | ✅ |
| Text messages | ✅ Send / Receive |
| Image messages | ✅ Send / Receive |
| File messages | ✅ Send / Receive |
| Streaming replies | ✅ |
| Scheduled push messages | ✅ |
## 三、使用
## 3. Usage
在企业微信中搜索创建的机器人名称，即可开始单聊对话。
Search for the bot's name inside WeCom to start a direct chat.
如需在企微内部群聊中使用，将机器人添加到群中，@机器人发送消息即可。
To use the bot in an internal group chat, add it to the group and @-mention it.
<img src="https://cdn.link-ai.tech/doc/20260316182902.png" width="800"/>

74
docs/channels/wecom.mdx
View File

@@ -1,48 +1,48 @@
---
title: 企微自建应用
description: 将 CowAgent 接入企业微信自建应用
title: WeCom
description: Integrate CowAgent into WeCom enterprise app
---
通过企业微信自建应用接入 CowAgent，支持企业内部人员单聊使用。
Integrate CowAgent into WeCom through a custom enterprise app, supporting one-on-one chat for internal employees.
<Note>
企业微信只能使用 Docker 部署或服务器 Python 部署，不支持本地运行模式。
WeCom only supports Docker deployment or server Python deployment. Local run mode is not supported.
</Note>
## 一、准备
## 1. Prerequisites
需要的资源：
Required resources:
1. 一台服务器（有公网 IP）
2. 注册一个企业微信（个人也可注册，但无法认证）
3. 认证企业微信还需要对应主体备案的域名
1. A server with public IP (overseas server, or domestic server with a proxy for international API access)
2. A registered WeCom account (individual registration is possible but cannot be certified)
3. Certified WeCom accounts additionally require a domain filed under the corresponding entity
## 二、创建企业微信应用
## 2. Create WeCom App
1. 在 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame#profile) 点击 **我的企业**，在最下方获取 **企业ID**（后续填写到 `wechatcom_corp_id` 字段中）。
1. In the [WeCom Admin Console](https://work.weixin.qq.com/wework_admin/frame#profile), click **My Enterprise** and find the **Corp ID** at the bottom of the page. Save this ID for the `wechatcom_corp_id` configuration field.
2. 切换到 **应用管理**，点击创建应用：
2. Switch to **Application Management** and click Create Application:
<img src="https://cdn.link-ai.tech/doc/20260228103156.png" width="480"/>
3. 进入应用创建页面，记录 `AgentId` 和 `Secret`：
3. On the application creation page, record the `AgentId` and `Secret`:
<img src="https://cdn.link-ai.tech/doc/20260228103218.png" width="580"/>
4. 点击 **设置API接收**，配置应用接口：
4. Click **Set API Reception** to configure the application interface:
<img src="https://cdn.link-ai.tech/doc/20260228103211.png" width="520"/>
- URL 格式为 `http://ip:port/wxcomapp`（认证企业需使用备案域名）
- 随机获取 `Token` 和 `EncodingAESKey` 并保存
- URL format: `http://ip:port/wxcomapp` (certified enterprises must use a filed domain)
- Generate random `Token` and `EncodingAESKey` and save them for the configuration file
<Note>
此时保存 API 接收配置会失败，因为程序还未启动，等项目运行后再回来保存。
The API reception configuration cannot be saved at this point because the program hasn't started yet. Come back to save it after the project is running.
</Note>
## 三、配置和运行
## 3. Configuration and Run
在 `config.json` 中添加以下配置（各参数与企业微信后台的对应关系见上方截图）：
Add the following configuration to `config.json` (the mapping between each parameter and the WeCom console is shown in the screenshots above):
```json
{
@@ -57,41 +57,41 @@ description: 将 CowAgent 接入企业微信自建应用
}
```
| 参数 | 说明 |
| Parameter | Description |
| --- | --- |
| `wechatcom_corp_id` | 企业 ID |
| `wechatcomapp_token` | API 接收配置中的 Token |
| `wechatcomapp_secret` | 应用的 Secret |
| `wechatcomapp_agent_id` | 应用的 AgentId |
| `wechatcomapp_aes_key` | API 接收配置中的 EncodingAESKey |
| `wechatcomapp_port` | 监听端口，默认 9898 |
| `wechatcom_corp_id` | Corp ID |
| `wechatcomapp_token` | Token from API reception config |
| `wechatcomapp_secret` | App Secret |
| `wechatcomapp_agent_id` | App AgentId |
| `wechatcomapp_aes_key` | EncodingAESKey from API reception config |
| `wechatcomapp_port` | Listen port, default 9898 |
配置完成后启动程序。当后台日志显示 `http://0.0.0.0:9898/` 时说明程序运行成功，需要将该端口对外开放（如在云服务器安全组中放行）。
After configuration, start the program. When the log shows `http://0.0.0.0:9898/`, the program is running successfully. You need to open this port externally (e.g., allow it in the cloud server security group).
程序启动后，回到企业微信后台保存 **消息服务器配置**，保存成功后还需将服务器 IP 添加到 **企业可信IP** 中，否则无法收发消息：
After the program starts, return to the WeCom Admin Console to save the **Message Server Configuration**. After saving successfully, you also need to add the server IP to **Enterprise Trusted IPs**, otherwise messages cannot be sent or received:
<img src="https://cdn.link-ai.tech/doc/20260228103224.png" width="520"/>
<Warning>
如遇到 URL 配置回调不通过或配置失败：
1. 确保服务器防火墙关闭且安全组放行监听端口
2. 仔细检查 Token、Secret Key 等参数配置是否一致，URL 格式是否正确
3. 认证企业微信需要配置与主体一致的备案域名
If the URL configuration callback fails or the configuration is unsuccessful:
1. Ensure the server firewall is disabled and the security group allows the listening port
2. Carefully check that Token, Secret Key and other parameter configurations are consistent, and that the URL format is correct
3. Certified WeCom accounts must configure a filed domain matching the entity
</Warning>
## 四、使用
## 4. Usage
在企业微信中搜索刚创建的应用名称，即可直接对话：
Search for the app name you just created in WeCom to start chatting directly. You can run multiple instances listening on different ports to create multiple WeCom apps:
<img src="https://cdn.link-ai.tech/doc/20260228103228.png" width="720"/>
如需让外部个人微信用户使用，可在 **我的企业 → 微信插件** 中分享邀请关注二维码，个人微信扫码关注后即可与应用对话：
To allow external personal WeChat users to use the app, go to **My Enterprise → WeChat Plugin**, share the invite QR code. After scanning and following, personal WeChat users can join and chat with the app:
<img src="https://cdn.link-ai.tech/doc/20260228103232.png" width="520"/>
## 常见问题
## FAQ
需要确保已安装以下依赖：
Make sure the following dependencies are installed:
```bash
pip install websocket-client pycryptodome

67
docs/channels/weixin.mdx
View File

@@ -1,21 +1,21 @@
---
title: 微信
description: 将 CowAgent 接入个人微信（基于官方接口）
title: WeChat
description: Connect CowAgent to personal WeChat (via the official API)
---
> 接入个人微信，扫码登录即可使用，支持文本、图片、语音、文件、视频等消息的私聊收发。通过微信官方API进行接入，无安全风险，接入后会在会话中新增一个机器人助手，不影响当前账号的使用。
> Connect CowAgent to your personal WeChat — scan to log in, no public IP required. Supports text, image, voice, file, and video messages in 1-on-1 chats. Backed by WeChat's official API; safe to use. After connecting, a bot assistant is added to your conversation list without affecting normal account usage.
## 一、配置和运行
## 1. Setup and run
### 方式一：Web 控制台接入
### Option A: Web console
启动 Cow 项目后打开 Web 控制台 (本地链接为: http://127.0.0.1:9899/ )，选择 **通道** 菜单，点击 **接入通道**，选择 **微信**，点击接入后按照提示扫码登录。
Start CowAgent and open the Web console (local URL: http://127.0.0.1:9899/). Go to the **Channels** tab, click **Connect Channel**, select **WeChat**, and follow the prompts to scan in.
<img src="https://cdn.link-ai.tech/doc/20260322195114.png" width="800" />
### 方式二：配置文件接入
### Option B: Config file
在 `config.json` 中设置 `channel_type` 为 `weixin`：
Set `channel_type` to `weixin` in `config.json`:
```json
{
@@ -23,52 +23,49 @@ description: 将 CowAgent 接入个人微信（基于官方接口）
}
```
启动程序后，终端会显示二维码，使用微信扫码授权即可完成登录。
After starting CowAgent, a QR code is displayed in the terminal. Scan it with WeChat to complete login.
<img src="https://cdn.link-ai.tech/doc/20260322195509.png" width="800" />
<Note>
1. 兼容历史配置：`channel_type` 设为 `wx` 同样可以启用微信通道。
2. 注意微信客户端需要更新至 8.0.69 版本或以上
1. For backward compatibility, setting `channel_type` to `wx` also activates the WeChat channel.
2. The WeChat client must be on version **8.0.69** or higher.
</Note>
## 二、使用说明
## 2. Usage
微信扫码并进行授权确认后，即可完成接入并开始对话。接入微信后会在对话中创建出一个机器人助理，不会对已有账号的正常使用有任何影响。
Once authorized, the integration completes and you can start chatting. A bot assistant is created in your WeChat conversation list, leaving normal account usage unaffected.
> 你可以通过搜索"微信ClawBot"随时找到这个机器人，还可以修改这个机器人的头像、备注等信息，将机器人置顶在消息列表等。
> You can find the bot at any time by searching for **"微信ClawBot"**. You may also rename it, change its avatar, pin it to the top of your conversation list, and so on.
<img src="https://cdn.link-ai.tech/doc/83ae8251d896219fde4803f4205205be.jpg" width="250" />
## 3. Login
### QR code login
## 三、登录说明
On first startup, a QR code appears in the terminal (valid for around 2 minutes). Scan it with WeChat and confirm on your phone to log in.
### 扫码登录
- The QR code refreshes automatically when it expires
- The `qrcode` dependency is already included in `requirements.txt`, so the QR code renders directly in the terminal after install
首次启动时，终端会显示一个二维码（有效期约 2 分钟）。使用微信扫描二维码并在手机上确认后即可完成登录。
### Credential persistence
- 二维码过期后会自动刷新并重新显示
- `requirements.txt` 中已默认包含 `qrcode` 依赖，安装后可在终端直接渲染二维码图案
After a successful login, credentials are saved to `~/.weixin_cow_credentials.json`. Subsequent startups reuse the saved credentials with no need to re-scan.
### 凭证保存
To force a re-login, delete the credentials file and restart.
登录成功后，凭证会自动保存至 `~/.weixin_cow_credentials.json`，下次启动时无需重新扫码。
### Session expiry
如需重新登录，删除该凭证文件后重启程序即可。
When the WeChat session expires (errcode `-14`), CowAgent automatically clears old credentials and initiates a new QR login — no manual intervention required.
### Session 过期
## 4. Supported features
当微信 session 过期时（errcode -14），程序会自动清除旧凭证并重新发起扫码登录，无需手动干预。
## 四、功能说明
| 功能 | 支持情况 |
| Feature | Status |
| --- | --- |
| 单聊 | ✅ |
| 文本消息 | ✅ 收发 |
| 图片消息 | ✅ 收发 |
| 文件消息 | ✅ 收发 |
| 视频消息 | ✅ 收发 |
| 语音消息 | ✅ 接收 (自带语音识别) |
| Direct messages | ✅ |
| Text messages | ✅ Send & Receive |
| Image messages | ✅ Send & Receive |
| File messages | ✅ Send & Receive |
| Video messages | ✅ Send & Receive |
| Voice messages | ✅ Receive (built-in speech recognition) |