# DingTalk
Source: https://docs.cowagent.ai/channels/dingtalk

Connect CowAgent to DingTalk: create an app with the bot capability on the DingTalk Open Platform, add the credentials, and chat in direct and group chats, with optional streaming cards.

Integrate CowAgent into DingTalk by creating an intelligent robot app on the DingTalk Open Platform.

## 1. Create 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:

![](https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/dingtalk-create-app.png)

2. Click **Add App Capability**, select **Robot** capability and click **Add**:

![](https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/dingtalk-add-bot.png)

> Optional: to reply with streaming Markdown cards, request the `Card.Instance.Write` and `Card.Streaming.Write` permissions under **Permission Management**, and add `"dingtalk_card_enabled": true` to `config.json`.

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:

![](https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/dingtalk-config-bot.png)

4. Click **Version Management & Release**, create a new version and publish:

![](https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/dingtalk-publish-bot.png)

## 2. Project Configuration

1. Click **Credentials & Basic Info**, get the `Client ID` and `Client Secret`:

![](https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/dingtalk-get-secret.png)

2. Add the following configuration to `config.json` in the project root:

```json theme={null}
{
  "channel_type": "dingtalk",
  "dingtalk_client_id": "YOUR_CLIENT_ID",
  "dingtalk_client_secret": "YOUR_CLIENT_SECRET"
}
```

3. Install the dependency:

```bash theme={null}
pip3 install dingtalk_stream
```

![](https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/dingtalk-app-config.png)

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:

![](https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/dingtalk-event-sub.png)

## 3. Usage

Chat privately with the robot or add it to an enterprise group to start a conversation:

![](https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/dingtalk-hosting-demo.png)


# Discord
Source: https://docs.cowagent.ai/channels/discord

Connect CowAgent to a Discord bot for DMs and server channels (@mention or reply). The Gateway WebSocket connection needs no public IP or callback URL; create the app and bot token to get started.

> 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

### Step 1: Create a Discord Application and Bot

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]
>
> This token is your bot's password — keep it secret. If it leaks, click **Reset Token** again on the Bot page to regenerate it.

### Step 2: Enable the Message Content Intent

Reading message text in both DMs and channels depends on this privileged 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.

### Step 3: Invite the Bot to a Server

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]
>
> 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).

### Step 4: Connect to CowAgent

**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.

**Config File**

Add the following to `config.json` and start Cow:

```json theme={null}
{
  "channel_type": "discord",
  "discord_token": "your-discord-bot-token",
  "discord_group_trigger": "mention_or_reply"
}
```

| Key | Description | Default |
| - | - | - |
| `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` |

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 |
| - | - |
| 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]
>
> A single Discord message is capped at 2000 characters; long replies are automatically split across multiple messages by line breaks.

## 3. Usage

Once connected:

* **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.


# Feishu (Lark)
Source: https://docs.cowagent.ai/channels/feishu

Connect CowAgent to a Feishu (Lark) custom app for direct and group chats. It uses a WebSocket connection with no public IP, supports one-scan app creation, streaming replies and voice messages.

> 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.

## 1. Setup

### 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.

![](https://cdn.link-ai.tech/doc/20260505181126.png)

> [!NOTE]
>
> 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).

When starting from CLI without `feishu_app_id` configured, the QR code is also printed to the terminal.

### Option 2: Manual Setup

Manually create a custom app on the Feishu Developer Platform, then connect via Web Console or config file.

**Step 1: Create the App**

1. Go to [Feishu Developer Platform](https://open.feishu.cn/app/), click **Create Enterprise Custom App**:

![](https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/feishu-hosting-create-app.jpg)

2. In **Add App Capabilities**, add the **Bot** capability:

![](https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/feishu-hosting-add-bot.jpg)

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
```

![](https://cdn.link-ai.tech/doc/feishu-hosting-add-auth2.png)

4. Get `App ID` and `App Secret` from **Credentials & Basic Info**:

![](https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/feishu-hosting-appid-secret.jpg)

**Step 2: Connect to CowAgent**

**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.

**Config File**

Add the following to `config.json` and start the program:

```json theme={null}
{
  "channel_type": "feishu",
  "feishu_app_id": "YOUR_APP_ID",
  "feishu_app_secret": "YOUR_APP_SECRET",
  "feishu_stream_reply": true
}
```

| Parameter | Description | Default |
| - | - | - |
| `feishu_app_id` | Feishu app App ID | - |
| `feishu_app_secret` | Feishu app App Secret | - |
| `feishu_stream_reply` | Enable streaming typewriter reply | `true` |
| `feishu_detailed_card` | Use a detailed card (tool calls, thinking process, elapsed time) for streaming replies; off keeps the plain typewriter card | `true` |

**Step 3: Publish the App**

1. After Cow is running, go to **Events & Callbacks** in the Feishu Developer Platform, choose **Long Connection** mode and save:

![](https://cdn.link-ai.tech/doc/202601311731183.png)

2. Click **Add Event**, search for "Receive Message" and choose **Receive Message v2.0**.

3. (Optional) Under **Callbacks**, add **Card Action Trigger** (`card.action.trigger`) to enable `/tasks` scheduler commands; add the **Message Recalled** (`im.message.recalled_v1`) event to cancel a task by recalling its message.

4. Click **Version Management & Release**, create a version and apply for **Production Release**. Approve the request in the Feishu client:

![](https://cdn.link-ai.tech/doc/202601311807356.png)

## 2. Features

| Feature | Status |
| - | - |
| P2P chat | ✅ |
| Group chat (@bot) | ✅ |
| Text messages | ✅ send/receive |
| Image messages | ✅ send/receive |
| Voice messages | ✅ send/receive |
| Quoted replies | ✅ quoted text and rich-post context |
| Streaming reply | ✅ (powered by Feishu cardkit streaming card) |
| Markdown card | ✅ remote images are uploaded to Feishu for static and final streaming cards |
| Detailed card | ✅ tool calls, thinking process and elapsed time (controlled by `feishu_detailed_card`, on by default) |
| Scheduler controls | ✅ `/tasks` list with enable, disable and delete buttons |

> [!NOTE]
>
> 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.

## 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.

Send `/tasks` in a private chat, or @-mention the bot with `/tasks` in a group, to manage tasks belonging to that chat.


# Channels Overview
Source: https://docs.cowagent.ai/channels/index

All channels CowAgent supports, with a matrix comparing image, file, voice and group chat support across WeChat, Feishu, DingTalk, WeCom, QQ, Telegram, Slack, Discord and the web console.

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 |
| - | :-: | :-: | :-: | :-: | :-: |
| [WeChat](/channels/weixin) | ✅ | ✅ | ✅ | ✅ | |
| [Web Console](/channels/web) | ✅ | ✅ | ✅ | ✅ | |
| [Feishu](/channels/feishu) | ✅ | ✅ | ✅ | ✅ | ✅ |
| [DingTalk](/channels/dingtalk) | ✅ | ✅ | ✅ | ✅ | ✅ |
| [WeCom Bot](/channels/wecom-bot) | ✅ | ✅ | ✅ | ✅ | ✅ |
| [QQ](/channels/qq) | ✅ | ✅ | ✅ | ✅ | ✅ |
| [WeCom App](/channels/wecom) | ✅ | ✅ | ✅ | ✅ | |
| [Official Account](/channels/wechatmp) | ✅ | ✅ | | ✅ | |
| [WeChat Customer Service](/channels/wechat-kf) | ✅ | ✅ | ✅ | ✅ | |
| [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]
>
> The voice / image capabilities of each channel depend on the configuration of the corresponding model provider. See [Models Overview](/models/index) for details.

## Channel List

* [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


# QQ Bot
Source: https://docs.cowagent.ai/channels/qq

Connect CowAgent to a QQ bot for direct chats, group chats (@bot), guild channel messages and DMs. Built on the QQ Open Platform with a WebSocket connection, so no public IP or domain is needed.

> 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 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.

## 1. Create a QQ Bot

> 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.Go to the [QQ Open Platform - Bot List](https://q.qq.com/#/apps), and click **Create Bot**:

![](https://cdn.link-ai.tech/doc/20260317162900.png)

2.Fill in the bot name, avatar, and other basic information to complete the creation:

![](https://cdn.link-ai.tech/doc/20260317163005.png)

3.Enter the bot configuration page, go to **Development Management**, and complete the following steps:

* Copy and save the **AppID** (Bot ID)
* Generate and save the **AppSecret** (Bot Secret)

![](https://cdn.link-ai.tech/doc/20260317164955.png)

## 2. Configuration and Running

### Option A: Web Console

Start the program and open the Web console (local access: [http://127.0.0.1:9899/](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.

![](https://cdn.link-ai.tech/doc/20260317165425.png)

### Option B: Config File

Add the following to your `config.json`:

```json theme={null}
{
  "channel_type": "qq",
  "qq_app_id": "YOUR_APP_ID",
  "qq_app_secret": "YOUR_APP_SECRET"
}
```

| Parameter | Description |
| - | - |
| `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 |

After configuration, start the program. The log message `[QQ] ✅ Connected successfully` indicates a successful connection.

## 3. Usage

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:

![](https://cdn.link-ai.tech/doc/20260317165947.png)

Chat example:

![](https://cdn.link-ai.tech/doc/20260317171508.png)

## 4. Supported Features

> 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 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

* **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.


# Slack
Source: https://docs.cowagent.ai/channels/slack

Connect CowAgent to a Slack app for DMs and channel conversations (@mention or thread replies). Socket Mode needs no public IP or callback URL; follow the steps to create the app and tokens.

> 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

### Step 1: Create a Slack App

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.

### Step 2: Enable Socket Mode and get the App 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 receives events over a WebSocket connection, so you don't need to expose a public callback URL — ideal for local or intranet deployments.

### Step 3: Configure bot scopes and install

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
   channels:history
   chat:write
   commands
   files:read
   files:write
   groups:history
   im:history
   mpim:history
   users:read
   ```

   > [!NOTE]
   >
   > `files:read` / `files:write` are used for sending/receiving images and files; omit them if you only need text conversations.

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
   message.im
   message.channels
   ```

   > [!NOTE]
   >
   > Add `message.groups` if you need to use the bot in private channels.

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]
>
> 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).

### Step 4: Connect to CowAgent

**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.

**Config File**

Add the following to `config.json` and start Cow:

```json theme={null}
{
  "channel_type": "slack",
  "slack_bot_token": "xoxb-xxxxxxxxxxxx",
  "slack_app_token": "xapp-xxxxxxxxxxxx",
  "slack_group_trigger": "mention_or_reply"
}
```

| Key | Description | Default |
| - | - | - |
| `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` |

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 |
| - | - |
| 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 organizes conversations into threads. The bot posts replies into the thread of the triggering message, keeping channels tidy.

## 3. Usage

Once connected:

* **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.


# Telegram
Source: https://docs.cowagent.ai/channels/telegram

Connect CowAgent to a Telegram bot: create it with BotFather, add the token, and chat in DMs or groups (@mention or reply). Uses long polling, so no public IP is required.

> 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

### Step 1: Create a Bot via BotFather

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]
>
> The token is the password of your bot — never share it. If it leaks, send `/revoke` to `@BotFather` to reset it.

### Step 2: (Group chat only) Disable Privacy Mode

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.

Send the following to `@BotFather`:

1. `/setprivacy`
2. Pick the bot you just created
3. Choose `Disable`

> [!NOTE]
>
> If the bot is still silent in groups after this, try removing it from the group and adding it back.

### Step 3: Connect to CowAgent

**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.

**Config File**

Add the following to `config.json` and start Cow:

```json theme={null}
{
  "channel_type": "telegram",
  "telegram_token": "123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ",
  "telegram_group_trigger": "mention_or_reply"
}
```

| Key | Description | Default |
| - | - | - |
| `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` |

The integration is ready when you see logs like:

```
[Telegram] Bot logged in as @my_cowagent_bot (id=123456789)
[Telegram] Registered 10 bot commands
[Telegram] ✅ Telegram bot ready, polling for updates
```

## 2. Capabilities

| Feature | Support |
| - | - |
| 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

On startup, the channel registers a command menu with BotFather. Typing `/` in Telegram shows a dropdown:

| Command | Description |
| - | - |
| `/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 |
| `/steer` | Guide the running Agent task (`/steer <instruction>`) |
| `/logs` | View recent logs |
| `/version` | Show version |

> [!NOTE]
>
> Telegram's command menu only displays top-level commands; subcommands are entered with a space, e.g. `/skill list`, `/context clear`.

## 3. Usage

Once connected:

* **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).

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.


# Web Console
Source: https://docs.cowagent.ai/channels/web

The web console is CowAgent's default channel: chat in your browser, manage models, skills, memory and channels online, protect it with a password, and enable an OpenAI-compatible chat API.

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 theme={null}
{
  "channel_type": "web",
  "web_host": "0.0.0.0",
  "web_port": 9899,
  "web_password": "",
  "external_api_enabled": false,
  "external_api_token": "",
  "enable_thinking": false
}
```

| Parameter | Description | Default |
| - | - | - |
| `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` | `""` |
| `external_api_enabled` | Turn on the [Chat API](/extensions/chat-api) | `false` |
| `external_api_token` | API key of the [Chat API](/extensions/chat-api), kept while the API is off | `""` |
| `web_session_expire_days` | Login session validity in days | `30` |
| `web_file_serve_root` | Additional root directory the web console can directly read/send files from (defaults to the user home directory). Configured Agent workspaces, including disabled Agents, and opened project directories are also allowed; set to `/` to allow the whole filesystem | `"~"` |
| `enable_thinking` | Whether to enable deep thinking mode | `false` |

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:

* Local: `http://localhost:9899`
* Server: `http://<server-ip>:9899`

> [!NOTE]
>
> Ensure the server firewall and security group allow the corresponding port.

## HTTPS and Domain Access

To serve the console on a domain with HTTPS, use one of the two setups below.

**Option 1: nginx reverse proxy (recommended).** Let nginx terminate TLS and forward plain HTTP to the console, and set `"web_host": "127.0.0.1"` so the console is only reachable through nginx:

```nginx theme={null}
server {
    listen 443 ssl;
    server_name cow.example.com;

    ssl_certificate     /etc/letsencrypt/live/cow.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/cow.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:9899;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        # Replies stream over SSE: keep connections open and unbuffered
        proxy_read_timeout 3600s;
        proxy_buffering off;
        # File uploads up to 512 MB
        client_max_body_size 512m;
    }
}
```

**Option 2: direct HTTPS.** The console serves TLS itself:

```json theme={null}
{
  "web_https_enabled": true,
  "web_ssl_certfile": "/etc/letsencrypt/live/cow.example.com/fullchain.pem",
  "web_ssl_keyfile": "/etc/letsencrypt/live/cow.example.com/privkey.pem"
}
```

| Parameter | Description | Default |
| - | - | - |
| `web_https_enabled` | Serve the console over HTTPS directly | `false` |
| `web_ssl_certfile` | PEM certificate file (full chain recommended) | `""` |
| `web_ssl_keyfile` | PEM private key file | `""` |

A missing or unreadable certificate stops startup with an error instead of falling back to HTTP.

> [!NOTE]
>
> The console must be served at the root path; use a dedicated subdomain rather than a sub-path such as `/cow/`. If you use MCP servers with OAuth, also set `"mcp_oauth_redirect_base": "https://cow.example.com"`.

## Chat API

The Web Console's port also serves an OpenAI-compatible chat API, `/v1/chat/completions`. It is off by default; turn it on and get an API key from the Chat API card on the settings page. See [Chat API](/extensions/chat-api).

## Features

### Chat Interface

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.

![](https://cdn.link-ai.tech/doc/20260227180120.png)

#### Multi-Session Management

The chat interface supports multi-session management. All session records are persistently stored in the database:

* **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
* **Workspace / Model / Permission**: Set a workspace, model, and permission mode for the current session below the input box. When you work across several projects, past sessions are grouped by project automatically. See [Architecture - Project Workspace](/intro/architecture#project-workspace)

![](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/web-console-workspace-project-demo.png)

Sessions grouped by workspace, with a per-session workspace and model

#### Permission Modes

Each session can run under its own permission mode, controlling how far the Agent can reach into files and commands: read-only, workspace-write, or full-access. When a tool call is blocked, the hint is clickable so you can adjust the permission on the spot.

![](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/web-console-access-mode.png)

Per-session permission modes: read-only, workspace-write, full-access

### Artifacts

Collects the pages, documents, images and videos your agents create on one timeline, with preview, pinning, and a jump back to the original conversation. The page is hidden by default; show it from the [Custom Menu](/extensions/custom-menu) editor:

![](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/web-console-artifacts.png)

### Model Management

Manage text, image, voice, and embedding model configurations for different providers online — no need to edit config files manually:

![](https://cdn.link-ai.tech/doc/20260521212949.png)

### Skill Management

View and manage Agent skills (Skills) online:

![](https://cdn.link-ai.tech/doc/20260227173403.png)

### Memory Management

View and manage Agent memory online:

![](https://cdn.link-ai.tech/doc/20260227173349.png)

### Channel Management

Manage connected channels online with real-time connect/disconnect operations:

![](https://cdn.link-ai.tech/doc/20260227173331.png)

### Scheduled Tasks

View and manage scheduled tasks online, including one-time tasks, fixed intervals, and Cron expressions:

![](https://cdn.link-ai.tech/doc/20260227173704.png)

### Logs

View Agent runtime logs in real time for monitoring and troubleshooting:

![](https://cdn.link-ai.tech/doc/20260227173514.png)


# WeChat Customer Service
Source: https://docs.cowagent.ai/channels/wechat-kf

Connect CowAgent to WeChat Customer Service through a WeCom custom app to answer external WeChat users from Official Accounts, Mini Programs and Channels, with text, image and voice messages.

By binding a WeCom custom enterprise app to a WeChat 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]
>
> WeChat Customer Service only supports Docker deployment or server Python deployment. A publicly reachable callback URL is required; local run mode is not supported.

## 1. Prerequisites

Required resources:

1. A server with a public IP
2. A registered and verified WeCom account
3. WeChat Customer Service capability enabled

> [!NOTE]
>
> 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.

## 2. Create a WeCom Custom App

1. In the [WeCom Admin Console](https://work.weixin.qq.com/wework_admin/frame#apps), go to **Application Management → Create Application**:

![](https://cdn.link-ai.tech/doc/20260228103156.png)

2. Click **My Enterprise** and find the **Corp ID** at the bottom of the page (it goes into `wechat_kf_corp_id`):

![](https://cdn.link-ai.tech/doc/wechatcom-hosting-companyid.png)

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:

![](https://cdn.link-ai.tech/doc/wechatcom-hosting-agent-secret.png)

4. Open the app's **Receive Messages → Set API Reception** page, click **"Random Generate"** to generate the **Token** and **EncodingAESKey**, and save them:

![](https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wechatcom-hosting-token-aeskey.jpg)

> [!NOTE]
>
> 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.

## 3. Configuration and Run

Fill in the 4 fields collected from the previous step (Corp ID / Secret / Token / EncodingAESKey):

**Web Console**

Start the Cow project and open the Web Console. Go to the **Channels** menu, click **Connect**, choose **WeChat Customer Service**, fill in Corp ID / Secret / Token / AES Key (port defaults to 9888, configurable), and click Connect.

![](https://cdn.link-ai.tech/doc/cow-weixinkefu-web-control.png)

**Config File**

Add the following configuration to `config.json` (each parameter maps to a field shown in the screenshots above):

```json theme={null}
{
  "channel_type": "wechat_kf",
  "wechat_kf_corp_id": "YOUR_CORP_ID",
  "wechat_kf_secret": "YOUR_SECRET",
  "wechat_kf_token": "YOUR_TOKEN",
  "wechat_kf_aes_key": "YOUR_AES_KEY",
  "wechat_kf_port": 9888
}
```

| Parameter | Description |
| - | - |
| `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 |

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).

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:

![](https://cdn.link-ai.tech/doc/wechat-com_config.png)

![](https://cdn.link-ai.tech/doc/20260228103224.png)

> [!WARNING]
>
> 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

## 4. Bind a WeChat Customer Service Account

In the WeCom Admin Console, go to **WeChat Customer Service**, create a customer service account, and bind it to the custom app you created above:

![](https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-step1.jpg)

![](https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-step2.jpg)

![](https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-step3.jpg)

After binding, go to **WeChat Customer Service → Account Details**, and under **"Access Link"**:

* 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:

![](https://cdn.link-ai.tech/doc/wechat-customer-service_use.png)

## 5. Usage

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:

![](https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-chat-demo.jpg)

Beyond that, leveraging the official WeChat ecosystem, WeChat Customer Service can also be embedded into Official Accounts, Mini Programs, Video Channels and more. See the **WeChat Customer Service → Access Scenarios** section in the [WeCom Admin Console](https://work.weixin.qq.com/wework_admin/frame#/app/servicer) for details:

![](https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-interface-demo.png)

## FAQ

Make sure the following dependencies are installed:

```bash theme={null}
pip install websocket-client pycryptodome
```


# WeChat Official Account
Source: https://docs.cowagent.ai/channels/wechatmp

Connect CowAgent to a WeChat Official Account, either a personal subscription account or a service account. Requires server or Docker deployment and server configuration in the account backend.

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]
>
> Official Accounts only support server and Docker deployment, not local run mode. Install extended dependencies: `pip3 install -r requirements-optional.txt`

## 1. Personal Subscription Account

Add the following configuration to `config.json`:

```json theme={null}
{
  "channel_type": "wechatmp",
  "single_chat_prefix": [""],
  "wechatmp_app_id": "wx73f9******d1e48",
  "wechatmp_app_secret": "YOUR_APP_SECRET",
  "wechatmp_aes_key": "",
  "wechatmp_token": "YOUR_TOKEN",
  "wechatmp_port": 80
}
```

### Setup Steps

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:

![](https://cdn.link-ai.tech/doc/20260228103506.png)

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:

![](https://cdn.link-ai.tech/doc/20260228103522.png)

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.

## 2. Enterprise Service Account

The setup process for enterprise service accounts is essentially the same as personal subscription accounts, with the following differences:

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 theme={null}
{
  "channel_type": "wechatmp_service",
  "single_chat_prefix": [""],
  "wechatmp_app_id": "YOUR_APP_ID",
  "wechatmp_app_secret": "YOUR_APP_SECRET",
  "wechatmp_aes_key": "",
  "wechatmp_token": "YOUR_TOKEN",
  "wechatmp_port": 80
}
```


# WeCom
Source: https://docs.cowagent.ai/channels/wecom

Connect CowAgent to a WeCom custom app for direct chats inside your organization. Needs a server with a public IP and Docker or server deployment; follow the steps to set up the app and callbacks.

Integrate CowAgent into WeCom through a custom enterprise app, supporting one-on-one chat for internal employees.

> [!NOTE]
>
> WeCom only supports Docker deployment or server Python deployment. Local run mode is not supported.

## 1. Prerequisites

Required resources:

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. 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. Switch to **Application Management** and click Create Application:

![](https://cdn.link-ai.tech/doc/20260228103156.png)

3. On the application creation page, record the `AgentId` and `Secret`:

![](https://cdn.link-ai.tech/doc/20260228103218.png)

4. Click **Set API Reception** to configure the application interface:

![](https://cdn.link-ai.tech/doc/20260228103211.png)

* 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]
>
> 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.

## 3. Configuration and Run

Add the following configuration to `config.json` (the mapping between each parameter and the WeCom console is shown in the screenshots above):

```json theme={null}
{
  "channel_type": "wechatcom_app",
  "single_chat_prefix": [""],
  "wechatcom_corp_id": "YOUR_CORP_ID",
  "wechatcomapp_token": "YOUR_TOKEN",
  "wechatcomapp_secret": "YOUR_SECRET",
  "wechatcomapp_agent_id": "YOUR_AGENT_ID",
  "wechatcomapp_aes_key": "YOUR_AES_KEY",
  "wechatcomapp_port": 9898
}
```

| Parameter | Description |
| - | - |
| `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 |

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).

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:

![](https://cdn.link-ai.tech/doc/20260228103224.png)

> [!WARNING]
>
> 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

## 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:

![](https://cdn.link-ai.tech/doc/20260228103228.png)

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:

![](https://cdn.link-ai.tech/doc/20260228103232.png)

## FAQ

Make sure the following dependencies are installed:

```bash theme={null}
pip install websocket-client pycryptodome
```


# WeCom Bot
Source: https://docs.cowagent.ai/channels/wecom-bot

Connect CowAgent to a WeCom smart bot for internal direct and group chats. It uses a WebSocket connection with no public IP or domain, supports one-scan setup, Markdown and streaming output.

> 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]
>
> 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.

## 1. Connection methods

### Option A: One-click QR scan (recommended)

No need to create the bot ahead of time. Start CowAgent and open the Web console (local URL: [http://127.0.0.1:9899/](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.

![](https://cdn.link-ai.tech/doc/20260401121213.png)

> [!NOTE]
>
> After a successful scan, you can further configure the bot (name, avatar, visibility scope, etc.) in **WeCom Workbench → AI Bot**.

### Option B: Manual creation

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. Open the WeCom client, go to **Workbench**, and click **AI Bot**:

![](https://cdn.link-ai.tech/doc/20260316180959.png)

2. Click **Create Bot → Manual Creation**:

![](https://cdn.link-ai.tech/doc/20260316181118.png)

3. Scroll to the bottom of the right panel and select **API Mode**:

![](https://cdn.link-ai.tech/doc/20260316181215.png)

4. Set the bot name, avatar, and visibility scope. Choose **Long Connection** mode, save the **Bot ID** and **Secret**, then click Save.

**Step 2: Connect to CowAgent**

**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.

![](https://cdn.link-ai.tech/doc/20260316181711.png)

**Config File**

Add the following to `config.json`, then start CowAgent:

```json theme={null}
{
  "channel_type": "wecom_bot",
  "wecom_bot_id": "YOUR_BOT_ID",
  "wecom_bot_secret": "YOUR_SECRET"
}
```

| Parameter | Description |
| - | - |
| `wecom_bot_id` | Bot ID of the AI Bot |
| `wecom_bot_secret` | Secret of the AI Bot |

The log line `[WecomBot] Subscribe success` confirms the connection is established.

> [!NOTE]
>
> A **webhook (HTTP callback) mode** is also supported: when creating the bot, choose **Use URL callback**, set the receive-message URL to `http(s)://<your-domain-or-ip>:9892/wecombot`, and copy the Token and EncodingAESKey from that page. This mode needs a publicly reachable address and does not support file sending or scheduled push, so the long connection is generally recommended. The corresponding `config.json`:
>
> ```json theme={null}
> {
>   "channel_type": "wecom_bot",
>   "wecom_bot_mode": "webhook",
>   "wecom_bot_token": "YOUR_TOKEN",
>   "wecom_bot_encoding_aes_key": "YOUR_ENCODING_AES_KEY",
>   "wecom_bot_port": 9892
> }
> ```

## 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.

![](https://cdn.link-ai.tech/doc/20260316182902.png)


# WeChat
Source: https://docs.cowagent.ai/channels/weixin

Connect CowAgent to personal WeChat through the official API. Log in by scanning a QR code to chat privately with text, images, voice, files and video, without affecting your account.

> 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

### Option A: Web console

Start CowAgent and open the Web console (local URL: [http://127.0.0.1:9899/](http://127.0.0.1:9899/)). Go to the **Channels** tab, click **Connect Channel**, select **WeChat**, and follow the prompts to scan in.

![](https://cdn.link-ai.tech/doc/20260322195114.png)

### Option B: Config file

Set `channel_type` to `weixin` in `config.json`:

```json theme={null}
{
  "channel_type": "weixin"
}
```

After starting CowAgent, a QR code is displayed in the terminal. Scan it with WeChat to complete login.

![](https://cdn.link-ai.tech/doc/20260322195509.png)

> [!NOTE]
>
> 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.

## 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.

> 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.

![](https://cdn.link-ai.tech/doc/83ae8251d896219fde4803f4205205be.jpg)

> [!NOTE]
>
> Due to WeChat platform limits, the bot can only send proactive messages within 24 hours of the user's last message. After that, scheduled task pushes will fail until the user sends any message again.

## 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

### Credential persistence

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.

### Session expiry

When the WeChat session expires (errcode `-14`), CowAgent automatically clears old credentials and initiates a new QR login — no manual intervention required.

## 4. Supported features

| 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) |


# Backup and Restore
Source: https://docs.cowagent.ai/cli/backup

Export and restore CowAgent configuration and workspace data as a portable archive, including config.json, persona files, memory, sessions, knowledge, custom skills and scheduled tasks.

CowAgent can create a portable local archive for migration or disaster recovery.

## Create a backup

```bash theme={null}
cow backup
cow backup --output /safe/location/cow-backup.zip
```

The archive contains:

* `config.json`
* Agent persona and user files such as `AGENT.md`, `USER.md`, and `MEMORY.md`
* Daily memory, session history, knowledge, custom skills, and scheduled tasks in the configured workspace
* The Agent registry, channel bindings, and every configured Agent workspace when multi-Agent mode is configured
* Legacy `user_datas.pkl`, when present

Transient `tmp/` data, caches, Git metadata, and symbolic links are skipped. The
archive is written with owner-only permissions where the operating system
supports them.

> [!WARNING]
>
> A backup may contain API keys, conversation history, and other personal data.
> Store and transfer it as a secret. The ZIP file is not encrypted.

## Restore a backup

Stop CowAgent before restoring:

```bash theme={null}
cow stop
cow restore /safe/location/cow-backup.zip
```

Use `--workspace` to migrate workspace files to a different location:

```bash theme={null}
cow restore cow-backup.zip --workspace ~/cow-restored
```

For a multi-Agent archive, `--workspace` is the instance root. CowAgent restores
the default Agent into that root and every other Agent into
`<root>/agents/<agent-id>`, the same layout the Agent registry derives on its
own. Without the option, Agent IDs that already exist locally keep their current
workspace, and the rest are placed under the instance root this machine already
uses.

Restore validates the archive format and paths before writing anything. It
overwrites matching files but does not delete unrelated files already present
at the destination. When current CowAgent data exists, the command first
creates a `cow-pre-restore-*.zip` rollback archive beside the selected backup.

For unattended scripts, pass `--yes` to acknowledge overwrites.


# General Commands
Source: https://docs.cowagent.ai/cli/general

Reference for everyday CowAgent commands such as help, status, cancel, steer, config and context, usable with / in chat or cow in a terminal to check status, stop tasks and manage settings.

The following commands can be used in chat with the `/` prefix or in the terminal with the `cow` prefix (some are chat-only).

> [!TIP]
>
> In the Web console, typing `/` brings up an autocomplete menu with keyboard navigation and Tab completion.

## help

Show help information for all available commands.

```text theme={null}
/help
```

## status

View current session and service status, including process info, model configuration, message count, loaded skills, and loaded MCP servers (ready/configured).

```text theme={null}
/status
```

## cancel

Abort the agent task currently running in this session. When the agent is busy with a long task (e.g. multi-turn tool calls or a long streaming response), send `/cancel` and the agent will stop before the next tool execution. Available across all channels — Web, WeChat, WeCom, Feishu, etc.

```text theme={null}
/cancel
```

## steer

Redirect the Agent task currently running in this session without cancelling it. The instruction is injected at the next safe checkpoint; a tool that is already running may finish, while tools that have not started are skipped. If no task is active, `/steer` does not start or queue a new one. Available across all chat channels.

```text theme={null}
/steer focus on the failing tests first
```

In the Web console, enter an instruction while a reply is running and click **Steer active task**. Sending an ordinary message still uses the session queue.

## config

View or modify runtime configuration. Changes take effect immediately without restarting.

**View all configurable items:**

```text theme={null}
/config
```

**View a single item:**

```text theme={null}
/config model
```

**Modify a config item:**

```text theme={null}
/config model deepseek-flash
```

**Configurable items:**

| Item | Description | Example |
| - | - | - |
| `model` | AI model name | `deepseek-flash` |
| `agent_max_context_tokens` | Max context tokens | `200000` |
| `agent_max_context_turns` | Max context memory turns | `30` |
| `agent_max_steps` | Max decision steps per task | `100` |
| `enable_thinking` | Enable deep thinking mode | `true` / `false` |

> [!NOTE]
>
> When changing `model`, the system automatically matches the corresponding model API. Configuration is persisted to `config.json`.

## context

View current session context statistics, including message count and content length.

```text theme={null}
/context
```

**Clear current session context:**

```text theme={null}
/clear
```

> [!TIP]
>
> Clearing context makes the Agent "forget" previous conversation, useful for switching topics or freeing context space. `/context clear` still works as an alias.

## compact

Summarize older turns to free up context while keeping recent turns intact. Unlike automatic trimming, this runs immediately regardless of current token usage.

```text theme={null}
/compact
```

> [!TIP]
>
> Use `/compact` before a long task to reclaim context space without fully clearing the conversation. Recent turns and an LLM summary of older turns are retained.

## logs

View recent service logs. Shows the last 20 lines by default, up to 50.

```text theme={null}
/logs
```

**Specify line count:**

```text theme={null}
/logs 50
```

## version

Show the current CowAgent version.

```text theme={null}
/version
```


# Commands Overview
Source: https://docs.cowagent.ai/cli/index

Overview of CowAgent commands: use the cow CLI in a terminal to run, update and manage the service and skills, or type / commands in chat to check status and change settings.

CowAgent provides two ways to interact via commands:

* **Terminal CLI** — Run `cow <command>` in your system terminal for service management, skill management, and other operations
* **Chat Commands** — Type `/<command>` or `cow <command>` in any conversation to check status, manage skills, adjust configuration, etc.

## Cow CLI

After deploying with the one-click install script, the `cow` command is automatically available. For manual installations, run:

```bash theme={null}
pip install -e .
```

Then use the `cow` command from anywhere:

```bash theme={null}
cow help
```

Example output:

```
🐮 CowAgent CLI

Usage: cow <command>

Service:
  start     Start the CowAgent service
  stop      Stop the CowAgent service
  restart   Restart the CowAgent service
  update    Update code and restart service
  status    Show service status
  logs      View service logs

Skills:
  skill     Manage skills (list / search / install / uninstall ...)

Memory & Knowledge:
  memory    Memory distillation (dream)
  knowledge View knowledge base stats and structure

Data portability:
  backup    Back up config and agent workspace
  restore   Restore a CowAgent backup

Others:
  help      Show this help message
  version   Show version
```

## Chat Commands

In the Web console or any connected channel, type `/` to see command suggestions. Supported commands:

| Command | Description |
| - | - |
| `/help` | Show command help |
| `/status` | View service status and configuration |
| `/cancel` | Abort the currently running agent task |
| `/steer <instruction>` | Guide the currently running agent task without queueing a new turn |
| `/config` | View or modify runtime configuration |
| `/skill` | Manage skills (install, uninstall, enable, disable, etc.) |
| `/memory dream [N]` | Manually trigger memory distillation (default 3 days, max 30) |
| `/knowledge` | View knowledge base statistics |
| `/knowledge list` | View knowledge base directory structure |
| `/knowledge on\|off` | Enable or disable knowledge base |
| `/context` | View current session context info |
| `/context clear` | Clear current session context |
| `/logs` | View recent logs |
| `/version` | Show version number |

> [!TIP]
>
> Service management commands like `/start`, `/stop`, `/restart` will prompt you to use them in the terminal instead, as they involve process operations.

## Command Availability

| Command | Terminal (`cow`) | Chat (`/`) |
| - | :-: | :-: |
| help | ✓ | ✓ |
| version | ✓ | ✓ |
| status | ✓ | ✓ |
| logs | ✓ | ✓ |
| cancel | ✗ | ✓ |
| config | ✗ | ✓ |
| context | — | ✓ |
| memory (subcommands) | ✗ | ✓ |
| knowledge (subcommands) | ✓ | ✓ |
| skill (subcommands) | ✓ | ✓ |
| start / stop / restart | ✓ | ✗ |
| update | ✓ | ✗ |
| install-browser | ✓ | ✗ |
| backup / restore | ✓ | ✗ |

> [!NOTE]
>
> `context` only shows a hint in the terminal to use it in chat. `config` is only available in chat.


# Memory & Knowledge
Source: https://docs.cowagent.ai/cli/memory-knowledge

Memory and knowledge commands: run memory dream to distill recent daily memories into MEMORY.md and a dream diary on demand, and use knowledge to view and manage the personal knowledge base.

## memory

Manage the Agent's long-term memory system.

### memory dream

Manually trigger memory distillation (Deep Dream) — consolidate recent daily memories into MEMORY.md and generate a dream diary.

```text theme={null}
/memory dream [N]
```

* `N`: Consolidate the last N days of memory (default 3, max 30)
* Runs asynchronously in the background; you'll be notified in chat when complete
* Works without Agent initialization — can be used before the first conversation

**Examples:**

```text theme={null}
/memory dream       # Consolidate last 3 days
/memory dream 7     # Consolidate last 7 days
/memory dream 30    # Consolidate last 30 days (full)
```

On the Web console, the completion notification includes clickable links to view the updated MEMORY.md and dream diary.

> [!TIP]
>
> The system automatically runs distillation daily at 23:55 (lookback 1 day). Manual trigger is useful for consolidating historical memories after first deployment, or when you need an immediate memory update.

## knowledge

View and manage the personal knowledge base. Shows statistics by default.

```text theme={null}
/knowledge
```

### knowledge list

View the knowledge base directory tree.

```text theme={null}
/knowledge list
```

### knowledge on / off

Enable or disable the knowledge base. When disabled, knowledge prompts and file indexing are not injected.

```text theme={null}
/knowledge on
/knowledge off
```

> [!NOTE]
>
> In the terminal CLI, `cow knowledge` and `cow knowledge list` are available, but `on|off` is only supported in chat (requires runtime effect).


# Process Management
Source: https://docs.cowagent.ai/cli/process

Manage the CowAgent background process with the cow command: start, stop, restart, update (pull code, update dependencies and restart), check status and view logs.

Process management commands control the CowAgent background process. These commands are only available in the terminal.

## start

Start the CowAgent service. Runs as a background daemon by default and automatically tails logs.

```bash theme={null}
cow start
```

**Options:**

| Option | Description |
| - | - |
| `-f`, `--foreground` | Run in foreground, not as a background daemon |
| `--no-logs` | Don't tail logs after starting |

## stop

Stop the running CowAgent service.

```bash theme={null}
cow stop
```

## restart

Restart the CowAgent service (stop then start).

```bash theme={null}
cow restart
```

**Options:**

| Option | Description |
| - | - |
| `--no-logs` | Don't tail logs after restart |

## update

Update code and restart the service. Automatically performs:

1. Pull latest code (`git pull`)
2. Stop current service
3. Update Python dependencies
4. Reinstall CLI
5. Start service

```bash theme={null}
cow update
```

> [!WARNING]
>
> If `git pull` fails (e.g., uncommitted local changes), the update aborts and the service remains unaffected.

## status

Check CowAgent service status, including process info, version, and current model/channel configuration.

```bash theme={null}
cow status
```

## logs

View service logs.

```bash theme={null}
cow logs
```

**Options:**

| Option | Description | Default |
| - | - | - |
| `-f`, `--follow` | Continuously tail log output | No |
| `-n`, `--lines` | Show last N lines | 50 |

Examples:

```bash theme={null}
# View last 100 lines
cow logs -n 100

# Continuously tail logs
cow logs -f
```

## install-browser

Install Playwright and Chromium browser for the [browser tool](/tools/browser).

```bash theme={null}
cow install-browser
```

> [!TIP]
>
> Only needed when using browser tools (web browsing, screenshots, etc.).

## run.sh Compatibility

If Cow CLI is not installed, you can use `run.sh` to manage the service:

| cow command | run.sh equivalent |
| - | - |
| `cow start` | `./run.sh start` |
| `cow stop` | `./run.sh stop` |
| `cow restart` | `./run.sh restart` |
| `cow update` | `./run.sh update` |
| `cow status` | `./run.sh status` |
| `cow logs` | `./run.sh logs` |

> [!NOTE]
>
> The `cow` command is recommended — it provides cleaner syntax and richer features. It is automatically installed via the one-click install script.


# Skill Management
Source: https://docs.cowagent.ai/cli/skill

Skill management commands: use /skill in chat or cow skill in a terminal to list, search, install, uninstall, enable and disable skills from the Skill Hub, GitHub, ClawHub or any URL.

Skill management commands are used to install, query, and manage CowAgent skills. Use `/skill <subcommand>` in chat or `cow skill <subcommand>` in the terminal.

## list

List installed skills and their status.

```text Chat theme={null}
/skill list
```

```bash Terminal theme={null}
cow skill list
```

Example output:

```
📦 Installed skills (3/4)

✅ pptx
   Use this skill any time a .pptx file is involved…
   Source: cowhub

✅ skill-creator
   Create, install, or update skills…
   Source: builtin

⏸️ image-vision (disabled)
   Image understanding and visual analysis
   Source: builtin
```

**Browse the Skill Hub** (view all available skills):

```text Chat theme={null}
/skill list --remote
```

```bash Terminal theme={null}
cow skill list --remote
```

**Options:**

| Option | Description | Default |
| - | - | - |
| `--remote`, `-r` | Browse Skill Hub remote skill list | No |
| `--page` | Page number for remote listing | 1 |

## search

Search for skills on the Skill Hub.

```text Chat theme={null}
/skill search pptx
```

```bash Terminal theme={null}
cow skill search pptx
```

## install

Install skills with a single `install` command from Cow Skill Hub, GitHub, ClawHub, or any URL (zip archives, SKILL.md links) — no manual download or configuration required.

**From Skill Hub (recommended):**

```text Chat theme={null}
/skill install pptx
```

```bash Terminal theme={null}
cow skill install pptx
```

**From GitHub:**

```text Chat theme={null}
# Install all skills in a repo (auto-discovers subdirectories with SKILL.md)
/skill install larksuite/cli

# Specify a subdirectory to install a single skill
/skill install https://github.com/larksuite/cli/tree/main/skills/lark-im

# Use # to specify a subdirectory
/skill install larksuite/cli#skills/lark-minutes
```

```bash Terminal theme={null}
# Install all skills in a repo (auto-discovers subdirectories with SKILL.md)
cow skill install larksuite/cli

# Specify a subdirectory to install a single skill
cow skill install https://github.com/larksuite/cli/tree/main/skills/lark-im

# Use # to specify a subdirectory
cow skill install larksuite/cli#skills/lark-minutes
```

Supports full GitHub URLs and `owner/repo` shorthand. For mono-repos (multiple skills in one repository), omitting the subdirectory auto-discovers and batch-installs all skills; specifying a subdirectory installs only that skill.

**From ClawHub:**

```text Chat theme={null}
/skill install clawhub:baidu-search
```

```bash Terminal theme={null}
cow skill install clawhub:baidu-search
```

**From URL:**

```text Chat theme={null}
# Install from a zip archive (single or batch)
/skill install https://cdn.link-ai.tech/skills/pptx.zip

# Install from a SKILL.md link
/skill install https://example.com/path/to/SKILL.md
```

```bash Terminal theme={null}
# Install from a zip archive (single or batch)
cow skill install https://cdn.link-ai.tech/skills/pptx.zip

# Install from a SKILL.md link
cow skill install https://example.com/path/to/SKILL.md
```

Supports installing from zip / tar.gz archive URLs — automatically extracts and discovers directories containing `SKILL.md`, with support for single or batch install. Also supports installing directly from a `SKILL.md` file URL, automatically parsing the skill name and description.

## uninstall

Uninstall an installed skill.

```text Chat theme={null}
/skill uninstall pptx
```

```bash Terminal theme={null}
cow skill uninstall pptx
```

> [!WARNING]
>
> Uninstalling deletes all files in the skill directory. This action cannot be undone.

## enable / disable

Enable or disable a skill. Disabled skills will not be invoked by the Agent.

```text Chat theme={null}
/skill enable pptx
/skill disable pptx
```

```bash Terminal theme={null}
cow skill enable pptx
cow skill disable pptx
```

## info

View details of an installed skill, including a preview of its `SKILL.md`.

```text Chat theme={null}
/skill info pptx
```

```bash Terminal theme={null}
cow skill info pptx
```

## Skill Sources

Installed skills track their origin, viewable via `/skill list`:

| Source | Description |
| - | - |
| `builtin` | Built-in project skills |
| `cowhub` | Installed from CowAgent Skill Hub |
| `github` | Installed directly from a GitHub URL |
| `clawhub` | Installed from ClawHub |
| `url` | Installed from a SKILL.md URL |
| `local` | Locally created skills |


# Agent Mail
Source: https://docs.cowagent.ai/extensions/agent-mail

Enable the Agent Mail overlay in a Docker deployment so the agent can send, reply to, forward and search email and download attachments through agently-cli, set up in four short steps.

[Agent Mail](https://agent.qq.com) lets the agent handle emails through the `agently-cli` command-line tool: sending, replying, forwarding, searching, reading emails, downloading attachments, and managing the inbox.

It is provided as an optional Docker Compose overlay. The default `docker-compose.yml` deployment is unchanged; the overlay only installs Node.js and `agently-cli` into the container when you choose to enable it.

## 1. Download the overlay

Run the following in the directory that contains `docker-compose.yml`:

```bash theme={null}
mkdir -p agent-mail
curl -o docker-compose.agent-mail.yml https://raw.githubusercontent.com/zhayujie/CowAgent/master/docker/docker-compose.agent-mail.yml
curl -o agent-mail/entrypoint.sh https://raw.githubusercontent.com/zhayujie/CowAgent/master/docker/agent-mail/entrypoint.sh
echo "COMPOSE_FILE=docker-compose.yml:docker-compose.agent-mail.yml" >> .env
```

The `COMPOSE_FILE` entry in `.env` makes every later `docker compose` command in this directory (including `pull` for upgrades) apply the overlay automatically.

## 2. Start the container

```bash theme={null}
sudo docker compose up -d
```

On the first start, Node.js and `agently-cli` are downloaded into `./agent-mail-data/`, so later restarts, container recreation, and image upgrades do not download them again. If the download fails, CowAgent still starts normally without Agent Mail; check the `[agent-mail]` lines in `docker compose logs` and restart to retry.

> [!TIP]
>
> If downloads are slow, change `NODE_MIRROR` and `NPM_CONFIG_REGISTRY` in `docker-compose.agent-mail.yml` to a closer mirror, for example `https://npmmirror.com/mirrors/node` and `https://registry.npmmirror.com`.

## 3. Authorize the mailbox

```bash theme={null}
sudo docker compose exec -u agent chatgpt-on-wechat agently-cli auth login
```

Open the printed link in a browser to complete authorization. The command exits automatically once authorization succeeds.

## 4. Install the skill

The skill teaches the agent how to use `agently-cli`. Send this in chat:

```text theme={null}
/skill install https://agent.qq.com/.well-known/skills/agently-mail/SKILL.md
```

Or run it in the terminal:

```bash theme={null}
sudo docker compose exec -u agent chatgpt-on-wechat cow skill install https://agent.qq.com/.well-known/skills/agently-mail/SKILL.md
```

The skill is installed into the workspace (`./cow/skills`). Once it is installed, just ask the agent to send or check emails.

## Data persistence

| Host directory | Contents |
| - | - |
| `./agent-mail-data/config` | `agently-cli` configuration and login credentials |
| `./agent-mail-data/share` | `agently-cli` local data |
| `./agent-mail-data/npm-global` | Node.js runtime and `agently-cli` |

> [!WARNING]
>
> `./agent-mail-data/config` contains your mailbox credentials. Keep it private and do not commit or share it.


# Chat API
Source: https://docs.cowagent.ai/extensions/chat-api

Turn on the OpenAI-compatible /v1/chat/completions endpoint to call the full CowAgent from any app, SDK or workflow, with tools, skills and memory, plus reasoning, tool calls and token usage.

> CowAgent serves a chat endpoint compatible with the OpenAI Chat Completions protocol, on the same port as the Web Console. Any app, SDK or workflow that speaks the OpenAI protocol can connect to it directly.

Unlike calling a model, the endpoint runs the full Agent: it uses its tools, skills, memory and knowledge base to finish the task, and returns its reasoning, tool calls and token usage along with the answer.

## Turn on the API

The API is off by default. Once it is on, every request must carry the API key.

### From the console

Open "Config → Integrations → Chat API" and turn on the switch. After you confirm, an API key is generated, along with the base URL and ready-to-copy examples (cURL / Python / Node.js).

![Chat API config](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/web-console-chat-api-config.png)

The Chat API card on the Config page

* **Regenerate**: issues a new API key; the old one stops working at once
* **Turn off**: the API stops serving requests. The key is kept and works again once the API is back on

### From the config file

Set these two keys in `config.json`, then restart the service:

```json theme={null}
{
  "external_api_enabled": true,
  "external_api_token": "sk-your-random-key"
}
```

| Key | Description |
| - | - |
| `external_api_enabled` | Whether the API is on. Defaults to `false` |
| `external_api_token` | The API key; use a long random string. It is kept while the API is off |

> [!NOTE]
>
> The API shares the Web Console's address and port. By default it listens on `127.0.0.1`, so only this machine can reach it. To call it from other machines, set `web_host` to `0.0.0.0` as described in [Web Console](/channels/web) and open the port. The API key is independent from the console password `web_password`.

## Quick start

The examples assume the service runs on port `9899` of this machine. They name neither a model nor an Agent, so the default Agent answers on its own model.

**cURL**

```bash theme={null}
curl http://localhost:9899/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Summarize the files in the workspace"}]}'
```

**Python**

```python theme={null}
import requests

resp = requests.post(
    "http://localhost:9899/v1/chat/completions",
    headers={"Authorization": "Bearer your-api-key"},
    json={"messages": [{"role": "user", "content": "Summarize the files in the workspace"}]},
)
print(resp.json()["choices"][0]["message"]["content"])
```

**Node.js**

```javascript theme={null}
const resp = await fetch("http://localhost:9899/v1/chat/completions", {
  method: "POST",
  headers: { "Authorization": "Bearer your-api-key", "Content-Type": "application/json" },
  body: JSON.stringify({
    messages: [{ role: "user", content: "Summarize the files in the workspace" }],
  }),
});
const data = await resp.json();
console.log(data.choices[0].message.content);
```

## Endpoints

### Authentication

Every request carries the API key in its headers:

```
Authorization: Bearer <API key>
```

### Chat

`POST /v1/chat/completions`

| Parameter | Type | Required | Description |
| - | - | - | - |
| `messages` | array | Yes | The conversation. Roles `system`, `developer`, `user` and `assistant` are accepted; `content` is a string or an array of `text` parts |
| `model` | string | No | The model to answer on. Without it the Agent uses its own model. See [List models](#list-models) |
| `agent_id` | string | No | CowAgent extension: the Agent that answers. Without it the default Agent answers. See [Choose an Agent](#choose-an-agent) |
| `stream` | boolean | No | Stream the response. Defaults to `false` |
| `stream_options` | object | No | With `{"include_usage": true}`, the stream ends with the token usage |
| `conversation_id` | string | No | CowAgent extension: the server keeps this conversation's history. See [Conversations](#conversations) |

The Agent uses its own tools and system prompt, so parameters such as `temperature`, `max_tokens` and `tools` are ignored.

### Choose an Agent

With [multiple Agents](/multi-agent/team) configured, `agent_id` chooses which one answers. An Agent's ID is shown under its name on the Agents page, with a button next to it to copy it. `default` always means the default Agent. An Agent that does not exist or is archived returns 404.

```bash theme={null}
curl http://localhost:9899/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "research",
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "Look into recent open-source agent frameworks"}]
  }'
```

`model` applies to that request only; it does not change the model set for the Agent or the conversation.

### List models

`GET /v1/models`

Returns the available models: the chat models of every provider configured under "Config → Models", with the provider in `owned_by`. A request naming a model that is not listed returns 404.

```json theme={null}
{
  "object": "list",
  "data": [
    { "id": "deepseek-chat", "object": "model", "created": 0, "owned_by": "deepseek" },
    { "id": "qwen-max", "object": "model", "created": 0, "owned_by": "dashscope" }
  ]
}
```

## Conversations

The API supports two ways of keeping a conversation:

* **Stateless (default)**: without `conversation_id`, send the whole `messages` list every time, as with any model. The last `user` message is this turn's input, and the `user` / `assistant` messages before it are the context. Nothing is written to CowAgent's conversation history.
* **Stateful**: with `conversation_id`, CowAgent keeps the history, so each request only sends the new message and earlier entries in `messages` are ignored. Requests in the same conversation are handled one at a time, in order.

```json theme={null}
{
  "conversation_id": "order-bot-user-42",
  "messages": [{ "role": "user", "content": "Let's continue where we left off" }]
}
```

> [!NOTE]
>
> `system` messages in the request are ignored: the Agent always keeps its own persona, skills and memory. Either way, the Agent can read and write its workspace and memory files through its tools.

## Responses

### Non-streaming

Besides the standard OpenAI response, `message` carries the reasoning and a record of the tool calls:

```json theme={null}
{
  "id": "chatcmpl-82c19c44...",
  "object": "chat.completion",
  "created": 1791861130,
  "model": "deepseek-chat",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The workspace holds 4 core files and 7 folders...",
        "reasoning_content": "The user wants to know what is in the workspace, so list it first...",
        "tool_trace": [
          {
            "type": "tool_result",
            "id": "call_00_wYInMZ...",
            "name": "ls",
            "arguments": { "path": "." },
            "result": "AGENT.md\nMEMORY.md\n...",
            "status": "success",
            "elapsed": "0.01s"
          }
        ]
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18151,
    "completion_tokens": 180,
    "total_tokens": 18331,
    "prompt_tokens_details": { "cached_tokens": 11392 }
  }
}
```

| Field | Description |
| - | - |
| `model` | The model that answered |
| `message.content` | The final answer |
| `message.reasoning_content` | The reasoning, when deep thinking is on and the model supports it |
| `message.tool_trace` | CowAgent extension: the tool calls, each with its arguments, result, status and duration. Hand-offs to other Agents and generated files are recorded here too, in the format of the [process events](#process-events) below |
| `usage` | Token usage. One Agent turn may call the model several times; this is the sum of all calls. `prompt_tokens_details.cached_tokens` counts input tokens served from cache. Left out when the model reports no usage |

### Streaming

With `"stream": true` the response is a stream of standard `chat.completion.chunk` events over SSE:

* The answer is in `choices[0].delta.content`
* The reasoning is in `choices[0].delta.reasoning_content`
* Process events such as tool calls are in the top-level `cow_event` field, with an empty `delta`
* The last chunk has `finish_reason` set to `stop`. With `stream_options.include_usage`, one more chunk follows with empty `choices` and the `usage`
* The stream ends with `data: [DONE]`

```
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":null}],"cow_event":{"type":"tool_start","id":"call_1","name":"ls","arguments":{"path":"."}}}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"The workspace holds"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":18151,"completion_tokens":180,"total_tokens":18331,"prompt_tokens_details":{"cached_tokens":11392}}}

data: [DONE]
```

Reading the stream:

```python theme={null}
import json
import requests

resp = requests.post(
    "http://localhost:9899/v1/chat/completions",
    headers={"Authorization": "Bearer your-api-key"},
    json={"messages": [{"role": "user", "content": "Summarize the files in the workspace"}], "stream": True},
    stream=True,
)
for line in resp.iter_lines(decode_unicode=True):
    if not line.startswith("data: ") or line == "data: [DONE]":
        continue
    chunk = json.loads(line[len("data: "):])
    event = chunk.get("cow_event")
    if event and event["type"] == "tool_start":
        print(f"\n[tool] {event['name']} {event['arguments']}")
    for choice in chunk["choices"]:
        print(choice["delta"].get("content") or "", end="", flush=True)
```

### Process events

`cow_event.type` takes these values:

| Type | Description | Main fields |
| - | - | - |
| `tool_start` | A tool call starts | `id`, `name`, `arguments` |
| `tool_result` | A tool call finishes | `id`, `name`, `arguments`, `result`, `status`, `elapsed` |
| `subagent_step` | A step taken by a sub-agent | `card_id`, `step_id`, `phase`, `tool`, `status` |
| `peer_start` | The task is handed to another Agent; the content that follows is its answer | `card_id`, `agent_id`, `agent_name` |
| `peer_end` | That Agent is done | `card_id`, `agent_id`, `status` |
| `artifact` | A file the Agent produced | `artifact` |
| `reasoning` | Reasoning, the same text as `delta.reasoning_content` | `delta` |
| `error` | The run failed | `message` |

## Errors

Errors follow the OpenAI format:

```json theme={null}
{ "error": { "message": "Invalid authentication credentials.", "type": "api_error", "code": "invalid_api_key" } }
```

| Status | `code` | Meaning |
| - | - | - |
| 400 | `invalid_request` / `invalid_json` | Malformed request |
| 401 | `invalid_api_key` | Wrong API key |
| 404 | `model_not_found` | `model` is not in the [model list](#list-models) |
| 404 | `agent_not_found` | The Agent `agent_id` names does not exist or is archived |
| 503 | `api_disabled` | The API is off |
| 500 | `internal_error` / `timeout` | The Agent failed or timed out |

A streaming request waits up to 30 seconds for the Agent to produce the first event. A failure or a timeout before the first event returns one of the JSON errors above, and a timeout cancels that request. Once the stream has started its HTTP status can no longer change, so a later failure arrives as a `cow_event.type=error` chunk, followed by a terminal chunk with `finish_reason=error` and then `data: [DONE]`.

## Use it from other apps

Any client or platform that accepts a custom OpenAI endpoint can connect. Choose the "OpenAI" or "OpenAI compatible" provider and fill in:

* **Base URL**: `http://<server address>:9899/v1` (some apps only want the address and port, and add `/v1` themselves)
* **API key**: the key generated in the console
* **Model**: pick one from the [model list](#list-models)

The default Agent answers requests from these apps.

The API allows cross-origin requests (CORS), so browser apps can call it directly.

> [!NOTE]
>
> Only text input is supported for now; images and other multimodal content are not. Caller-supplied `tools` for function calling are not supported either: the Agent finishes the task with its own tools.


# Custom Menu
Source: https://docs.cowagent.ai/extensions/custom-menu

Customize the sidebar in the web console and desktop app: reorder and group items, hide pages you rarely use, and pin agent-generated pages, documents or any URL to open them in one click.

The sidebar menu can be arranged the way you work: reorder and group it, hide the pages you rarely use, and add web pages and documents the Agent created, or any URL, so they open in one click like a built-in page. The Web Console and the desktop client share one menu.

![Custom menu](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/web-console-custom-menu.png)

An ops dashboard maintained by the Agent, pinned to a Workbench group and opened right inside the console

## Edit the menu

### Open the editor

There are three ways in:

* Hover over a group title in the sidebar and click the edit icon that appears on its right
* Click the version number at the bottom left of the sidebar (Web Console) or the "More" button (desktop client), then choose "Customize menu"
* While previewing a web page or Markdown document on the Artifacts page, click "Add to menu"

![Menu editor](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/web-console-custom-menu-config.png)

The menu editor: drag to reorder and regroup, and add artifacts and web links

Changes take effect once you click Save in the editor.

### Order and groups

* Hold the drag handle on the left of an entry to move it, within its group or into another one
* Click "Add group" to create a group; its title can be edited in place
* Before removing a group, move the built-in pages it holds to another group

### Built-in pages

Built-in pages such as Chat, Agents, Config and Capabilities can be:

* **Renamed and given another icon**: an empty name falls back to the default one
* **Hidden**: click the eye icon to hide or show the page. Chat and Config cannot be hidden, so the settings are always within reach
* **Added back**: a removed built-in page can be restored from "Add → Built-in page"

The Artifacts page starts hidden; show it in the editor when you need it.

### Restore default

Click "Restore default" in the editor to go back to the built-in menu. The artifacts and links you added are removed.

## Add menu entries

Besides built-in pages, the menu can hold artifacts and web links, each with its own name and icon.

### Artifacts

Use "Add → Artifact (HTML / Markdown)" to search the web pages and Markdown documents the Agent created and put one in the menu. Clicking the entry opens it right inside the console, always at its latest version, which suits reports, dashboards and notes the Agent keeps up to date.

If the file is deleted, the entry says so, and you can remove it in the editor.

### Web links

Use "Add → Web link", enter a name and a URL starting with `http://` or `https://`, and choose how it opens:

* **Embed**: inside the console, which suits internal tools and dashboards
* **New tab**: in a new browser tab

> [!TIP]
>
> Some sites refuse to be embedded in other pages and show up blank. Switch the entry to "New tab" instead. An embedded page also has an "Open in new tab" button at its top right.

## Menu file

### Location

The menu is saved in `system/menu.json` under the default Agent's workspace (`~/cow/system/menu.json` for a source deployment), and both the Web Console and the desktop client read it. A page one client does not have is skipped there and kept in the menu for the other.

### Format

The file can also be edited by hand in the format below. A file that cannot be parsed is ignored and the built-in menu is used.

```json theme={null}
{
  "version": 1,
  "groups": [
    {
      "id": "chat",
      "title": "",
      "items": [
        { "id": "chat", "type": "builtin", "view": "chat", "title": "", "icon": "", "hidden": false },
        { "id": "m_report", "type": "artifact", "title": "Weekly report", "icon": "chart", "path": "/Users/me/cow/websites/report.html" },
        { "id": "m_board", "type": "url", "title": "Dashboard", "icon": "gauge", "url": "https://example.com/board", "open": "embed" }
      ]
    }
  ]
}
```

| Type | Description | Fields |
| - | - | - |
| `builtin` | A built-in page | `view`: the page name; `hidden`: whether it is hidden |
| `artifact` | An artifact | `path`: absolute path of the file, HTML or Markdown only |
| `url` | A web link | `url`: the address; `open`: `embed` or `tab` |


# Guest Pages
Source: https://docs.cowagent.ai/extensions/guest-share

Share an Agent as a standalone chat page, or embed it in your site as a chat window. Visitors just open the link, no sign-in needed.

> Share an Agent as a standalone chat page, or embed it in your own site, for product questions, docs Q\&A, customer support and the like. Visitors open the link and start chatting, no sign-in needed.

The Agent on a guest page is kept apart from the one you use every day. It only gets the tools, skills and references you open up for that page, and never sees your memory, chats or workspace.

## Turn it on

Go to **Config → Integrations → Guest pages** and turn on the switch.

* **Set a console password first.** Guest pages share the console's port, so their links stay offline until the console has a password, then go live on their own.
* **The server must be reachable from outside.** See [Web Console](/channels/web) for deployment. If you serve it through a domain or a public IP, enter that address under **Public address** on the same page; share links and embed code will use it.

## Create a page

Click **New guest page**, fill it in and save. The link is created right away.

### Basics

Name, model, welcome message and suggested questions. Without a model picked, the page uses the global default. Suggested questions appear on the welcome screen for visitors to tap.

### Appearance

Icon and theme color, used on the page and on the embedded chat button.

### Access

* **Password**: visitors must enter it before chatting.
* **Questions per visitor a day**: visitors are told apart by browser. Defaults to 100; 0 means no limit.
* **Expires on**: the link stops working after this date. Leave empty to keep it open.

### More settings

* **Tools**: reading and writing files, searching files, sending files, web search, fetching pages, vision and the current time. New pages get all of them. Guest pages cannot run commands.
* **Skills**: pick from your installed skills. Skills that rely on commands or scripts can't work on a guest page and are left out of the list.
* **References**: folders the Agent may look things up in, read-only. Pick your knowledge base or one of its categories, or enter any other folder. Each one can carry a short note, such as "product docs, for feature and pricing questions", so the Agent knows when to look there.
* **Guest rules**: written into the Agent's system prompt. Use them to set who it is, what it helps with and how it replies.
* **Footer**: the text and link at the bottom of the page. Edit or clear them.

## Share and embed

Copy the link from the page list to share it. Links look like `https://<public address>/share/<token>`.

To embed the page in your site, click **Embed** on the page. Add your site (e.g. `https://example.com`) under **Sites allowed to embed**, then put the code in your page's `<body>`. A chat button appears in the bottom-right corner, and the dialog shows a live preview.

```html theme={null}
<script src="https://agent.example.com/assets/guest/embed.js"
  data-share-url="https://agent.example.com/share/<token>"
  data-title="Ask us"
  defer></script>
```

Add `data-color` to change the button color, or `data-position="left"` to move it to the bottom-left corner.

## Manage pages

* **Visitor logs**: read each visitor's conversations.
* **Reset link**: issues a new link; the old link and embed code stop working at once.
* **Sign out visitors**: everyone has to come in again (and re-enter the password, if the page has one). Earlier chats are no longer shown to them.
* **Pause / Resume**: a paused page's link stops working for now, and replies in progress are stopped.
* **Delete**: removes the page, its link and all visitor logs. This cannot be undone.

## Security

* The guest Agent can only reach the current conversation's scratch folder and the references and skills you picked. It never sees real paths and cannot step outside these folders.
* It cannot run commands. Network tools only reach the public internet; local and private network addresses are blocked.
* Page settings live in `~/cow/guests/<page id>/`, so you can also ask your own Agent to change them. Changes that widen access, such as adding tools or references, turning on the network or removing the password, only take effect after you click **Confirm** in the console.


# Desktop Client
Source: https://docs.cowagent.ai/guide/desktop

Download and install the CowAgent desktop app for macOS (Apple Silicon and Intel) and Windows. It bundles the agent runtime, so no Python or dependencies are needed to run your AI assistant locally.

CowAgent ships a ready-to-use desktop client with the Agent runtime bundled in — **no need to install Python or dependencies manually**. Just download, install, and run your local super AI assistant.

<video />

It drives your browser, terminal, and file system directly, with long-term memory, a personal knowledge base, and self-evolution — all running locally.

## Download & Install

> **[Go to the download page](https://cowagent.ai/download/)**
>
> Download the macOS / Windows installer

**macOS**

1. Open the [download page](https://cowagent.ai/download/) and pick the build for your chip:
   * Apple Silicon (M1/M2/M3/M4): download the `arm64` build
   * Intel: download the `x64` build
2. Open the downloaded `.dmg` and drag CowAgent into your Applications folder.
3. Launch CowAgent from Launchpad or Applications.

**Windows**

1. Open the [download page](https://cowagent.ai/download/) and download the Windows installer (`.exe`).
2. Run the installer and follow the prompts (you can choose the install directory).
3. Launch CowAgent from the desktop or Start menu.

## Auto Update

The desktop client has built-in auto-update. When a new version is available it is detected automatically; you can also manually "Check for updates" from the menu in the bottom-left corner and upgrade with one click.

## Desktop vs. Command-line Deployment

* **Desktop client**: best for personal use on your own computer — works out of the box, GUI-based, auto-updating.
* **Command-line deployment**: best for developers or long-running servers with more customization. See [Quick Start](/guide/quick-start).

## Access from a Browser

Once the desktop client is running, it listens on port `9876` locally, and its backend is exactly the same Web console. So while the app is open you can also just point your browser at `http://localhost:9876` for the same full experience as the client UI.

If that port is unavailable (for example reserved by Hyper-V/WSL2 on Windows), the client automatically falls back to another one and still starts normally. The actual port is shown on the `Local access` line in `run.log`, and you can pin one by setting `web_port` in `config.json`.

## Local Data Storage

All data of the desktop client is stored on your machine:

* **Config directory**: `~/.cow` in your home folder, holding `config.json` (model keys, channels, etc.) along with logs, cache and other runtime data.
* **Workspace**: `~/cow` by default, holding chat history, knowledge base, memory, skills, scheduled tasks and other files produced by the Agent.

Uninstalling the client does not delete these two directories, so your data is preserved across reinstalls. To fully clean up or migrate to another device, just back up or remove the corresponding folders manually.


# Custom Themes
Source: https://docs.cowagent.ai/guide/desktop-themes

Switch built-in themes in the CowAgent desktop app, import theme packages, or let the Agent design your own colors and wallpaper.

The desktop app supports themes (skins). A theme only describes colors, corner radius, fonts and a background wallpaper, never the UI layout, so themes keep working across app updates.

## Switch Themes

Open the "More" menu at the bottom-left, hover "Theme" to show the theme list, and click one to apply it. Themes are independent of light / dark mode, and every theme covers both.

Built-in color themes:

* **Meadow** (default): fresh green
* **Ocean**: ocean blue
* **Clay**: warm terracotta
* **Sakura**: cherry-blossom pink
* **Lavender**: lavender purple

## Import Themes

Click "Custom theme…" at the bottom of the theme list to open the custom theme dialog, then drag a theme `.zip` or theme folder onto it. You can also click it to browse instead (on Windows, pick the `theme.json` inside a folder to import that folder). The imported theme is applied right away.

On import the app checks that:

* `theme.json` sits at the root of the package, or inside its single top-level folder
* Only `theme.json` and images (`jpg` / `png` / `webp` / `gif` / `svg`) are copied; other files are ignored
* Each file is at most 16MB and the whole theme at most 64MB
* An existing theme with the same ID is only replaced after you confirm; an ID taken by a built-in theme is renamed automatically

Imported themes live in `~/.cow/themes/`, one folder per theme. Click "Open themes folder" at the bottom of that dialog to manage them: delete a folder to remove a theme, or copy a theme folder in directly; it shows up the next time you open the theme list.

## Theme Structure

```
my-theme/
├── theme.json        # required
├── wallpaper.jpg     # optional background wallpaper
└── logo.png          # optional icon in the middle of the new-chat page
```

Example `theme.json`:

```json theme={null}
{
  "specVersion": 1,
  "id": "midnight-neon",
  "name": "Midnight Neon",
  "preview": { "accent": "#8b5cf6", "bg": "#f7f6fb", "surface": "#ffffff" },
  "shape": { "radiusCard": "14px", "radiusBtn": "10px" },
  "wallpaper": { "image": "wallpaper.jpg", "overlayOpacity": 0.25, "glass": true },
  "light": {
    "colors": {
      "accent": "#7c4dff",
      "accentSoft": "rgba(124, 77, 255, 0.10)",
      "bgBase": "#f7f6fb",
      "textPrimary": "#1f1b2e"
    }
  },
  "dark": {
    "colors": {
      "accent": "#8b5cf6",
      "accentSoft": "rgba(139, 92, 246, 0.18)",
      "bgBase": "#0d0b14",
      "bgSurface": "#151220",
      "textPrimary": "#f2effa"
    }
  }
}
```

| Field | Description |
| - | - |
| `id` | Unique theme ID; defaults to the folder name |
| `name` | Name shown in the theme list |
| `specVersion` | Theme spec version, currently `1` |
| `preview` | Swatch in the theme list: `accent` / `bg` / `surface`; derived from the colors when omitted |
| `shape` | Appearance-independent shape: `radiusCard`, `radiusBtn`, `radiusSm`, `fontSans`, `fontMono` |
| `wallpaper` | Background wallpaper shared by light and dark |
| `light` / `dark` | `colors` for that appearance, plus an optional `wallpaper` of its own |
| `identity.logo` | Icon in the middle of the new-chat page; a square image works best. A `logo.png` in the theme folder is used automatically, so set this only for a different file name |

### Colors

Values accept any CSS color (e.g. `#7c4dff`, `rgba(...)`). Keys you leave out fall back to the default theme, and unknown keys are ignored. If the colors make text hard to tell apart from its background, the app falls back to the default theme.

| Key | Used for |
| - | - |
| `accent` / `accentHover` / `accentActive` | Theme color and its hover / pressed states (buttons, selection, links) |
| `accentSoft` | Light accent fill (selected rows, tags) |
| `accentContrast` | Text drawn on the accent color |
| `bubbleUserBg` / `bubbleUserText` | User message bubble background and text |
| `bgBase` | App background |
| `bgSurface` / `bgSurface2` | Panels and cards, plus nested layers and hover fills |
| `bgElevated` | Menus and dialogs |
| `bgInset` / `bgInset2` | Inputs, plus nested fills such as code blocks |
| `textPrimary` / `textSecondary` / `textTertiary` / `textDisabled` | Four levels of text |
| `borderDefault` / `borderStrong` / `borderSubtle` | Three levels of borders |

### Wallpaper

One wallpaper is enough: set it at the top level and both light and dark use it. To give each appearance its own image, set `wallpaper` under `light` / `dark`; those take precedence. If only one appearance sets a wallpaper, the other reuses it, and a `wallpaper.jpg` in the theme folder is used automatically when none is set anywhere.

For different wallpapers per appearance, drop the top-level `wallpaper` and set one under each of `light` / `dark`:

```json theme={null}
{
  "light": {
    "colors": { "...": "..." },
    "wallpaper": { "image": "wallpaper-light.jpg", "glass": true }
  },
  "dark": {
    "colors": { "...": "..." },
    "wallpaper": { "image": "wallpaper-dark.jpg", "glass": true }
  }
}
```

| Key | Description |
| - | - |
| `image` | Image path inside the theme folder |
| `focusX` / `focusY` | Focal point (0–1) kept in view as the window resizes; default `0.5` |
| `overlayOpacity` | Scrim strength over the image (0–1) for readable text; defaults to `0.4` light, `0.3` dark. Tune it if the wallpaper looks too dark or too busy |
| `glass` | When `true`, panels turn translucent frosted glass so the wallpaper shows through the whole UI |

## Let the Agent Create a Theme

The Agent in the desktop app can build a theme for you. It writes the theme to `~/.cow/themes/`, and if image generation is configured it can generate the wallpaper and logo too.

The quickest way is the "Start" button next to "Let the Agent create one" in the custom theme dialog: it opens a new chat with the prompt filled in, so you only add the style you want at the end and send it. You can also attach reference images (a character or scene you like), and the Agent will base the wallpaper and logo on them.

You can also send the prompt below in any chat, with the style you want on the last line. To fine-tune afterwards, such as "make the wallpaper brighter" or "switch the accent to teal", just tell the Agent; reopen the theme list to see the change.

```text theme={null}
Create a theme for this desktop app.

Requirements:
1. Create theme.json in ~/.cow/themes/<theme-id>/ with a lowercase, hyphenated id, shaped like {"specVersion": 1, "id", "name", "light": {"colors": {...}}, "dark": {"colors": {...}}}.
2. Fill these keys in both light and dark colors: accent, accentHover, accentActive, accentSoft, accentContrast, bubbleUserBg, bubbleUserText, bgBase, bgSurface, bgSurface2, bgElevated, bgInset, bgInset2, textPrimary, textSecondary, textTertiary, textDisabled, borderDefault, borderStrong, borderSubtle. Keep backgrounds low-saturation, text easy to read, and white text on the accent legible.
3. If you can generate images, use an image generation skill to make two images without text in the same folder:
   - wallpaper.jpg: a 16:9 wallpaper with the subject toward the right, moderately bright rather than dark; add "wallpaper": {"image": "wallpaper.jpg", "overlayOpacity": 0.25, "glass": true} at the top level of theme.json, shared by both appearances. If I ask for different wallpapers per appearance, generate wallpaper-light.jpg and wallpaper-dark.jpg instead, skip the top-level wallpaper, and add a wallpaper to light and to dark pointing to each image
   - logo.png: square, used as the icon in the middle of the new-chat page (not the app icon); just put it in the folder, no need to add it to theme.json
4. If I attached reference images, pass them to the image generation as input images so the characters and art style match them, and take the colors from them too.
5. Check that theme.json is valid JSON, then tell me the theme name.

The style I want: <e.g. "cyberpunk city at night, neon purple and cyan">
```

Then open the theme list at the bottom-left to find and apply the new theme. To share it, zip the theme folder and send it; others can drop it onto the "Custom theme" dialog.


# Manual Install
Source: https://docs.cowagent.ai/guide/manual-install

Deploy CowAgent manually: clone the source, install core and optional dependencies, install the Cow CLI, edit config.json and start the service, or deploy to a server with Docker Compose.

## Source Code Deployment

### 1. Clone the project

```bash theme={null}
git clone https://github.com/zhayujie/CowAgent
cd CowAgent/
```

> [!TIP]
>
> For network issues, use the mirror: [https://gitee.com/zhayujie/CowAgent](https://gitee.com/zhayujie/CowAgent)

### 2. Install dependencies

Core dependencies (required):

```bash theme={null}
pip3 install -r requirements.txt
```

Optional dependencies (recommended):

```bash theme={null}
pip3 install -r requirements-optional.txt
```

### 3. Install Cow CLI

Install the command-line tool for managing services and skills:

```bash theme={null}
pip3 install -e .
```

Then use the `cow` command:

```bash theme={null}
cow help
```

> [!NOTE]
>
> This step is recommended. After installation you can use `cow start`, `cow stop`, `cow update` to manage the service, and `cow skill` to manage skills. Without the CLI, you can use `./run.sh` or `python3 app.py` to run.

### 4. Configure

Copy the config template and edit:

```bash theme={null}
cp config-template.json config.json
```

Fill in model API keys, channel type, and other settings in `config.json`. See the [model docs](/models/index) for details.

### 5. Run

**Using Cow CLI (recommended):**

```bash theme={null}
cow start
```

**Or run locally in foreground:**

```bash theme={null}
python3 app.py
```

By default, the Web console starts. Access `http://localhost:9899` to chat.

**Background run on server (without CLI):**

```bash theme={null}
nohup python3 app.py & tail -f nohup.out
```

> [!TIP]
>
> **Deploying on a server?** By default `web_host` only listens on `127.0.0.1` (local access). Set `web_host` to `0.0.0.0` in `config.json` to make the console reachable from outside, and set `web_password` to protect it. Don't forget to open port `9899` in your firewall or security group — ideally restricted to specific IPs.

## Docker Deployment

Docker deployment does not require cloning source code or installing dependencies. For Agent mode, source deployment is recommended for broader system access.

> [!NOTE]
>
> Requires [Docker](https://docs.docker.com/engine/install/) and docker-compose.

**1. Download config**

```bash theme={null}
curl -O https://cdn.link-ai.tech/code/cow/docker-compose.yml
```

Edit `docker-compose.yml` with your configuration.

**2. Start container**

```bash theme={null}
sudo docker compose up -d
```

**3. View logs**

```bash theme={null}
sudo docker logs -f chatgpt-on-wechat
```

> [!NOTE]
>
> **Data persistence**: `docker-compose.yml` mounts two host directories by default, so your data survives container restarts and `docker compose pull` image upgrades:
>
> * `./cow` → `/home/agent/cow` in the container: the workspace, holding conversation-installed skills, memory, knowledge base, `mcp.json`, and conversation artifacts.
> * `./cow-data` → `/home/agent/.cow` in the container: the data directory pointed to by `COW_DATA_DIR`, holding the `config.json` saved from the web console, run logs, and channel credentials.
>
> Both directories are created next to `docker-compose.yml` by default — don't delete them.

> [!TIP]
>
> **Running in Docker?** Set `WEB_HOST` to `0.0.0.0` in `docker-compose.yml` so the console is reachable from outside the container, and set `WEB_PASSWORD` to protect it. Make sure port `9899` is mapped to the host and open in your firewall or security group.

## Core Configuration

```json theme={null}
{
  "channel_type": "web",
  "model": "deepseek-flash",
  "deepseek_api_key": "",
  "agent": true,
  "agent_workspace": "~/cow",
  "agent_max_context_tokens": 200000,
  "agent_max_context_turns": 30,
  "agent_max_steps": 100,
  "cow_lang": "auto"
}
```

| Parameter | Description | Default |
| - | - | - |
| `channel_type` | Channel type | `web` |
| `model` | Model name | `deepseek-flash` |
| `agent` | Enable Agent mode | `true` |
| `agent_workspace` | Agent workspace path | `~/cow` |
| `agent_max_context_tokens` | Max context tokens | `200000` |
| `agent_max_context_turns` | Max context turns | `30` |
| `agent_max_steps` | Max decision steps per task | `100` |
| `cow_lang` | Language for the UI, command text and system prompts; `auto` to detect, or set `zh` / `en` | `auto` |

> [!TIP]
>
> Full configuration options are in the project [`config.py`](https://github.com/zhayujie/CowAgent/blob/master/config.py).


# One-click Install
Source: https://docs.cowagent.ai/guide/quick-start

Install CowAgent with one command on Linux, macOS or Windows. The script checks Python, installs dependencies and the Cow CLI, walks you through model and channel setup, and starts the web console.

The project provides scripts for one-click install, configuration, startup, and management. Script-based deployment is recommended for quick setup.

Supports Linux, macOS, and Windows. Requires Python 3.7-3.13 (3.9 recommended).

## Install Command

**Linux / macOS**

```bash theme={null}
bash <(curl -fsSL https://cdn.link-ai.tech/code/cow/run.sh)
```

**Windows (PowerShell)**

```powershell theme={null}
irm https://cdn.link-ai.tech/code/cow/run.ps1 | iex
```

The script automatically performs these steps:

1. Check Python environment (requires Python 3.7+)
2. Install required tools (git, curl, etc.)
3. Clone project to `~/CowAgent`
4. Install Python dependencies and Cow CLI
5. Guided configuration for AI model and channel
6. Start service

By default, the Web console starts after installation. Access `http://localhost:9899` to begin chatting.

> [!NOTE]
>
> **Deploying on a server?** By default `web_host` only listens on `127.0.0.1` (local access only). Set `web_host` to `0.0.0.0` in `config.json` to make the console reachable from outside, and set `web_password` to protect it. Don't forget to open port `9899` in your firewall or security group — ideally restricted to specific IPs.

## Management Commands

After installation, use the `cow` command to manage the service:

| Command | Description |
| - | - |
| `cow start` | Start service |
| `cow stop` | Stop service |
| `cow restart` | Restart service |
| `cow status` | Check run status |
| `cow logs` | View real-time logs |
| `cow update` | Update code and restart |
| `cow install-browser` | Install browser tool dependencies |

See the [Commands documentation](/cli/index) for more details.

> [!NOTE]
>
> If the `cow` command is not available, you can use `./run.sh <command>` (Linux/macOS) or `.\scripts\run.ps1 <command>` (Windows) as a fallback. Both are functionally equivalent.


# Upgrade
Source: https://docs.cowagent.ai/guide/upgrade

Upgrade CowAgent to the latest version: run cow update to pull code, update dependencies, reinstall the CLI and restart, or check for updates and upgrade in one click from the web console.

## Recommended: One-line upgrade

Use `cow update` to pull the latest code and restart the service in one step:

```bash theme={null}
cow update
```

The command runs the following automatically:

1. Pull the latest code (`git pull`)
2. Stop the running service
3. Update Python dependencies
4. Reinstall the CLI
5. Start the service

> [!NOTE]
>
> If the Cow CLI is not installed, `./run.sh update` performs the same operations.

## Web console one-click update

Source installs can also upgrade from the Web console without opening a terminal.

1. Click the version string in the left sidebar footer to open the pop-up menu. Opening it does **not** contact GitHub.
2. Click **Check for update** to fetch version info — the only network request. If a newer version exists, the same row turns into **Update now** with a small red dot.
3. Click **Update now**. The console reuses the same path as `cow update` (`git pull`, dependency install, CLI reinstall) and then restarts the service. The **Release notes** entry opens the GitHub releases page for the full changelog.

The update only touches the git checkout. User data lives outside the repo (`agent_workspace`, default `~/cow`) and `config.json` is git-ignored, so `git pull` never overwrites them — no backup is taken. The updater records the current git commit; if the new code fails to import, it resets the checkout to that commit and leaves the running process untouched.

After a successful update the console reconnects on its own and shows the new version.

> [!NOTE]
>
> Docker images and the packaged desktop app cannot use this button. Docker stays on `docker compose pull`; the desktop client keeps its built-in updater. On Windows, run `cow update` in a terminal — the Web console cannot restart that process from inside itself.

### Rollback

If a successful update misbehaves, reset to the previous commit:

```bash theme={null}
cow stop
git reset --hard <previous-commit>   # recorded in tmp/web-update-status.json
cow start
```

## Manual upgrade

Run the following inside the project root:

```bash theme={null}
git pull
pip3 install -r requirements.txt
pip3 install -e .
```

Then restart the service:

```bash theme={null}
# Using Cow CLI (recommended)
cow restart

# Or using run.sh
./run.sh restart

# Or restart manually with nohup
kill $(ps -ef | grep app.py | grep -v grep | awk '{print $2}')
nohup python3 app.py & tail -f nohup.out
```

## Docker upgrade

Run the following in the directory containing `docker-compose.yml`:

```bash theme={null}
sudo docker compose pull
sudo docker compose up -d
```

> [!TIP]
>
> Back up `config.json` before upgrading. Settings and channel logins live in the mounted `./cow-data` directory and the workspace in `./cow`, so recreating the container keeps them. Environment variables given a value in `docker-compose.yml` override the same settings from the console on every start.

## Desktop client upgrade

The [desktop client](/guide/desktop) has built-in auto-update: it checks for new versions automatically and prompts you, so you can download and restart to upgrade in one click.

You can also grab the latest version anytime from the [download page](https://cowagent.ai/download/).


# Architecture
Source: https://docs.cowagent.ai/intro/architecture

How CowAgent is built: the channel, agent core, model, tool, skill, memory and knowledge modules, and the agent loop from receiving a message to planning, calling tools, updating memory and replying.

CowAgent is an out-of-the-box super AI assistant and a complete Agent harness framework, featuring complex task planning, long-term memory, skill extensibility, self-evolution, and multi-agent collaboration.

## System Architecture

CowAgent's architecture consists of the following core modules:

![CowAgent Architecture](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/architecture/en/architecture.jpg)

| Module | Description |
| - | - |
| **Plan** | Understands user intent, decomposes complex tasks into multi-step plans, and iteratively invokes tools until the goal is achieved |
| **Memory** | Automatically persists important information as core memory and daily memory, with hybrid keyword and vector retrieval for cross-session context continuity |
| **Knowledge** | Organizes structured knowledge by topic. The Agent autonomously distills valuable information into Markdown pages, maintaining indexes and cross-references to build a growing knowledge network |
| **Evolution** | Reviews a conversation in an isolated environment after it goes idle, improving skills, following up on unfinished tasks, and backfilling memory and knowledge so the Agent keeps growing through everyday use |
| **Multi-agent** | Multiple Agents form a team, each with its own responsibilities, model, and workspace. Supports group-chat collaboration, task delegation, and sub-Agents; a channel can bind a single Agent or the whole team to serve externally |
| **Tools** | Core capability for Agent to access OS resources. 10+ built-in tools including file read/write, terminal, browser, scheduler, memory search, web search, and more |
| **Skills** | Loads and manages Skills. Supports one-click installation from Skill Hub, GitHub, and more, or custom skill creation through conversation |
| **Models** | Model layer with unified access to OpenAI, Claude, Gemini, DeepSeek, MiniMax, GLM, Qwen, and other mainstream LLMs |
| **Channels** | Message channel layer for receiving and sending messages. Supports Web console, WeChat, Feishu, DingTalk, WeCom, WeChat Official Account, and more with a unified protocol |
| **CLI** | Command-line system providing terminal commands (`cow`) and chat commands (`/`) for process management, skill installation, configuration, knowledge base management, and more |

## Agent Mode Workflow

When Agent mode is enabled, CowAgent runs as an autonomous agent with the following workflow:

1. **Receive Message** — Receive user input through channels
2. **Understand Intent** — Analyze task requirements and context
3. **Plan Task** — Break complex tasks into multiple steps
4. **Invoke Tools** — Select and execute appropriate tools for each step
5. **Update Memory & Knowledge** — Store important information in long-term memory and organize structured knowledge into the knowledge base
6. **Return Result** — Send execution results back to the user

## Workspace

### System Workspace

The Agent's system workspace is located at `~/cow` by default and stores system prompts, memory files, and skill files:

```
~/cow/
├── SYSTEM.md          # Agent system prompt
├── USER.md            # User profile
├── MEMORY.md          # Core memory
├── memory/            # Long-term memory storage
│   └── YYYY-MM-DD.md  # Daily memory
├── knowledge/         # Personal knowledge base
│   ├── index.md       # Knowledge index
│   └── <category>/    # Topic-based pages
├── skills/            # Custom skills
│   ├── skill-1/
│   └── skill-2/
└── agents/            # Multi-agent team
    ├── team.json      # Team roster & channel bindings
    └── <agent-id>/    # Non-default agent's own workspace
```

Secret keys are stored separately in `~/.cow` directory for security:

```
~/.cow/
└── .env               # Secret keys for skills
```

### Project Workspace

Besides the default workspace, each session can be bound to its own **project directory**. The Agent's file reads/writes and command execution happen inside that directory, giving you multi-project isolation; memory, skills, and the like still live in the default workspace. When more than one project is in use, the Web/desktop history list automatically groups sessions by project.

### Multi-Agent Workspace

Once you build an [Agent team](/multi-agent/team), each Agent has a complete workspace of its own. The default Agent uses the instance root `~/cow`, while every other member lives under `~/cow/agents/<agent-id>/`. This splits storage into three categories — system-shared, per-member isolated, and optionally shared:

* **System-shared**: the secrets file (`~/.cow/.env`) and the team config (`~/cow/agents/team.json`) are shared across the whole instance.
* **Per-member isolated**: each Agent's core files (`SYSTEM.md`, `USER.md`, `AGENT.md`, `RULE.md`), memory (`MEMORY.md`, `memory/`), and output files live inside its own workspace and are not visible to other members.
* **Optionally shared**: skills and the knowledge base can either be shared with the team or dedicated to a specific member, and the two modes can be switched at any time.

> A sub-Agent is a temporary execution unit spun up by the lead Agent; it shares the lead Agent's workspace and has no memory of its own. A team member is a persistent, full Agent with a completely independent workspace and memory. See [Sub-Agents](/multi-agent/subagent) for details.

### Per-Session Model & Permission

Workspace, model, and permission can all be **set per session**, falling back to the global default when unset:

* **Model**: different sessions can switch to different models, making it easy to pick the right one per task.
* **Permission**: controls what the Agent is allowed to do, in three levels — **read-only**, **workspace-write**, and **full-access**. You can set a global default (`agent_permission_mode`) in the config; new sessions inherit it and can be adjusted individually as needed. Permissions reduce the risk of accidental changes; for strong isolation, run inside a container.

## Core Configuration

Configure Agent mode parameters in `config.json`:

```json theme={null}
{
  "agent": true,
  "agent_workspace": "~/cow",
  "agent_max_context_tokens": 200000,
  "agent_max_context_turns": 30,
  "agent_max_steps": 100,
  "agent_permission_mode": "full-access",
  "enable_thinking": false,
  "cow_lang": "auto"
}
```

| Parameter | Description | Default |
| - | - | - |
| `agent` | Enable Agent mode | `true` |
| `agent_workspace` | Workspace path | `~/cow` |
| `agent_max_context_tokens` | Max context tokens | `200000` |
| `agent_max_context_turns` | Max context turns | `30` |
| `agent_max_steps` | Max decision steps per task | `100` |
| `agent_permission_mode` | Global default permission inherited by new sessions: `read-only` / `workspace-write` / `full-access` | `full-access` |
| `enable_thinking` | Enable deep-thinking mode | `false` |
| `knowledge` | Enable personal knowledge base | `true` |
| `self_evolution_enabled` | Enable Self-Evolution (on by default for new installs) | `false` |
| `cow_lang` | Language for the UI, command text and system prompts; `auto` to detect, or set `zh` / `en` | `auto` |


# Features
Source: https://docs.cowagent.ai/intro/features

A tour of CowAgent's core features: layered long-term memory with Deep Dream, self-evolution, a personal knowledge base and graph, task planning and tools, scheduling, skills, CLI and browser control.

## 1. Long-term Memory

The memory system enables the Agent to remember important information over time, using a three-tier memory flow: conversation context (short-term) → daily memory (mid-term) → MEMORY.md (long-term), forming a complete memory lifecycle.

On first launch, the Agent proactively asks the user for key information and records it in the workspace (default `~/cow`) — including agent settings, user identity, and memory files.

In subsequent long-term conversations, the Agent intelligently stores or retrieves memory as needed, continuously updating its own settings, user preferences, and memory files. **Deep Dream** distillation runs daily, consolidating scattered daily memories into refined long-term memory and generating a narrative-style dream diary.

![](https://cdn.link-ai.tech/doc/20260203000455.png)

Building on this, **Self-Evolution** lets the Agent keep growing through everyday use: after a conversation goes idle, it reviews it automatically to improve skills, follow up on unfinished tasks, and backfill memory and knowledge. It speaks up only when it actually made a change, and every change can be undone. Enabled by default for new installs.

![](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/web-console-evolution-demo.png)

See [Long-term Memory](/memory), [Deep Dream](/memory/deep-dream), and [Self-Evolution](/memory/self-evolution) for details.

## 2. Personal Knowledge Base

> The knowledge base system enables the Agent to continuously accumulate and organize structured knowledge. Unlike memory which records along a timeline, the knowledge base is organized by topics, transforming articles, conversation insights, and learning materials into interconnected Markdown pages that form a continuously growing knowledge network.

The Agent automatically organizes valuable information from conversations into knowledge pages, maintaining cross-references and indexes. The Web console provides document browsing and knowledge graph visualization. Knowledge is stored in `~/cow/knowledge/` within the workspace.

* **Auto-organization**: The Agent autonomously extracts and organizes structured knowledge during conversations, maintaining indexes and cross-references
* **Knowledge graph**: Automatically builds a knowledge graph from cross-references between pages, with interactive graph visualization in the Web console
* **Chat integration**: Knowledge document links referenced in Agent replies can be clicked directly in the Web console for viewing
* **CLI management**: Use `/knowledge` commands to view stats, browse directory, and toggle the feature with `/knowledge on|off`

![](https://cdn.link-ai.tech/doc/20260413105435.png)

See [Personal Knowledge Base](/knowledge) for details.

## 3. Task Planning and Tool Use

Tools are the core of how the Agent accesses operating system resources. The Agent intelligently selects and invokes tools based on task requirements, performing file read/write, command execution, scheduled tasks, and more. Built-in tools are implemented in the project's `agent/tools/` directory.

**Key tools:** file read/write/edit, Bash terminal, browser, file send, scheduler, memory search, web search, environment config, and more.

### 3.1 Terminal and File Access

Access to the OS terminal and file system is the most fundamental and core capability. Many other tools and skills build on top of this. Users can interact with the Agent from a mobile device to operate resources on their personal computer or server:

![](https://cdn.link-ai.tech/doc/20260202181130.png)

### 3.2 Programming Capability

Combining programming and system access, the Agent can execute the complete **Vibecoding workflow** — from information search, asset generation, coding, testing, deployment, Nginx configuration, to publishing — all triggered by a single command from your phone:

![](https://cdn.link-ai.tech/doc/20260318211018.png)

### 3.3 Scheduled Tasks

The `scheduler` tool enables dynamic scheduled tasks, supporting **one-time tasks, fixed intervals, and Cron expressions**. Tasks can be triggered as either a **fixed message send** or an **Agent dynamic task** execution:

![](https://cdn.link-ai.tech/doc/20260202195402.png)

### 3.4 Browser

The built-in `browser` tool allows the Agent to control a Chromium browser to visit web pages, fill forms, click elements, and take screenshots, with support for dynamic JS-rendered pages. Run `cow install-browser` to install with one command, automatically adapting to server (headless) and desktop environments:

![](https://cdn.link-ai.tech/doc/20260401110103.png)

### 3.5 Environment Variable Management

Secrets required by skills are stored in an environment variable file, managed by the `env_config` tool. You can update secrets through conversation, with built-in security protection and desensitization:

![](https://cdn.link-ai.tech/doc/20260202234939.png)

## 4. Skills System

The Skills system provides infinite extensibility for the Agent. Each Skill consists of a description file, execution scripts (optional), and resources (optional), describing how to complete specific types of tasks. Skills allow the Agent to follow instructions for complex workflows, invoke tools, or integrate third-party systems.

* [Skill Hub](https://skills.cowagent.ai/): An open skill marketplace featuring official, community, and third-party skills. Install with one command.
* **Built-in skills:** Located in the project's `skills/` directory, including skill creator, image recognition, LinkAI agent, web fetch, and more. Built-in skills are automatically enabled based on dependency conditions (API keys, system commands, etc.).
* **Custom skills:** Created by users through conversation, stored in the workspace (`~/cow/skills/`), capable of implementing any complex business process or third-party integration.

Install skills: `/skill install <name>` or `cow skill install <name>`, supporting Skill Hub, GitHub, ClawHub, URL, and more.

### 4.1 Creating Skills

The `skill-creator` skill enables rapid skill creation through conversation. You can ask the Agent to codify a workflow as a skill, or send any API documentation and examples for the Agent to complete the integration directly:

![](https://cdn.link-ai.tech/doc/20260202202247.png)

### 4.2 Web Search and Image Recognition

* **Web search:** Built-in `web_search` tool, supports multiple search engines. Configure `BOCHA_API_KEY` or `LINKAI_API_KEY` to enable.
* **Image recognition:** Built-in `openai-image-vision` skill, supports `gpt-4.1-mini`, `gpt-4.1`, and other models. Requires `OPENAI_API_KEY`.

![](https://cdn.link-ai.tech/doc/20260202213219.png)

### 4.3 Skill Hub

Visit [skills.cowagent.ai](https://skills.cowagent.ai/) to browse all available skills, or use commands in conversation:

```text theme={null}
/skill list --remote          # Browse Skill Hub
/skill search <keyword>       # Search skills
/skill install <name>          # Install with one command
```

Also supports installing skills from GitHub, ClawHub, LinkAI, and other third-party platforms. See [Install Skills](/skills/install) for details.

![](https://cdn.link-ai.tech/doc/20260401110103.png)

## 5. CLI Command System

CowAgent provides two command interaction methods, covering service management, skill installation, configuration, and more:

* **Terminal CLI:** Run `cow <command>` in the system terminal, supporting `start`, `stop`, `restart`, `update`, `status`, `logs`, `skill`, etc.
* **Chat commands:** Type `/<command>` in conversation. The Web console shows a command menu when you type `/`.

```bash theme={null}
cow start              # Start service
cow stop               # Stop service
cow update             # Update and restart
cow skill install pptx # Install a skill
cow install-browser    # Install browser tool
```

See [Command Overview](https://docs.cowagent.ai/en/cli) for details.

## 6. Multi-Agent Teams

CowAgent is no longer just a single Agent. You can create multiple Agents to form a team, each with its own responsibilities, model, skills, and knowledge, with isolated workspaces and memory. They can work independently or be brought into the same session to collaborate. A channel can bind a single Agent or the whole team to serve externally, making it easy to set up a team of digital employees.

![](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/team-overview.png)

In a group-chat session, multiple Agents can participate together: use `@` to direct a member to answer, or let the lead Agent automatically **delegate** a task to a more suitable member and consolidate the reply. The lead Agent can also spin up temporary **sub-Agents** to handle independent subtasks in parallel, returning only the conclusion without cluttering the main conversation's context.

![](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/agent-group-session.png)

See [Agent Teams](/multi-agent/team), [Task Delegation](/tools/delegate), and [Sub-Agents](/multi-agent/subagent) for details.


# Introduction
Source: https://docs.cowagent.ai/intro/index

CowAgent is an open-source super AI assistant and Agent Harness that plans tasks, runs tools and skills, keeps long-term memory and a knowledge base, and self-evolves across models and channels.

![CowAgent](https://cdn.link-ai.tech/doc/78c5dd674e2c828642ecc0406669fed7.png)

**CowAgent** is an open-source super AI assistant and Agent Harness. It proactively plans tasks, runs tools and skills, and autonomously grows with memory and knowledge.

CowAgent is lightweight, easy to deploy, and built to extend. Plug in any major LLM provider, quickly assemble a multi-agent team, run it across Web and major IM platforms, 24/7 on a personal computer or server.

<video />

> **[GitHub](https://github.com/zhayujie/CowAgent)**
>
> Open-source repository — Star and contribute

> **[Try Online](https://link-ai.tech/cowagent/create?utm_source=cowagent\&utm_medium=docs\&utm_campaign=intro)**
>
> No setup required — experience CowAgent instantly

## Core Capabilities

> **[Autonomous Task Planning](/intro/architecture)**
>
> Decomposes complex tasks and executes them step by step, looping over tools and skills until the goal is reached.

> **[Long-term Memory](/memory/index)**
>
> Three-tier architecture (context → daily → core), automatic Deep Dream distillation, hybrid keyword + vector retrieval.

> **[Personal Knowledge Base](/knowledge/index)**
>
> Auto-curates structured knowledge into a Markdown wiki, builds an evolving knowledge graph with visual browsing.

> **[Self-Evolution](/memory/self-evolution)**
>
> Reviews conversations automatically to improve skills, follow up on unfinished tasks, and consolidate memory and knowledge, growing through everyday use.

> **[Skills System](/skills/index)**
>
> A complete skill creation and execution engine. Install from Skill Hub or generate custom skills via natural-language conversation.

> **[Tool System](/tools/index)**
>
> Built-in file I/O, terminal, browser, scheduler, memory retrieval, web search, and more — with native MCP integration.

> **[Command System](/cli/index)**
>
> Terminal CLI and in-chat commands for process management, skill installation, configuration, and context inspection.

> **[Pluggable Models](/models/index)**
>
> Claude, GPT, Gemini, DeepSeek, Qwen, GLM, Kimi, MiniMax, Doubao, and more — swap providers from the Web console with one click.

> **[Multi-channel Integration](/channels/index)**
>
> A single Agent simultaneously serves Web, WeChat, Feishu, DingTalk, WeCom, QQ, and Official Accounts.

> **[Multi-Agent Teams](/multi-agent/team)**
>
> Create multiple Agents with distinct roles to form a team, with group-chat collaboration, task delegation, and sub-Agents — usable in the Web console, desktop client, and channel integrations.

## Quick Start

Run one of the commands below to install, configure, and start CowAgent in a single step:

**Linux / macOS**

```bash theme={null}
bash <(curl -fsSL https://cdn.link-ai.tech/code/cow/run.sh)
```

**Windows (PowerShell)**

```powershell theme={null}
irm https://cdn.link-ai.tech/code/cow/run.ps1 | iex
```

**Docker**

```bash theme={null}
curl -O https://cdn.link-ai.tech/code/cow/docker-compose.yml
docker compose up -d
```

Once started, open `http://localhost:9899` to access the **Web console** — the unified place to chat, configure providers, connect channels, and install skills.

> **[Quick Start](/guide/quick-start)**
>
> Complete installation and run guide

> **[Architecture](/intro/architecture)**
>
> CowAgent system architecture

## Disclaimer

1. This project is licensed under the [MIT License](https://github.com/zhayujie/CowAgent/blob/master/LICENSE) and is intended for technical research and learning. You are responsible for complying with applicable laws and regulations in your jurisdiction; the maintainers assume no liability for any consequences arising from use of this project.
2. **Cost & safety:** Agent mode consumes substantially more tokens than plain chat — pick models that balance quality and cost. The Agent has access to your local operating system; deploy only in trusted environments.
3. CowAgent is a pure open-source project and does not participate in, authorize, or issue any cryptocurrency.

## Community

> **[Join our Discord](https://discord.gg/9U8eA8v9TR)**
>
> Ask questions, share skills, and follow development

Or scan the WeChat QR code to join the open-source community group:

![](https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/open-community.png)


# Personal Knowledge Base
Source: https://docs.cowagent.ai/knowledge/index

CowAgent's personal knowledge base organizes shared articles, conversation insights and study notes by topic into interlinked Markdown pages and a knowledge graph. Explains how it differs from memory.

The personal knowledge base is the Agent's long-term structured knowledge store, saved in the `knowledge/` directory within the workspace. Unlike memory, which is organized by timeline, the knowledge base organizes content by topic — articles, conversation insights, and learning materials are structured into interlinked Markdown pages, forming a continuously growing knowledge network.

![](https://cdn.link-ai.tech/doc/20260413105435.png)

## Core Concepts

### Knowledge vs Memory

| Dimension | Knowledge Base (knowledge/) | Long-term Memory (memory/) |
| - | - | - |
| Organization | By topic, interlinked | By timeline, dated files |
| Writing | Agent actively structures content | Auto-summarized on context trimming |
| Content | Refined, structured knowledge | Raw conversation summaries |
| Use cases | Study notes, tech docs, project knowledge | Conversation history, event records |

### Directory Structure

```
~/cow/knowledge/
├── index.md          # Knowledge index, entry point for all pages
├── log.md            # Change log, records each write
├── concepts/         # Conceptual knowledge
│   └── machine-learning.md
├── entities/         # Entity knowledge (people, orgs, tools)
│   └── openai.md
└── sources/          # Source knowledge (articles, papers)
    └── llm-wiki.md
```

The directory structure is flexible — the Agent automatically creates appropriate category directories based on actual content. Users can also customize the organization.

## Automatic Organization

Knowledge writing is an autonomous Agent behavior, triggered in these scenarios:

* **User shares an article or document** — The Agent automatically extracts key information and creates a structured knowledge page
* **Conversation produces valuable conclusions** — The Agent organizes insights into knowledge pages and links them to existing knowledge
* **User explicitly requests organization** — Users can guide the Agent to organize and update knowledge through conversation

Each knowledge page includes cross-reference links to related pages, gradually building a knowledge graph.

![](https://cdn.link-ai.tech/doc/20260413110104.png)

## Knowledge Retrieval

The Agent can retrieve knowledge during conversation through:

* **Index lookup** — Quickly locate relevant pages via `knowledge/index.md`
* **Semantic search** — Search knowledge content via the `memory_search` tool
* **Direct read** — Read specific knowledge files via the `memory_get` tool

## Web Console

The web console provides a dedicated "Knowledge" module with:

* **Document browsing** — Tree-style directory structure, searchable and collapsible, click to view content
* **Knowledge graph** — Interactive graph visualizing relationships between knowledge pages
* **Chat integration** — Knowledge document links referenced in Agent replies are clickable for direct navigation

![](https://cdn.link-ai.tech/doc/17aad553d3e9e428c52ff9dc31726fda.png)

![](https://cdn.link-ai.tech/doc/20260413105402.png)

## CLI Commands

Manage the knowledge base with the `/knowledge` command:

| Command | Description |
| - | - |
| `/knowledge` | Show knowledge base statistics |
| `/knowledge list` | Display file directory as a tree |
| `/knowledge on` | Enable the knowledge base feature |
| `/knowledge off` | Disable the knowledge base feature |

## Configuration

| Parameter | Description | Default |
| - | - | - |
| `knowledge` | Whether to enable the personal knowledge base | `true` |
| `agent_workspace` | Workspace path; knowledge is stored under the `knowledge/` subdirectory | `~/cow` |


# Short-term Memory
Source: https://docs.cowagent.ai/memory/context

Short-term memory is the conversation context of messages, replies and tool results. Learn its structure, key settings, multi-stage compression on overflow, and commands to inspect or clear it.

Conversation context is the Agent's short-term memory, containing all messages in the current session (user input, Agent replies, tool calls and results). Proper context management is critical for the Agent's reasoning quality and cost control.

## Context Structure

Each conversation turn consists of:

```
User message → Agent thinking → Tool call → Tool result → ... → Agent final reply
```

A single turn may include multiple tool calls (controlled by `agent_max_steps`). All tool calls and results are retained in context until compressed or trimmed.

## Key Configuration

| Parameter | Description | Default |
| - | - | - |
| `agent_max_context_tokens` | Maximum context token budget | `200000` |
| `agent_max_context_turns` | Maximum conversation turns in context | `30` |
| `agent_max_steps` | Maximum decision steps per turn (tool call count) | `100` |
| Configurable via `config.json` or the `/config` chat command. | | |

## Compression Strategy

When context exceeds limits, the system automatically compresses to free space. The process has multiple stages:

### 1. Tool Result Truncation

Before each decision loop, the system checks tool call results in historical turns. Results exceeding **20,000 characters** are truncated, keeping only the beginning and end with a truncation notice. Current turn results are not affected.

### 2. Turn Trimming

When conversation turns exceed `agent_max_context_turns`:

* The **oldest half** of complete turns is trimmed (preserving tool call chain integrity)
* Trimmed messages are summarized by LLM and **written to the daily memory file**
* Once the LLM summary is ready, it is also **injected into the first user message** of the retained context, helping the model maintain conversational continuity
* Summary injection runs asynchronously in the background and takes effect from the next turn onward

### 3. Token Budget Trimming

After turn trimming, if tokens still exceed the budget:

* **Fewer than 5 turns**: All turns undergo **text compression** — each turn keeps only the first user text and last Agent reply, removing intermediate tool call chains
* **5 or more turns**: The **first half** of turns is trimmed again, with discarded content written to memory and a context summary injected

### 4. Overflow Emergency Handling

When the model API returns a context overflow error:

1. All current messages are summarized and written to memory
2. Aggressive trimming is applied (tool results limited to 10K chars, user text to 10K, max 5 turns)
3. If still overflowing, the entire conversation context is cleared

### 5. Manual Compaction

Besides the automatic strategies above, you can compact context on demand with the `/compact` command. It reuses the same logic as automatic trimming — older turns are summarized by the LLM and injected into the retained context, while the most recent turns are kept intact. Unlike auto-trim, it runs immediately regardless of current token usage, which is handy for freeing context before a long task.

## Session Persistence

Conversation messages are persisted to a local database, automatically restored after service restart. Restore strategy:

* Restores the most recent **`max(3, max_context_turns / 6)`** turns
* Only retains each turn's **user text and Agent final reply**, not intermediate tool call chains
* Sessions older than **30 days** are automatically cleaned up

## Commands

Use these commands in chat to manage context:

| Command | Description |
| - | - |
| `/context` | View current context statistics (message count, role distribution, total characters) |
| `/clear` | Clear current session context (`/context clear` still works as an alias) |
| `/compact` | Summarize older turns to free up context, keeping recent turns intact |
| `/config agent_max_context_tokens 80000` | Adjust context token budget |
| `/config agent_max_context_turns 30` | Adjust context turn limit |

> [!TIP]
>
> After clearing context, the Agent "forgets" previous conversation content. Content that was already written to long-term memory can still be retrieved via memory search.


# Deep Dream
Source: https://docs.cowagent.ai/memory/deep-dream

Deep Dream is CowAgent's memory consolidation: conversations become daily memories, which are distilled into MEMORY.md every day along with a dream diary. Covers triggers, the process and manual runs.

Deep Dream is the core consolidation mechanism of CowAgent's memory system, responsible for distilling scattered daily memories into refined long-term memory and generating dream diaries.

## Memory Flow

CowAgent's memory progresses through three stages from short-term to long-term:

```
Conversation context (short-term) → Daily memory (mid-term) → MEMORY.md (long-term)
```

### 1. Conversation → Daily Memory

When conversation context is trimmed or during the daily scheduled summary, the system uses LLM to summarize conversation content into key events, writing them to the daily memory file `memory/YYYY-MM-DD.md`.

Triggers:

* **Context trimming** — Trimmed content is summarized when turn or token limits are exceeded
* **Daily schedule** — Automatically triggered at 23:55
* **API overflow** — Emergency save of current conversation summary

### 2. Daily Memory → MEMORY.md (Distillation)

After the daily summary completes, Deep Dream automatically runs distillation:

1. **Read materials** — Current `MEMORY.md` + today's daily memory
2. **LLM distillation** — Deduplicate, merge, prune, extract new information
3. **Overwrite MEMORY.md** — Output the refined long-term memory
4. **Generate dream diary** — Record discoveries and insights from the consolidation

### 3. Role of MEMORY.md

`MEMORY.md` is injected into the system prompt for every conversation, keeping the Agent aware of user preferences, decisions, and key facts. Therefore it must stay concise — Deep Dream targets approximately 30 entries or fewer.

## Distillation Rules

Deep Dream follows these consolidation rules:

| Operation | Description |
| - | - |
| **Merge & refine** | Combine similar entries into single high-density statements |
| **Extract new** | Pull preferences, decisions, people, experiences from daily memory |
| **Conflict update** | When new info contradicts old entries, newer info takes precedence |
| **Clean invalid** | Remove temporary records, blank entries, formatting artifacts |
| **Remove redundancy** | Delete old entries already covered by more refined statements |

## Dream Diary

Each distillation generates a dream diary saved at `memory/dreams/YYYY-MM-DD.md`, written in a narrative style recording:

* Duplications or contradictions found
* New insights extracted from daily memory
* Cleanups and optimizations performed
* Overall observations

Dream diaries can be viewed in the Web console under "Memory → Dream Diary" tab.

![](https://cdn.link-ai.tech/doc/20260414110032.png)

## Manual Trigger

In addition to the automatic daily run, you can manually trigger distillation in chat:

```text theme={null}
/memory dream [N]
```

* `N`: Consolidate the last N days of memory (default 3, max 30)
* Runs asynchronously in the background; you'll be notified in chat when complete
* Web notifications include clickable links to view MEMORY.md and dream diary
* Works without Agent initialization — can be used before the first conversation

> [!TIP]
>
> After first deployment, it's recommended to run `/memory dream 30` once to distill all historical daily memories into MEMORY.md.

## Config Toggle

Control the nightly automatic distillation via `deep_dream_enabled` in `config.json`:

```json theme={null}
{
  "deep_dream_enabled": true
}
```

| Key | Description | Default |
| - | - | - |
| `deep_dream_enabled` | Enable the daily scheduled distillation | `true` |

Enabled by default to keep existing behavior. When disabled, the nightly distillation no longer runs — useful if you prefer to maintain MEMORY.md manually or want to save an LLM call (daily memory summarization is not affected). The manual `/memory dream` command is also unaffected and can still be triggered anytime.

## Safety Mechanisms

| Mechanism | Description |
| - | - |
| **Skip on no content** | Distillation skipped when no daily memory exists, avoiding empty overwrites |
| **Input dedup** | In scheduled tasks, automatically skipped when input materials haven't changed |
| **Async execution** | Distillation runs in a background thread, never blocking conversation |
| **Sequential guarantee** | In scheduled tasks, daily flush completes before distillation starts |
| **No fabrication** | Prompt explicitly constrains consolidation to existing materials only |


# Long-term Memory
Source: https://docs.cowagent.ai/memory/index

CowAgent's long-term memory: core memory in MEMORY.md, daily memories and dream diaries stored as workspace files, written automatically when context is trimmed and recalled with hybrid search.

Long-term memory is stored in workspace files, persisting across sessions. The Agent loads historical memory on demand via retrieval tools during conversation, and automatically writes conversation summaries to long-term memory when context is trimmed.

![Memory Architecture](https://cdn.link-ai.tech/doc/memory-architecture-en.jpg)

## Memory Types

### Core Memory (MEMORY.md)

Stored in `~/cow/MEMORY.md`, containing long-term user preferences, important decisions, key facts, and other information that doesn't fade over time. The Agent reads and writes this file via tools to maintain long-term knowledge.

### Daily Memory (memory/YYYY-MM-DD.md)

Stored in `~/cow/memory/` directory, named by date (e.g., `2026-03-08.md`), recording daily conversation summaries and key events. Files are only created on first write to avoid generating empty files.

### Dream Diary (memory/dreams/YYYY-MM-DD.md)

A byproduct of the Deep Dream (memory distillation) process, recording discoveries, deduplication operations, and new insights from each consolidation. Stored in `~/cow/memory/dreams/` directory, named by date.

## Automatic Writing

The Agent automatically persists conversation content to long-term memory through the following mechanisms:

* **On context trimming** — When conversation turns or tokens exceed the configured limit, the oldest half of the context is trimmed, and the discarded content is summarized by LLM into key information and written to the daily memory file. The summary is also asynchronously injected into the retained context for conversational continuity
* **Daily scheduled summary** — A full summary is automatically triggered at 23:55 every day, ensuring memory is preserved even on low-activity days (skipped if content hasn't changed)
* [Deep Dream (memory distillation)](/memory/deep-dream) — Runs automatically after the daily summary, distilling daily memories into MEMORY.md and generating a dream diary
* **On API context overflow** — When the model API returns a context overflow error, the current conversation summary is saved as an emergency measure

All memory writes run asynchronously in a background thread (LLM summarization + file writing), never blocking normal conversation replies.

## Memory Retrieval

The memory system supports hybrid retrieval modes:

* **Keyword retrieval** — FTS5 full-text index matching with BM25 ranking
* **Vector retrieval** — Embedding-based semantic similarity search, finds relevant memory even with different wording

The Agent automatically triggers memory retrieval during conversation as needed, incorporating relevant historical information into context. Results are ranked by rank-normalizing the vector and keyword scores onto a common scale and taking a weighted average (default: 0.7 vector weight + 0.3 keyword weight). Because the top hit is always normalized to 1.0, `min_score` acts as a rank-position cutoff rather than an absolute relevance floor. Daily memory scores decay over time (30-day half-life), while core memory does not decay.

> [!TIP]
>
> For more precise ranking, rerank can optionally be enabled: run `pip install sentence-transformers`, then set `"rerank_provider": "local"` in the config, and results are reordered by a local rerank model (default `BAAI/bge-reranker-base`). It is off by default and has no effect unless configured.

## Related Files

Files related to memory in the workspace (default `~/cow`):

| File | Description |
| - | - |
| `AGENT.md` | Agent personality and behavior settings |
| `USER.md` | User identity information and preferences |
| `RULE.md` | Custom rules and constraints |
| `MEMORY.md` | Core memory (long-term) |
| `memory/YYYY-MM-DD.md` | Daily memory (created on demand) |
| `memory/dreams/YYYY-MM-DD.md` | Dream diary (auto-generated by Deep Dream) |

## Web Console

The memory management page in the Web console allows browsing memory files and dream diaries, with tab switching support:

![](https://cdn.link-ai.tech/doc/20260414171014.png)

## Configuration

| Parameter | Description | Default |
| - | - | - |
| `agent_workspace` | Workspace path, memory files stored under this directory | `~/cow` |
| `agent_max_context_tokens` | Max context tokens; when exceeded, content is trimmed and summarized into memory | `200000` |
| `agent_max_context_turns` | Max context turns; when exceeded, content is trimmed and summarized into memory | `30` |
| `rerank_provider` | Rerank service for memory retrieval; empty disables it, `local` uses a local cross-encoder | `""` |
| `rerank_model` | Rerank model; empty uses the provider's default | `BAAI/bge-reranker-base` |
| `memory.hit_boost` | Nudge frequently retrieved memories up the ranking (fading after about a week idle); off keeps ranking unchanged and searches write nothing | `false` |


# Self-Evolution
Source: https://docs.cowagent.ai/memory/self-evolution

Self-Evolution lets the agent review each conversation afterwards: fixing skills, following up on unfinished tasks and saving what matters to memory and knowledge, quietly in the background.

## Overview

### Introduction

Self-Evolution lets the Agent do more than finish one task at a time; it keeps improving as it works with you. After a conversation winds down, it quietly reviews what just happened: it saves anything worth remembering into long-term memory, fixes problems that surfaced in a skill, and picks up tasks that were left unfinished. Over time the Agent learns your preferences, repeats fewer mistakes, and gets better at wrapping things up on its own. All of this runs in the background, and it only tells you when it actually did something.

> [!NOTE]
>
> For the full architecture and engineering behind the self-evolution mechanism, see the blog post: [A Five-Layer Self-Evolution Mechanism for AI Agents](https://cowagent.ai/blog/self-evolution/).

> Self-Evolution complements [Deep Dream](/memory/deep-dream). Deep Dream organizes memory itself, while Self-Evolution goes a step further to improve skills and push unfinished tasks forward, sharpening the Agent's abilities through everyday use.

![Self-Evolution in a conversation](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/web-console-evolution-demo.png)

### Three Goals

Self-Evolution focuses on three things:

| Goal | Description |
| - | - |
| **Consolidate memory** | Record important preferences, decisions, and facts from the conversation, filling in what the main chat may have missed |
| **Improve skills** | ① When a skill shows a problem in use (such as a wrong setting or a missing step), fix the skill file directly; ② when a reusable workflow emerges, turn it into a new skill so it can be reused next time |
| **Follow up on unfinished tasks** | Spot the to-dos left in a conversation and finish them when possible |

Once a review is done, if it actually changed something, the Agent tells you in a single line what it just learned and what it adjusted, so you can decide whether to roll it back.

## Usage

### When It Triggers

Self-Evolution does not run on a fixed schedule. It only kicks in **after a conversation naturally ends and goes idle**, so it never interrupts an ongoing exchange. Two conditions must both hold:

* **The conversation is idle**: more time has passed since the last interaction than the configured idle window (10 minutes by default)
* **There is enough to review**: enough turns have accumulated since the last evolution, or the context is close to its capacity

Only when both are met does a review begin. This makes sure there is something worth reviewing while keeping it from bothering you mid-conversation.

### Configuration

You can toggle Self-Evolution in the Web console under **Settings → Agent Config** (below "Deep Thinking"), or adjust it in the config file:

| Parameter | Description | Default |
| - | - | - |
| `self_evolution_enabled` | Whether Self-Evolution is enabled (on by default for new installs) | `false` |
| `self_evolution_idle_minutes` | How long the conversation must be idle before it triggers (minutes) | `10` |
| `self_evolution_min_turns` | Minimum conversation turns required to trigger | `6` |

![Enable Self-Evolution in the Web console](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/web-console-evolution-config.png)

> [!TIP]
>
> The Web console only exposes the on/off toggle. To change the idle window or the turn threshold, edit the config file. Changes take effect immediately, with no restart needed.

### Evolution Records

Each review is recorded by date in `memory/evolution/YYYY-MM-DD.md`, viewable in the Web console under the **Memory → Self-Evolution** tab. That tab gathers both self-evolution records and dream diaries in one place, so you can look back on how the Agent has grown.

![Self-Evolution records list](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/web-console-evolution-logs.png)

### Rolling Back

If you disagree with a change from a review, just tell the Agent in chat to undo the last change. It restores the affected files from the backup taken before the review. Every review keeps its own backup, so they never interfere with each other.

## Design

Self-Evolution reuses what the system already has, which keeps it lightweight:

* **Isolated execution**: each review runs as a separate, short-lived task. It uses the same model as the main chat but with a restricted toolset (it can only read context and edit memory and skill files). It does not pollute the main chat's context or affect its performance.
* **Backup-based undo**: the relevant files are snapshotted before a review and restored from that snapshot on undo, so every change is traceable and reversible.
* **Change detection**: after a review, the system compares file snapshots to see whether anything actually changed, and uses that to decide whether to notify you. This is how it guarantees, at the engineering level, that no work means no message.

### Restraint and Safety

Self-Evolution is built to act when needed and stay out of the way otherwise:

| Mechanism | Description |
| - | - |
| **No work, no notification** | If a review produces no real change, it stays silent and sends nothing |
| **Triggers only when idle** | It runs only after the conversation is idle, never interrupting an active one |
| **Reversible changes** | A backup is taken before every review, so you can undo a result you do not like |
| **Built-in skills protected** | The skills shipped with the product are protected and never modified |
| **Workspace-scoped** | All reads and writes stay inside the workspace and never touch other system files |
| **Runs in the background** | Reviews run in the background and do not block normal replies |


# Claude
Source: https://docs.cowagent.ai/models/claude

Configure Anthropic Claude in CowAgent: chat with native image understanding, plus thinking mode with adjustable reasoning effort, set up in the web console or config.json.

Claude is provided by Anthropic and supports both text chat and image understanding. The mainstream Sonnet / Opus models natively support vision, so no separate Vision model needs to be specified.

> [!TIP]
>
> All capabilities below can be configured in one place via the "Model Management" page in the Web Console, with no need to manually edit the configuration file.

## Text Chat

```json theme={null}
{
  "model": "claude-opus-5-5",
  "claude_api_key": "YOUR_API_KEY"
}
```

| Parameter | Description |
| - | - |
| `model` | Supports `claude-opus-5-5`, `claude-opus-5`, `claude-sonnet-5`, `claude-fable-5-1`, `claude-fable-5`, `claude-opus-4-8`, `claude-opus-4-7`, `claude-sonnet-4-6`, `claude-opus-4-6`, `claude-sonnet-4-5`, `claude-sonnet-4-0`, `claude-3-5-sonnet-latest`, etc. See [official models](https://docs.anthropic.com/en/docs/about-claude/models/overview) |
| `claude_api_key` | Create one in the [Claude Console](https://console.anthropic.com/settings/keys) |
| `claude_api_base` | Optional, defaults to `https://api.anthropic.com/v1`. Can be changed to a third-party proxy |

### Model Selection

| Model | Use Case |
| - | - |
| `claude-opus-5-5` | Latest flagship; default recommendation, best on complex reasoning and long-running Agent tasks |
| `claude-opus-5` | Previous Opus flagship |
| `claude-sonnet-5` | Balanced option in the Claude 5 family; good reasoning quality at a lower price |
| `claude-fable-5-1` | Alternative flagship in the Claude 5 family (newer revision) |
| `claude-fable-5` | Alternative flagship in the Claude 5 family |
| `claude-opus-4-8` / `claude-opus-4-7` | Earlier Opus flagships |
| `claude-sonnet-4-6` | Balanced cost and speed, lower cost |
| `claude-opus-4-6` / `claude-sonnet-4-5` / `claude-sonnet-4-0` | Earlier flagships at a lower price |

## Thinking Mode

Controlled by the global `enable_thinking` setting, which can also be toggled on the Web Console configuration page. When enabled, the Web Console shows the thinking process:

```json theme={null}
{
  "enable_thinking": true,
  "reasoning_effort": "high"
}
```

`reasoning_effort` sets the thinking intensity (mapped to Anthropic's `output_config.effort`) and accepts `low` / `medium` / `high` / `xhigh` / `max`, with the supported range depending on the model. It only takes effect when `enable_thinking` is `true`.

## Image Understanding

Once `claude_api_key` is configured, the Agent's Vision tool automatically uses the Claude main model to recognize images, with no extra setup required.

To manually specify a Vision model, set it explicitly in the configuration file:

```json theme={null}
{
  "tools": {
    "vision": {
      "model": "claude-sonnet-5"
    }
  }
}
```


# Coding Plan
Source: https://docs.cowagent.ai/models/coding-plan

Use vendors' Coding Plan subscriptions with CowAgent for heavy agent use. Connect Alibaba Cloud, MiniMax, Zhipu, Volcano Engine, Kimi and others through the OpenAI-compatible API.

> Coding Plan is a monthly subscription package offered by various providers, ideal for high-frequency Agent usage. CowAgent supports all Coding Plan providers via OpenAI-compatible mode.

> [!NOTE]
>
> Coding Plan API Base and API Key are usually separate from the standard pay-as-you-go ones. Please obtain them from each provider's platform.

## General Configuration

All providers can be accessed via the OpenAI-compatible protocol, and can be quickly configured through the web console. Set the model provider to **OpenAI**, select a custom model and enter the model code, then fill in the corresponding provider's API Base and API Key:

![](https://cdn.link-ai.tech/doc/20260318113134.png)

You can also configure directly in `config.json`:

```json theme={null}
{
  "bot_type": "openai",
  "model": "MODEL_NAME",
  "open_ai_api_base": "PROVIDER_CODING_PLAN_API_BASE",
  "open_ai_api_key": "YOUR_API_KEY"
}
```

| Parameter | Description |
| - | - |
| `bot_type` | Must be `openai` (OpenAI-compatible mode) |
| `model` | Model name supported by the provider |
| `open_ai_api_base` | Provider's Coding Plan API Base URL |
| `open_ai_api_key` | Provider's Coding Plan API Key |

***

## Alibaba Cloud

```json theme={null}
{
  "bot_type": "openai",
  "model": "qwen3.5-plus",
  "open_ai_api_base": "https://coding.dashscope.aliyuncs.com/v1",
  "open_ai_api_key": "YOUR_API_KEY"
}
```

| Parameter | Description |
| - | - |
| `model` | `qwen3.5-plus`, `qwen3-max-2026-01-23`, `qwen3-coder-next`, `qwen3-coder-plus`, `glm-5`, `glm-4.7`, `kimi-k2.5`, `MiniMax-M2.5` |
| `open_ai_api_base` | `https://coding.dashscope.aliyuncs.com/v1` |
| `open_ai_api_key` | Coding Plan specific key (not shared with pay-as-you-go) |

Reference: [Quick Start](https://help.aliyun.com/zh/model-studio/coding-plan-quickstart?spm=a2c4g.11186623.help-menu-2400256.d_0_2_1.70115203zi5Igc), [Model List](https://help.aliyun.com/zh/model-studio/coding-plan)

***

## MiniMax

```json theme={null}
{
  "bot_type": "openai",
  "model": "MiniMax-M3",
  "open_ai_api_base": "https://api.minimaxi.com/v1",
  "open_ai_api_key": "YOUR_API_KEY"
}
```

| Parameter | Description |
| - | - |
| `model` | `MiniMax-M3`, `MiniMax-M2.7`, `MiniMax-M2.7-highspeed` |
| `open_ai_api_base` | China: `https://api.minimaxi.com/v1`; Global: `https://api.minimax.io/v1` |
| `open_ai_api_key` | Coding Plan specific key (not shared with pay-as-you-go) |

Reference: [China Key](https://platform.minimaxi.com/docs/coding-plan/quickstart), [Model List](https://platform.minimaxi.com/docs/guides/pricing-coding-plan), [Global Key](https://platform.minimax.io/docs/coding-plan/quickstart)

***

## GLM

```json theme={null}
{
  "bot_type": "openai",
  "model": "glm-4.7",
  "open_ai_api_base": "https://open.bigmodel.cn/api/coding/paas/v4",
  "open_ai_api_key": "YOUR_API_KEY"
}
```

| Parameter | Description |
| - | - |
| `model` | `glm-5`, `glm-4.7`, `glm-4.6`, `glm-4.5`, `glm-4.5-air` |
| `open_ai_api_base` | China: `https://open.bigmodel.cn/api/coding/paas/v4`; Global: `https://api.z.ai/api/coding/paas/v4` |
| `open_ai_api_key` | Shared with standard API |

Reference: [China Quick Start](https://docs.bigmodel.cn/cn/coding-plan/quick-start), [Global Quick Start](https://docs.z.ai/devpack/quick-start)

***

## Kimi

```json theme={null}
{
  "bot_type": "moonshot",
  "model": "kimi-for-coding",
  "moonshot_base_url": "https://api.kimi.com/coding/v1",
  "moonshot_api_key": "YOUR_API_KEY"
}
```

| Parameter | Description |
| - | - |
| `model` | Use `kimi-for-coding` for auto-updating model, or specify a model such as `kimi-k2.6` |
| `moonshot_base_url` | `https://api.kimi.com/coding/v1` |
| `moonshot_api_key` | Coding Plan specific key (not shared with pay-as-you-go) |

Reference: [Key & Docs](https://www.kimi.com/code/docs/?aff=cowagent)

***

## Volcengine

```json theme={null}
{
  "bot_type": "openai",
  "model": "Doubao-Seed-2.0-Code",
  "open_ai_api_base": "https://ark.cn-beijing.volces.com/api/coding/v3",
  "open_ai_api_key": "YOUR_API_KEY"
}
```

| Parameter | Description |
| - | - |
| `model` | `Doubao-Seed-2.0-Code`, `Doubao-Seed-2.0-pro`, `Doubao-Seed-2.0-lite`, `Doubao-Seed-Code`, `MiniMax-M2.5`, `Kimi-K2.5`, `GLM-4.7`, `DeepSeek-V3.2` |
| `open_ai_api_base` | `https://ark.cn-beijing.volces.com/api/coding/v3` |
| `open_ai_api_key` | Shared with standard API |

Reference: [Quick Start](https://www.volcengine.com/docs/82379/1928261?lang=zh)


# Custom
Source: https://docs.cowagent.ai/models/custom

Add custom model providers to CowAgent for any OpenAI-compatible service: third-party API proxies, local models served by Ollama or vLLM, or private deployments, with multiple providers supported.

For model services accessed via the OpenAI-compatible protocol, such as:

* **Third-party API proxies**: call multiple models through a unified API base
* **Local models**: models deployed locally with tools like Ollama, vLLM
* **Private deployments**: model services deployed inside an enterprise

## Web Console

Recommended. On the "Models" page of the Web console, click "Add Provider" and pick "Custom", then fill in the name, API Base and API Key. Multiple custom providers can be added; after adding one, select it together with a model in the "Main Model" card to enable it.

![](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/web-console-custom-model-config.png)

Default endpoints of common local deployment tools:

| Tool | Default API Base |
| - | - |
| [Ollama](https://ollama.com) | `http://localhost:11434/v1` |
| [vLLM](https://docs.vllm.ai) | `http://localhost:8000/v1` |
| [LocalAI](https://localai.io) | `http://localhost:8080/v1` |

## Configuration File

You can also edit `config.json` directly: define multiple providers in the `custom_providers` list and set `bot_type` to `"custom:<id>"` to activate one of them:

```json theme={null}
{
  "bot_type": "custom:3f2a9c1b",
  "custom_providers": [
    {
      "id": "3f2a9c1b",
      "name": "ProviderA",
      "api_key": "YOUR_API_KEY_A",
      "api_base": "https://api.a.com/v1",
      "model": "deepseek-v3"
    },
    {
      "id": "a1b2c3d4",
      "name": "ProviderB",
      "api_key": "YOUR_API_KEY_B",
      "api_base": "https://api.b.com/v1",
      "model": "qwen3-max"
    }
  ]
}
```

| Parameter | Description |
| - | - |
| `custom_providers` | List of custom providers; each item has `id`, `name`, `api_base`, `api_key` (optional) and `model` (optional) |
| `bot_type` | Set to `"custom:<id>"` to activate the corresponding provider |
| `id` | Unique identifier (8-char hex); auto-generated when adding via the Web console, or any unique string when editing manually |
| `name` | Display label, can be renamed freely |
| `model` | Model used by this provider, takes effect when activated |

> [!NOTE]
>
> The legacy single-provider configuration (`bot_type` set to `"custom"` with `custom_api_key` / `custom_api_base`) remains fully compatible and keeps working without any changes.


# DeepSeek
Source: https://docs.cowagent.ai/models/deepseek

Configure DeepSeek in CowAgent, a cost-effective default for agent mode: chat and task planning, with thinking mode on the V4 series, set up in the web console or config.json.

DeepSeek is one of the default recommended providers in Agent mode, focused on cost-effective text chat and task planning.

## Text Chat

```json theme={null}
{
  "model": "deepseek-flash",
  "deepseek_api_key": "YOUR_API_KEY"
}
```

| Parameter | Description |
| - | - |
| `model` | Supports `deepseek-flash` (Default, V4.1 Flash, natively multimodal), `deepseek-v4-flash`, `deepseek-v4-pro` |
| `deepseek_api_key` | Create one on the [DeepSeek Platform](https://platform.deepseek.com/api_keys) |
| `deepseek_api_base` | Optional, defaults to `https://api.deepseek.com/v1`. Can be changed to a third-party proxy |

### Model Selection

| Model | Use Case |
| - | - |
| `deepseek-flash` | Default recommended; V4.1 Flash, natively multimodal, fast and low cost |
| `deepseek-v4-flash` | Previous-generation V4 Flash |
| `deepseek-v4-pro` | Smarter; better for complex tasks |

## Thinking Mode

`deepseek-flash` and the V4 series (`deepseek-v4-flash` / `deepseek-v4-pro`) support an explicit "thinking mode": before producing the final answer, the model emits a chain of thought (`reasoning_content`) to improve answer quality.

### Toggle

Controlled by the global `enable_thinking` config, and can also be toggled from the Web Console's configuration page:

```json theme={null}
{
  "enable_thinking": true
}
```

* `true`: the model thinks before answering across all channels. The Web Console displays the thinking process; IM channels (WeChat / WeCom / DingTalk / Feishu) do not show it but still get better answers.
* `false`: thinking is disabled, responses are faster, and time-to-first-token is lower.

### Reasoning Effort

Under thinking mode, `reasoning_effort` controls reasoning intensity:

```json theme={null}
{
  "enable_thinking": true,
  "reasoning_effort": "high"
}
```

| Value | Use Case |
| - | - |
| `high` (Default) | Day-to-day Agent tasks; balanced reasoning and speed |
| `max` | Complex coding, long-horizon planning, strictly constrained tasks; deeper reasoning but more time and output tokens |

`reasoning_effort` only takes effect when `enable_thinking` is `true`; it is ignored automatically when the model does not support thinking mode.

### Behavior Notes

* **Sampling parameters**: in thinking mode, `temperature`, `top_p`, `presence_penalty`, and `frequency_penalty` are ignored by the server (without errors). CowAgent automatically skips them.
* **Multi-turn tool calls**: when the history contains tool calls, DeepSeek requires every assistant message to include `reasoning_content`. CowAgent handles this automatically, so toggling thinking mode across turns will not cause errors.

> [!TIP]
>
> `deepseek-flash` (V4.1 Flash, natively multimodal) is used by default; switch to `deepseek-v4-pro` for complex tasks; enable `enable_thinking` when deep reasoning is needed.


# Doubao
Source: https://docs.cowagent.ai/models/doubao

Configure Doubao (Volcano Ark) in CowAgent: one ark_api_key enables chat, image understanding, Seedream image generation and multimodal embeddings, set up from the web console.

Doubao (Volcengine Ark) supports text chat, image understanding, image generation (Seedream), and embedding. A single `ark_api_key` enables all capabilities.

> [!TIP]
>
> All capabilities below can be configured in one place via the "Model Management" page in the Web Console, with no need to manually edit the configuration file.

## Text Chat

```json theme={null}
{
  "model": "doubao-seed-2-1-pro-260628",
  "ark_api_key": "YOUR_API_KEY"
}
```

| Parameter | Description |
| - | - |
| `model` | Can be `doubao-seed-2-1-pro-260628`, `doubao-seed-2-1-turbo-260628`, `doubao-seed-2-0-pro-260215`, `doubao-seed-2-0-code-preview-260215`, etc. |
| `ark_api_key` | Create one in the [Volcengine Ark Console](https://console.volcengine.com/ark/region:ark+cn-beijing/apikey) |
| `ark_base_url` | Optional, defaults to `https://ark.cn-beijing.volces.com/api/v3` |

## Image Understanding

Once `ark_api_key` is configured and the main model is a Doubao model, the Agent's Vision tool automatically uses the current main model to recognize images, with no extra setup required.

To manually specify a Vision model:

```json theme={null}
{
  "tools": {
    "vision": {
      "model": "doubao-seed-2-1-pro-260628"
    }
  }
}
```

## Image Generation

```json theme={null}
{
  "skills": {
    "image-generation": {
      "model": "seedream-5.0-lite"
    }
  }
}
```

Available models: `seedream-5.0-lite`, `seedream-4.5`.

## Embedding

```json theme={null}
{
  "embedding_provider": "doubao",
  "embedding_model": "doubao-embedding-vision-251215"
}
```

The default model is `doubao-embedding-vision-251215` (multimodal embedding); the dimension (1024 or 2048) can be set via `embedding_dimensions` in the configuration file. After changing the embedding, run `/memory rebuild-index` to rebuild the index.


# Gemini
Source: https://docs.cowagent.ai/models/gemini

Configure Google Gemini in CowAgent: one API key enables chat, native image understanding and Nano Banana image generation, all set up from the web console.

Google Gemini supports text chat, image understanding, and image generation (Nano Banana series). A single `gemini_api_key` enables all capabilities.

> [!TIP]
>
> All capabilities below can be configured in one place via the "Model Management" page in the Web Console, with no need to manually edit the configuration file.

## Text Chat

```json theme={null}
{
  "model": "gemini-3.8-flash",
  "gemini_api_key": "YOUR_API_KEY"
}
```

| Parameter | Description |
| - | - |
| `model` | Recommended: `gemini-3.8-flash`; also supports `gemini-3.7-flash`, `gemini-3.6-flash`, `gemini-3.5-flash`, `gemini-3.1-pro-preview`, `gemini-3.1-flash-lite-preview`, `gemini-3-flash-preview`, `gemini-3-pro-preview`, etc. See [official docs](https://ai.google.dev/gemini-api/docs/models) |
| `gemini_api_key` | Create one in [Google AI Studio](https://aistudio.google.com/app/apikey) |
| `gemini_api_base` | Optional, defaults to `https://generativelanguage.googleapis.com`. Can be changed to a third-party proxy |

## Image Understanding

All Gemini models natively support vision. Once `gemini_api_key` is configured, the Agent's Vision tool automatically uses the main model to recognize images, with no extra setup required.

To manually specify a Vision model:

```json theme={null}
{
  "tools": {
    "vision": {
      "model": "gemini-3.1-flash-lite-preview"
    }
  }
}
```

## Image Generation

```json theme={null}
{
  "skills": {
    "image-generation": {
      "model": "gemini-3.1-flash-image-preview"
    }
  }
}
```

| Model ID | Alias |
| - | - |
| `gemini-3.1-flash-image-preview` | Nano Banana 2 |
| `gemini-3-pro-image-preview` | Nano Banana Pro |
| `gemini-2.5-flash-image` | Nano Banana |


# GLM
Source: https://docs.cowagent.ai/models/glm

Configure Zhipu GLM in CowAgent: one API key enables chat, image understanding, speech recognition and embeddings, with automatic fallback to a vision model, set up from the web console.

Zhipu AI supports text chat, image understanding, speech-to-text (ASR), and embedding. A single `zhipu_ai_api_key` enables all capabilities.

> [!TIP]
>
> All capabilities below can be configured in one place via the "Model Management" page in the Web Console, with no need to manually edit the configuration file.

## Text Chat

```json theme={null}
{
  "model": "glm-5.3-flash",
  "zhipu_ai_api_key": "YOUR_API_KEY"
}
```

| Parameter | Description |
| - | - |
| `model` | Can be `glm-5.3-flash` (recommended, 1M context / 128K max output), `glm-5.3`, `glm-5.2`, `glm-5.1`, `glm-5-turbo`, `glm-5`, `glm-4.7`, `glm-4-plus`, `glm-4-flash`, `glm-4-air`, etc. See [model codes](https://bigmodel.cn/dev/api/normal-model/glm-4) |
| `zhipu_ai_api_key` | Create one in the [Zhipu AI Console](https://www.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
| `zhipu_ai_api_base` | Optional, defaults to `https://open.bigmodel.cn/api/paas/v4` |

## Image Understanding

`glm-5.3-flash` is natively multimodal, so when it is the main model the Agent's Vision tool uses it directly. Text-only chat models (`glm-5.2`, `glm-5.1`, `glm-5-turbo`, etc.) do not support vision; for those, vision calls automatically fall back to the dedicated `glm-5v-turbo` model. Once `zhipu_ai_api_key` is configured, no extra setup is needed.

## Speech-to-Text (ASR)

```json theme={null}
{
  "voice_to_text": "zhipu",
  "voice_to_text_model": "glm-asr-2512"
}
```

| Parameter | Description |
| - | - |
| `voice_to_text` | Set to `zhipu` to enable Zhipu ASR |
| `voice_to_text_model` | Optional, defaults to `glm-asr-2512` |

Credentials are automatically reused from `zhipu_ai_api_key`. Audio files should be smaller than 25MB; oversized files may be rejected by the server.

## Embedding

```json theme={null}
{
  "embedding_provider": "zhipu",
  "embedding_model": "embedding-3"
}
```

Available models: `embedding-3`, `embedding-2`. After changing the embedding, run `/memory rebuild-index` to rebuild the index.


# Models Overview
Source: https://docs.cowagent.ai/models/index

Model providers CowAgent supports and what each can do: text, vision, image generation, speech and embeddings across OpenAI, Claude, Gemini, DeepSeek, Qwen, Doubao, Kimi, GLM, MiniMax and more.

CowAgent supports a wide range of mainstream large language models. Model interfaces live under the project's `models/` directory. Beyond text chat, several providers also provide vision understanding, image generation, speech-to-text, text-to-speech, and embeddings — all of which can be invoked on demand in the Agent flow.

## Capability Matrix

A snapshot of each provider's capabilities. "Text" refers to the main chat model; the remaining columns show which Agent capabilities the provider can power.

| Provider | Representative Models | Text | Vision | Image Gen | STT | TTS | Embedding |
| - | - | :-: | :-: | :-: | :-: | :-: | :-: |
| [DeepSeek](/models/deepseek) | deepseek-flash (V4.1) / pro | ✅ | ✅ | | | | |
| [Claude](/models/claude) | claude-opus-5-5 / sonnet-5 | ✅ | ✅ | | | | |
| [OpenAI](/models/openai) | gpt-6.1 / gpt-6 series | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| [Gemini](/models/gemini) | gemini-3.8-flash | ✅ | ✅ | ✅ | | | |
| [MiniMax](/models/minimax) | MiniMax-M3 | ✅ | ✅ | ✅ | | ✅ | |
| [GLM](/models/glm) | glm-5.3-flash, glm-5v-turbo | ✅ | ✅ | | ✅ | | ✅ |
| [Qwen](/models/qwen) | qwen3.8-flash | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| [Kimi](/models/kimi) | kimi-k3 | ✅ | ✅ | | | | |
| [Doubao](/models/doubao) | doubao-seed-2.1 series | ✅ | ✅ | ✅ | | | ✅ |
| [ERNIE](/models/qianfan) | ernie-5.1 | ✅ | ✅ | | | | |
| [MiMo](/models/mimo) | mimo-v2.6-pro / v2.6-flash | ✅ | ✅ | | ✅ | ✅ | |
| [LinkAI](/models/linkai) | 100+ models from multiple providers | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| [Custom](/models/custom) | Local models / third-party proxies | ✅ | | | | | |

> [!TIP]
>
> Every capability in the Web console (Vision / Image / STT / TTS / Embedding / Web Search) can be configured independently with its own provider and model — there is no forced binding between them.

## How to Configure

**Option 1 (recommended):** Manage models and capabilities online via the [Web console](/channels/web), with no need to edit the configuration file:

![](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/web-console-models-config.png)

**Option 2:** Edit `config.json` manually and fill in the model name and API key for the selected provider. Every model also supports OpenAI-compatible access — just set `bot_type` to `openai` and configure `open_ai_api_base` and `open_ai_api_key`.


# Kimi
Source: https://docs.cowagent.ai/models/kimi

Configure Kimi (Moonshot) in CowAgent: chat with native image understanding; once moonshot_api_key is set the vision tool uses Kimi automatically. Set up from the web console.

Kimi is provided by Moonshot and supports both text chat and image understanding. The `kimi-k3` and `kimi-k2.x` series natively support vision.

> [!TIP]
>
> All capabilities below can be configured in one place via the "Model Management" page in the Web Console, with no need to manually edit the configuration file.

## Text Chat

```json theme={null}
{
  "model": "kimi-k3",
  "moonshot_api_key": "YOUR_API_KEY"
}
```

| Parameter | Description |
| - | - |
| `model` | Can be `kimi-k3`, `kimi-k2.7-code`, `kimi-k2.7-code-highspeed`, `kimi-k2.6`, `kimi-k2.5`, `kimi-k2`, `moonshot-v1-8k`, `moonshot-v1-32k`, `moonshot-v1-128k` |
| `moonshot_api_key` | Create one in the [Moonshot Console](https://platform.kimi.com?aff=cowagent) |
| `moonshot_base_url` | Optional, defaults to `https://api.moonshot.cn/v1` |

## Image Understanding

Once `moonshot_api_key` is configured, the Agent's Vision tool automatically uses `kimi-k2.6` to recognize images, with no extra setup required.

To manually specify a Vision model:

```json theme={null}
{
  "tools": {
    "vision": {
      "model": "kimi-k2.6"
    }
  }
}
```


# LinkAI
Source: https://docs.cowagent.ai/models/linkai

Use one linkai_api_key on the LinkAI platform to reach models from OpenAI, Claude, Gemini, DeepSeek, Qwen, Kimi, Doubao and more for chat, vision, image generation, speech and embeddings.

A single `linkai_api_key` gives you access to all capabilities of mainstream providers such as OpenAI, Claude, Gemini, DeepSeek, MiniMax, Qwen, Kimi, and Doubao.

> [!TIP]
>
> All capabilities below can be configured in one place via the "Model Management" page in the Web Console, with no need to manually edit the configuration file.

## Text Chat

```json theme={null}
{
  "use_linkai": true,
  "linkai_api_key": "YOUR_API_KEY"
}
```

| Parameter | Description |
| - | - |
| `use_linkai` | Set to `true` to enable |
| `linkai_api_key` | Create one in the [Console](https://link-ai.tech/console/interface?utm_source=cowagent\&utm_medium=docs\&utm_campaign=models-linkai) |
| `model` | Can be any code from the [model list](https://link-ai.tech/console/models?utm_source=cowagent\&utm_medium=docs\&utm_campaign=models-linkai) |

See [Model Service](https://link-ai.tech/console/models?utm_source=cowagent\&utm_medium=docs\&utm_campaign=models-linkai) for more.

## Image Understanding

Once configured, the Agent's Vision tool automatically calls multimodal models via the gateway, with no extra setup required. To manually specify a Vision model:

```json theme={null}
{
  "tools": {
    "vision": {
      "model": "gpt-5.4-mini"
    }
  }
}
```

Available models: `gpt-4.1-mini`, `gpt-5.4-mini`, `qwen3.8-flash`, `qwen3.7-plus`, `doubao-seed-2-1-pro-260628`, `kimi-k2.6`, `claude-sonnet-5`, `claude-fable-5-1`, `claude-fable-5`, `gemini-3.1-flash-lite-preview`, etc.

## Image Generation

```json theme={null}
{
  "skills": {
    "image-generation": {
      "model": "gpt-image-2.5-flare"
    }
  }
}
```

| Model ID | Alias |
| - | - |
| `gpt-image-2.5-flare` | OpenAI |
| `gpt-image-2.5-sunburst` | OpenAI |
| `gpt-image-2` | OpenAI |
| `gemini-3.1-flash-image-preview` | Nano Banana 2 |
| `gemini-3-pro-image-preview` | Nano Banana Pro |
| `seedream-5.0-lite` | ByteDance Doubao Seedream |

## Speech-to-Text (ASR)

```json theme={null}
{
  "voice_to_text": "linkai"
}
```

ASR uses Whisper by default; credentials are automatically reused from `linkai_api_key`.

## Text-to-Speech (TTS)

The TTS gateway supports multiple underlying engines. The engine is selected by `text_to_voice_model`, and the available voices change with the engine.

```json theme={null}
{
  "text_to_voice": "linkai",
  "text_to_voice_model": "doubao",
  "tts_voice_id": "BV001_streaming"
}
```

| `text_to_voice_model` | Engine |
| - | - |
| `tts-1` | OpenAI · Multi-language (voices like `alloy` / `nova` / `echo`, etc.) |
| `doubao` | ByteDance Doubao · Rich Chinese voices |
| `baidu` | Baidu · Chinese broadcaster voices |

Voices differ by engine; we recommend selecting them visually in the Web Console under "Model Management → Text-to-Speech".

## Embedding

```json theme={null}
{
  "embedding_provider": "linkai",
  "embedding_model": "text-embedding-3-small"
}
```

The default model is `text-embedding-3-small` (OpenAI-compatible). After changing the embedding, run `/memory rebuild-index` to rebuild the index.


# MiMo
Source: https://docs.cowagent.ai/models/mimo

Configure Xiaomi MiMo, a natively omni-modal model, in CowAgent: one API key enables chat, image understanding, speech recognition and text-to-speech, with thinking mode on by default for V2.6.

Xiaomi MiMo is a native omni-modal large model. A single `mimo_api_key` enables text chat, image understanding, speech recognition, and text-to-speech all at once.

> [!TIP]
>
> All capabilities below can be configured in one place via the "Model Management" page in the Web Console — no need to manually edit the configuration file.

## Text Chat

```json theme={null}
{
  "model": "mimo-v2.6-pro",
  "mimo_api_key": "YOUR_API_KEY",
  "mimo_api_base": "https://api.xiaomimimo.com/v1"
}
```

| Parameter | Description |
| - | - |
| `model` | Default recommendation: `mimo-v2.6-pro`; `mimo-v2.6-flash` is also supported |
| `mimo_api_key` | Create one in the [MiMo Open Platform](https://platform.xiaomimimo.com/console/api-keys) |
| `mimo_api_base` | Optional, defaults to `https://api.xiaomimimo.com/v1` |

### Model Selection

| Model | Use Case |
| - | - |
| `mimo-v2.6-pro` | Flagship: native omni-modal + Agent capability, up to 1M tokens context |
| `mimo-v2.6-flash` | Faster and cheaper, native omni-modal (text / image / video / audio), up to 1M tokens context |

## Thinking Mode

The MiMo V2.6 series enables "thinking mode" by default: the model emits `reasoning_content` (chain-of-thought) before the final answer, improving performance on complex tasks.

Use the global `enable_thinking` flag to toggle visibility (also switchable from the Web Console settings):

```json theme={null}
{
  "enable_thinking": true
}
```

## Image Understanding

Once `mimo_api_key` is configured, the Agent's Vision tool can automatically use MiMo's vision models:

* When the main model itself is multimodal (`mimo-v2.6-pro` / `mimo-v2.6-flash`), images are handled directly by the main model with no extra setup.
* When the main model belongs to another provider, the Vision tool falls back to `mimo-v2.6-pro` in order.

To force a specific Vision model, set it explicitly in the configuration:

```json theme={null}
{
  "tools": {
    "vision": {
      "provider": "mimo",
      "model": "mimo-v2.6-pro"
    }
  }
}
```

## Speech-to-Text (ASR)

```json theme={null}
{
  "voice_to_text": "mimo",
  "voice_to_text_model": "mimo-v2.5-asr"
}
```

| Parameter | Description |
| - | - |
| `voice_to_text` | Set to `mimo` to enable MiMo ASR |
| `voice_to_text_model` | Optional, defaults to `mimo-v2.5-asr` (Chinese and English with automatic language detection, plus dialects such as Cantonese, Wu, Minnan and Sichuanese) |

Credentials are automatically reused from `mimo_api_key`. MiMo only accepts MP3 / WAV audio, so voice messages in other formats (e.g. AMR / SILK / Opus) are converted to MP3 before recognition. The encoded audio must stay under 10MB.

## Text-to-Speech (TTS)

```json theme={null}
{
  "text_to_voice": "mimo",
  "text_to_voice_model": "mimo-v2.5-tts",
  "tts_voice_id": "冰糖"
}
```

| Parameter | Description |
| - | - |
| `text_to_voice_model` | Currently only `mimo-v2.5-tts` (preset voices + singing mode) |
| `tts_voice_id` | Preset voice name (Chinese voice IDs use the Chinese name directly) |

### Preset Voices

| Voice ID | Description |
| - | - |
| `Mia` | English · Female |
| `Chloe` | English · Female |
| `Milo` | English · Male |
| `Dean` | English · Male |
| `冰糖` | Chinese · Female (default) |
| `茉莉` | Chinese · Female |
| `苏打` | Chinese · Male |
| `白桦` | Chinese · Male |

You can also pick a voice visually from the Web Console under "Model Management → Text-to-Speech".

### Style Control

MiMo TTS supports embedding **audio tags** in the synthesis text to control emotion, tone, dialect, persona, and even singing. Tags must appear in the **text that will be synthesized to speech (i.e. the Agent's reply)**, with the overall style tag placed at the very beginning:

```
(style)content-to-synthesize
```

Half-width `()`, full-width `（）`, and `[]` brackets are all accepted. Both Chinese and English style descriptors work — pick whichever language expresses the timbre most precisely. Common examples:

| Category | Example tags |
| - | - |
| Basic emotions | `happy` `sad` `angry` `fear` `surprised` `excited` `aggrieved` `calm` `indifferent` |
| Compound emotions | `wistful` `relieved` `helpless` `guilty` `at ease` `uneasy` `touched` |
| Overall tone | `gentle` `aloof` `lively` `serious` `languid` `playful` `deep` `sharp` `cutting` |
| Voice character | `magnetic` `mellow` `bright` `ethereal` `childlike` `aged` `sweet` `husky` |
| Persona | `squeaky` `mature lady` `young boy` `uncle` `Taiwanese accent` |
| Dialect | `Northeastern` `Sichuan` `Henan` `Cantonese` |
| Role-play | `Sun Wukong` `Lin Daiyu` |
| Singing | `sing` / `singing` |

Examples:

* `(magnetic)The night is deep, and the city is still breathing.`
* `(gentle)Take a breath. You've got this.`
* `(serious)This is the final warning before the system reboots.`
* `(singing)Oh, when the saints go marching in…`

You can also insert fine-grained audio tags at any position in the text to control breathing, laughter, pauses, etc. For example:

```
(nervous, deep breath) Phew… stay calm, stay calm. (faster pace) I've rehearsed this intro fifty times, it'll be fine.
```

See the [MiMo speech synthesis documentation](https://platform.xiaomimimo.com/docs/zh-CN/usage-guide/speech-synthesis-v2.5) for the full tag list.

> [!TIP]
>
> When CowAgent calls TTS, the Agent's reply text (including any `(...)` tags) is forwarded directly to MiMo for synthesis. Tell the model in its persona / system prompt to "prefix replies with a `(style)` tag to control the tone", and IM channels (WeChat / Feishu / DingTalk / WeCom) will play voice replies with the corresponding emotion, dialect, or even singing.


# MiniMax
Source: https://docs.cowagent.ai/models/minimax

Configure MiniMax in CowAgent: one API key enables chat, image understanding, image generation and text-to-speech with 70+ voices in Chinese, Cantonese, English, Japanese and Korean.

MiniMax supports text chat, image understanding, image generation, and text-to-speech. A single `minimax_api_key` enables all capabilities.

> [!TIP]
>
> All capabilities below can be configured in one place via the "Model Management" page in the Web Console, with no need to manually edit the configuration file.

## Text Chat

```json theme={null}
{
  "model": "MiniMax-M3",
  "minimax_api_key": "YOUR_API_KEY"
}
```

| Parameter | Description |
| - | - |
| `model` | Can be `MiniMax-M3`, `MiniMax-M2.7`, `MiniMax-M2.7-highspeed`, etc. |
| `minimax_api_key` | Create one in the [MiniMax Console](https://platform.minimaxi.com/user-center/basic-information/interface-key) |

## Image Understanding

MiniMax-M3 natively accepts text, image, and video input through the OpenAI-compatible chat endpoint. Once `minimax_api_key` is configured, the Agent's Vision tool automatically routes image requests to the selected MiniMax-M3 model, with no need to specify a separate vision model.

## Image Generation

```json theme={null}
{
  "skills": {
    "image-generation": {
      "model": "image-01"
    }
  }
}
```

Available models: `image-01`.

## Text-to-Speech (TTS)

```json theme={null}
{
  "text_to_voice": "minimax",
  "text_to_voice_model": "speech-2.8-hd",
  "tts_voice_id": "female-shaonv"
}
```

| Parameter | Description |
| - | - |
| `text_to_voice_model` | `speech-2.8-hd` (emotional rendering, natural sound), `speech-2.8-turbo` (ultra-fast), `speech-2.6-hd`, `speech-2.6-turbo` |
| `tts_voice_id` | Voice ID; supports Chinese / Cantonese / English / Japanese / Korean — 70+ voices in total |

Common voice examples:

| Voice ID | Description |
| - | - |
| `female-shaonv` | Chinese · Young Girl (Female) |
| `female-yujie` | Chinese · Mature Lady (Female) |
| `female-tianmei` | Chinese · Sweet Female (Female) |
| `male-qn-jingying` | Chinese · Elite Youth (Male) |
| `male-qn-badao` | Chinese · Dominant Youth (Male) |
| `Cantonese_GentleLady` | Cantonese · Gentle Female Voice |
| `English_Graceful_Lady` | English · Graceful Lady |

For the full voice list (70+ voices across Chinese / Cantonese / English / Japanese / Korean), see the [system voice list](https://platform.minimaxi.com/docs/faq/system-voice-id), or select visually in the Web Console under "Model Management → Text-to-Speech".


# OpenAI
Source: https://docs.cowagent.ai/models/openai

Configure OpenAI models in CowAgent: one API key enables chat, vision, image generation, speech recognition, text-to-speech and embeddings, set up in the web console or config.json.

OpenAI offers the most complete coverage and can simultaneously serve text chat, vision understanding, image generation, speech-to-text (ASR), text-to-speech (TTS), and embedding. A single `open_ai_api_key` lets the Agent use all of these capabilities.

> [!TIP]
>
> All capabilities below can be configured in one place via the "Model Management" page in the Web Console, with no need to manually edit the configuration file.

## Text Chat

```json theme={null}
{
  "model": "gpt-6.1-sol",
  "open_ai_api_key": "YOUR_API_KEY",
  "open_ai_api_base": "https://api.openai.com/v1"
}
```

| Parameter | Description |
| - | - |
| `model` | Same as OpenAI's [model parameter](https://platform.openai.com/docs/models); supports `gpt-6.1-sol`, `gpt-6-luna`, `gpt-6-sol`, `gpt-6-astra`, `gpt-5.6-luna`, `gpt-5.6-terra`, `gpt-5.6-sol`, `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano`, the `gpt-5` series, `gpt-4.1`, etc. Agent mode defaults to `gpt-6.1-sol`; `gpt-6-astra` is the top flagship (most intelligent, higher cost); tool calling for the `gpt-6` / `gpt-6.1` series goes through the Responses API; use `gpt-5.4` for better cost-efficiency |
| `open_ai_api_key` | Create one on the [OpenAI Platform](https://platform.openai.com/api-keys) |
| `open_ai_api_base` | Optional; change it to access a third-party proxy |
| `open_ai_api_type` | Optional API protocol, defaults to `auto` (only the `gpt-6` / `gpt-6.1` series uses the Responses API, others use Chat Completions). If your endpoint no longer serves `/chat/completions`, set it to `responses` to send all requests to `/responses`; `chat` always uses `/chat/completions`. For Docker deployments, set it via the `OPEN_AI_API_TYPE` environment variable |
| `bot_type` | Not required when using OpenAI's official models; set to `openai` when accessing other providers via the compatible protocol |

## Image Understanding

OpenAI models like `gpt-5.5`, `gpt-5.4`, `gpt-4o`, and `gpt-4.1` natively support vision. Once `open_ai_api_key` is configured, the Agent's Vision tool automatically uses the main model to recognize images. If the main model does not support vision or you want to specify it explicitly, set it in the configuration file:

```json theme={null}
{
  "tools": {
    "vision": {
      "model": "gpt-5.4-mini"
    }
  }
}
```

Supported Vision models: `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5`, `gpt-4.1`, `gpt-4.1-mini`, `gpt-4o`.

## Image Generation

Specify the image generation model in the configuration file; the Agent automatically routes image generation skill calls to OpenAI:

```json theme={null}
{
  "skills": {
    "image-generation": {
      "model": "gpt-image-2.5-flare"
    }
  }
}
```

Supported image generation models: `gpt-image-2.5-flare` (recommended default), `gpt-image-2.5-sunburst`, `gpt-image-2`, `gpt-image-1`.

## Speech-to-Text (ASR)

```json theme={null}
{
  "voice_to_text": "openai",
  "voice_to_text_model": "gpt-4o-mini-transcribe"
}
```

| Parameter | Description |
| - | - |
| `voice_to_text` | Set to `openai` to enable OpenAI speech-to-text |
| `voice_to_text_model` | Optional, defaults to `gpt-4o-mini-transcribe`; can also be `gpt-4o-transcribe`, `whisper-1` |

Credentials are automatically reused from `open_ai_api_key`.

## Text-to-Speech (TTS)

```json theme={null}
{
  "text_to_voice": "openai",
  "text_to_voice_model": "tts-1",
  "tts_voice_id": "alloy"
}
```

| Parameter | Description |
| - | - |
| `text_to_voice_model` | `tts-1`, `tts-1-hd`, `gpt-4o-mini-tts` |
| `tts_voice_id` | Voices: `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`, `ash`, `ballad`, `coral`, `sage`, `verse` |

## Embedding

```json theme={null}
{
  "embedding_provider": "openai",
  "embedding_model": "text-embedding-3-small"
}
```

Available models: `text-embedding-3-small`, `text-embedding-3-large`, `text-embedding-ada-002`. After changing the embedding, run `/memory rebuild-index` to rebuild the index.


# ERNIE
Source: https://docs.cowagent.ai/models/qianfan

Configure Baidu Qianfan ERNIE models in CowAgent: chat and image understanding, with automatic fallback to an ERNIE vision model, set up in the web console or config.json.

Option 1: Native integration (recommended):

```json theme={null}
{
  "model": "ernie-5.1",
  "qianfan_api_key": "",
  "qianfan_api_base": "https://qianfan.baidubce.com/v2"
}
```

| Parameter | Description |
| - | - |
| `model` | Default recommendation: `ernie-5.1`; also supports `ernie-5.0`, `ernie-x1.1`, `ernie-4.5-turbo-128k`, `ernie-4.5-turbo-32k` |
| `qianfan_api_key` | Qianfan API key, usually starting with `bce-v3/` |
| `qianfan_api_base` | Optional, defaults to `https://qianfan.baidubce.com/v2` |

## Model Selection

| Model | Use Case |
| - | - |
| `ernie-5.1` | Default recommendation; latest ERNIE flagship with the strongest overall capability |
| `ernie-5.0` | Previous-generation flagship with excellent overall capability |
| `ernie-x1.1` | Deep-thinking reasoning model with lower hallucination and stronger instruction following / tool calling |
| `ernie-4.5-turbo-128k` | Long-context and general chat |
| `ernie-4.5-turbo-32k` | General chat with a balanced context window and cost |

## Vision tool

Once `qianfan_api_key` is configured, Agent mode can auto-discover Qianfan for the Vision tool:

* When the main model itself is multimodal (e.g. `ernie-5.1`, `ernie-5.0`, `ernie-x1.1`, `ernie-4.5-turbo-vl`), images are handled directly by the main model with no extra setup.
* When the main model is text-only (e.g. `ernie-4.5-turbo-128k`), the Vision tool automatically falls back to `ernie-4.5-turbo-vl`.

To force a specific Vision model, set it explicitly in `config.json`:

```json theme={null}
{
  "tools": {
    "vision": {
      "model": "ernie-4.5-turbo-vl"
    }
  }
}
```

Option 2: OpenAI-compatible configuration:

```json theme={null}
{
  "model": "ernie-5.1",
  "bot_type": "openai",
  "open_ai_api_key": "",
  "open_ai_api_base": "https://qianfan.baidubce.com/v2"
}
```

> [!TIP]
>
> Prefer `qianfan_api_key` for new configurations. Existing `wenxin`, `wenxin-4`, `baidu_wenxin_api_key`, and `baidu_wenxin_secret_key` configurations remain supported.


# Qwen
Source: https://docs.cowagent.ai/models/qwen

Configure Qwen (DashScope / Bailian) in CowAgent: one dashscope_api_key enables chat, vision, image generation, speech recognition, text-to-speech and embeddings, with qwen3.8-flash recommended.

Qwen (Alibaba DashScope / Bailian) is one of the most fully-featured providers. Text, image understanding, image generation, speech-to-text, text-to-speech, and embedding can all be enabled with a single `dashscope_api_key`.

> [!TIP]
>
> All capabilities below can be configured in one place via the "Model Management" page in the Web Console, with no need to manually edit the configuration file.

## Text Chat

```json theme={null}
{
  "model": "qwen3.8-flash",
  "dashscope_api_key": "YOUR_API_KEY"
}
```

| Parameter | Description |
| - | - |
| `model` | Can be `qwen3.8-flash` (recommended, 1M context / 128K max output, multimodal), `qwen3.8-max`, `qwen3.7-plus`, `qwen3.7-max`, `qwen3.6-plus`, `qwen3.5-plus`, `qwen3-max`, `qwen-max`, `qwen-plus`, `qwen-turbo`, `qwq-plus`, etc. |
| `dashscope_api_key` | Create one in the [Bailian Console](https://bailian.console.aliyun.com/?tab=model#/api-key); see the [official docs](https://bailian.console.aliyun.com/?tab=api#/api) |

## Image Understanding

Once `dashscope_api_key` is configured, the Agent's Vision tool automatically calls Qwen's vision models to recognize images. Models like `qwen3.8-flash` / `qwen3.7-plus` / `qwen3.6-plus` / `qwen3.5-plus` / `qwen3-max` are already multimodal; if the main model is text-only (e.g. `qwen-turbo`), it automatically falls back to `qwen-vl-max`.

To manually specify a Vision model:

```json theme={null}
{
  "tools": {
    "vision": {
      "model": "qwen3.8-flash"
    }
  }
}
```

Supported models: `qwen3.8-flash`, `qwen3.7-plus`, `qwen3.6-plus`, `qwen3.5-plus`, `qwen3-max`.

## Image Generation

```json theme={null}
{
  "skills": {
    "image-generation": {
      "model": "qwen-image-2.0"
    }
  }
}
```

Available models: `qwen-image-2.0`, `qwen-image-2.0-pro`.

## Speech-to-Text (ASR)

```json theme={null}
{
  "voice_to_text": "dashscope",
  "voice_to_text_model": "qwen3-asr-flash"
}
```

| Parameter | Description |
| - | - |
| `voice_to_text` | Set to `dashscope` to enable Qwen ASR |
| `voice_to_text_model` | Optional, defaults to `qwen3-asr-flash` |

Credentials are automatically reused from `dashscope_api_key`. A single audio segment should be smaller than 10MB and no longer than 300 seconds.

## Text-to-Speech (TTS)

```json theme={null}
{
  "text_to_voice": "dashscope",
  "text_to_voice_model": "qwen3-tts-flash",
  "tts_voice_id": "Cherry"
}
```

| Parameter | Description |
| - | - |
| `text_to_voice_model` | Optional, defaults to `qwen3-tts-flash`; covers Mandarin, dialects, and major foreign languages |
| `tts_voice_id` | Voice ID; see the common list below |

Common voice examples:

| Voice ID | Description |
| - | - |
| `Cherry` | Qianyue · Sunny Female Voice |
| `Serena` | Suyao · Gentle Female Voice |
| `Ethan` | Chenxu · Sunny Male Voice |
| `Chelsie` | Qianxue · Anime Girl |
| `Dylan` | Beijing Dialect · Xiaodong |
| `Rocky` | Cantonese · Aqiang |
| `Sunny` | Sichuan Dialect · Qing'er |

The full voice list (Mandarin / regional dialects / bilingual, etc.) can be selected visually in the Web Console under "Model Management → Text-to-Speech".

## Embedding

```json theme={null}
{
  "embedding_provider": "dashscope",
  "embedding_model": "text-embedding-v4"
}
```

The default model is `text-embedding-v4`. After changing the embedding, run `/memory rebuild-index` to rebuild the index.


# Sub-Agent
Source: https://docs.cowagent.ai/multi-agent/subagent

Sub-agents are temporary workers the main agent spawns for independent tasks. They run in their own context, can work in parallel and return only the result, saving tokens in the main conversation.

A sub-Agent is a temporary execution unit that the lead Agent creates during a conversation. The lead Agent hands it one independent task, it completes that task in its own context, and it returns the result. The pages it opens, the files it reads, and the commands it runs never enter the main conversation.

> [!NOTE]
>
> Sub-Agents are temporary. They have no identity, memory, or channel of their own, and never appear in the Agent list.

## Two Benefits

* **Isolated context**: intermediate work does not consume the main conversation's context, which saves tokens and keeps the model's attention on what matters
* **Parallel execution**: several sub-Agents can be created and run at once, so the total time is that of the slowest one

## Inheritance and Isolation

A sub-Agent inherits part of the lead Agent's environment, but it is not a copy of it:

| Inherited | Not inherited |
| - | - |
| Model | Message history of the main conversation |
| Workspace (files are read and written in the same place) | Persona and rule files (`AGENT.md`, `RULE.md`, `USER.md`) |
| Skills (types with the full tool set only) | Writing to memory (it can read shared memory / the knowledge base, but never persists writes) |

A sub-Agent therefore knows only what the lead Agent passes to it. It cannot see the conversation history and cannot ask the user anything, so every path, identifier, constraint, and settled conclusion it needs must be stated when the task is created.

## When It Is Triggered

The lead Agent decides on its own. There is nothing to configure and no dedicated command.

**A sub-Agent is created when:**

* Several unrelated things can be done at the same time, such as "research product A and product B separately"
* A task produces a lot of intermediate output but only the conclusion is needed, such as "check whether this error has a known fix in the community"

**A sub-Agent is not created when:**

* The lead Agent needs the intermediate results to continue (reading a few files or running a few searches is ordinary execution)
* The task depends on earlier parts of the conversation, or needs the user to confirm something along the way
* The task should run over the long term across conversations, which is what [scheduled tasks](/tools/scheduler) are for

To force something to be run by a sub-Agent, just say so in the conversation, for example "use sub-Agents to research these two directions separately".

## What You See

Each sub-Agent has its own card in the Web console and desktop client. Expand it to see the tool it is currently calling and the step it has reached; once it finishes, the card holds its full report. Multiple sub-Agents start and finish independently, so it is clear which one is still running.

![](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/cow-subagent-demo.png)

## Types and Configuration

Sub-Agents come in two built-in types, `general-purpose` and `explore`, and custom types can be defined in the workspace. For the types, available tools, concurrency and timeout settings, and the disabled tools, see the [subagent tool](/tools/subagent).


# Agent Teams
Source: https://docs.cowagent.ai/multi-agent/team

Build an agent team in CowAgent: create agents with their own roles, models, skills, knowledge and workspaces that work alone or collaborate in one conversation, with isolated data and permissions.

CowAgent is no longer a single Agent. You can create multiple Agents to form a team: each member has its own responsibilities, model, skills, and knowledge, working independently or being brought into the same session to collaborate.

![Multi-agent team](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/team-overview.png)

## Why a Team

A team of specialized Agents is better suited to complex tasks that span different business domains, for the following reasons:

* **Focused context**: an Agent with too many responsibilities pulls in a lot of irrelevant context, which hurts quality and drives up token cost. Split by domain, each Agent keeps its context focused, answers more accurately, and costs less.
* **Complementary capabilities**: each Agent can be bound to a different model and skill set, and through division of labor, collaboration, or even cross-review, the team can handle tasks a single Agent would struggle with.
* **Data and permission isolation**: each Agent has its own workspace, and its memory, sessions, and output files are not visible to others, which fits boundaries drawn by role or by customer.
* **Better presentation**: different channels, or different instances of the same channel, can connect to different Agents and appear as separate assistants, or an entire team can join one channel to answer collaboratively, making it easy to set up a team of digital employees.

For users who only use a single Agent, the experience stays the same; team-related features appear only after you create a second Agent.

## Creating an Agent

Click Create on the "Agent Team" page in the Web console or desktop client to add an Agent. An Agent is made up of the following parts:

* **Name and avatar**: the identity within the team, shown in chat bubbles, the member list, and channel bindings.
* **Responsibilities**: one sentence describing what the Agent handles. It helps you tell members apart and is used to decide who a task should go to during collaboration.
* **Default model**: you can assign a model to this Agent individually. The default Agent follows the global configuration.
* **Skills and knowledge**: these can be shared with the team, or an Agent can have its own dedicated knowledge base that stays isolated from the others.
* **Copy from an existing Agent**: when creating a new Agent, you can copy an existing Agent's configuration, skills, and knowledge as a starting point.

![Agent-create](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/agent-create.png)

Once created, the Agent appears in the team list. Click any member, and on the right you can switch between "Overview / Skills / Core Files" to configure its basic information, enabled skills, and its persona and rule files (`AGENT.md`, `RULE.md`, and so on).

> [!NOTE]
>
> There is always a default Agent in the team. It is the fallback for new sessions and elsewhere, follows the global model configuration, and cannot be deleted.

### Knowledge Base: Shared or Independent

Every non-default Agent can choose a knowledge base mode:

* **Shared**: reads and writes the same knowledge base as the team, which fits scenarios where everyone works with the same materials.
* **Independent**: has a dedicated knowledge base isolated from other members, which fits cases where materials differ significantly across domains.

You can switch between the two modes at any time; when switching back to shared, the content of the independent base is preserved.

## Joining Sessions and Group Chats

When creating a session, you can have a single Agent talk with you, or start a group chat with multiple Agents.

In an existing session, the Agent selector at the bottom left of the input box lets you:

* **Switch Agent**: an empty session can switch its Agent directly; a session that already has content starts a new conversation with the new Agent, while the existing history stays with the original Agent.
* **Add member**: add another Agent to the current session, turning it into a group chat.
* **Remove member**: remove a member from the current session.

![Agent-team-group](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/agent-group-session.png)

In a group chat, each Agent answers with its own configured model, and the bubble shows which Agent is speaking. Members in the same session read the same record and can see what others have said.

> [!NOTE]
>
> Group chats do not use the session-level model selection; each Agent uses its own configured default model, so no model selector appears in a group chat.

## Channel Integration

A channel of the same type can run multiple instances, and each instance can be bound to a different single Agent or Agent team, appearing as its own separate assistant.

On the "Channels" page, set the bound Agent for a connected instance:

* The first one selected is the owner, responsible for receiving all tasks from this channel.
* You can add more members, and the owner assigns suitable tasks to them based on their responsibilities.
* In the channel, use `@` followed by a member's name or ID to talk to that member directly.

![Agent-team-channel](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/channel-config.png)

Binding changes take effect immediately, with no need to restart the channel. Channels that support multiple instances include WeChat, WeCom bots, DingTalk, Feishu, QQ, Telegram, Slack, Discord, and more.

## Collaboration

Multiple Agents in the same session collaborate in two ways.

### 1. Directing with @

In a group chat, use `@` followed by a member's name to hand the current turn to a specific Agent. Typing `@` brings up the members in the current session to choose from, and once sent, the bubble carries the avatar of the directed Agent to mark who is responsible for that turn.

![Agent-team-group](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/agent-group-chat-demo.png)

### 2. Lead Agent and Delegation

A group chat always has a lead Agent (the owner). Unless the user `@`s someone else, it receives every task. Delegation lets the lead Agent hand a task outside its own domain to a more suitable member:

* **Decide**: after receiving a task, the lead Agent decides automatically, answering directly if the task is within its domain and forwarding it to a more suitable member in the session otherwise.
* **Execute**: the delegated member completes the task in its own workspace and returns the result to the lead Agent.
* **Reply**: the lead Agent consolidates the results and replies to the user, who always faces a single entry point.

Details such as the delegation scope, chain depth, and time budget are handled by the [agent\_delegate tool](/tools/delegate) and can be adjusted in the configuration.

![Agent-team-delegate](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/agent-delegate.png)

## Differences from Sub-Agents

Agent teams and [sub-Agents](/multi-agent/subagent) both share the workload, but they serve different purposes:

| | Team member | Sub-Agent |
| - | - | - |
| Lifecycle | Persistent, configured in advance | Created temporarily for one task, then discarded |
| Identity | Has a name and avatar, appears in the team list, can bind to channels | Anonymous, not in the list |
| Workspace | Independent | Shared with the lead Agent |
| Memory | Independent | Has no memory of its own |
| Use case | Long-term specialization, external-facing service | Splitting your own work to run in parallel, isolating large amounts of intermediate work |

> In short: use team collaboration when the task itself belongs to another persistent Agent (one that holds the relevant knowledge, permissions, or customer relationship); use a sub-Agent when you just want to split your own task to run in parallel and speed things up.


# Changelog
Source: https://docs.cowagent.ai/releases/overview

CowAgent version history: from connecting ChatGPT in 1.0 to the 2.0 super AI assistant, then memory, knowledge base, Skill Hub, desktop app, agent teams and the Chat API, with dates and highlights.

| Version | Date | Description |
| - | - | - |
| [2.2.1](/releases/v2.2.1) | 2026.10.14 | Artifacts center and custom menu, open Agent Chat API, prompt caching and context cost savings, tool, channel and security improvements |
| [2.2.0](/releases/v2.2.0) | 2026.09.30 | Capabilities center, multi-Agent collaboration improvements, Web console rebuild, higher model cache hit rates, broad stability and security hardening |
| [2.1.9](/releases/v2.1.9) | 2026.09.14 | Multi-Agent collaboration refinements, configurable model lists and multiple fallback models, channel integration fixes, and a range of image-generation and voice fixes |
| [2.1.8](/releases/v2.1.8) | 2026.09.10 | Multi-Agent teams (team management, group collaboration, multiple channel instances), manual scheduled tasks, context-usage visualization, model fallback and new search providers, workspace file editing |
| [2.1.7](/releases/v2.1.7) | 2026.08.20 | Multiple workspaces isolated per session, session-level permission modes, task notifications, desktop improvements, new models (glm-5.3, qwen3.8-max, gemini-3.7-flash) |
| [2.1.6](/releases/v2.1.6) | 2026.08.12 | Sub agents for parallel task delegation, reasoning-effort settings, a pluggable memory vector backend, desktop client improvements, plus experience and security improvements |
| [2.1.5](/releases/v2.1.5) | 2026.07.28 | Workspace with file preview, core tool improvements (file search, write-time validation, background commands), context compaction (`/compact`), one-click prompt optimization, security hardening |
| [2.1.4](/releases/v2.1.4) | 2026.07.20 | Desktop client improvements (browser tool, Windows signing, Win7/8 support), MCP OAuth, scheduled tasks and Feishu channel enhancements, data backup & restore, new models (kimi-k3, gpt-5.6) |
| [2.1.3](/releases/v2.1.3) | 2026.07.08 | Desktop client released (macOS / Windows), knowledge base document management, on-demand MCP tool retrieval, Traditional Chinese support, new models (claude-sonnet-5, doubao-seed-2.1, etc.), security hardening and refinements |
| [2.1.2](/releases/v2.1.2) | 2026.06.18 | Web Console upgrades (scheduled task management, knowledge base categories, multiple custom model providers), Self-Evolution improvements, new models (kimi-k2.7-code, glm-5.2), security hardening and refinements |
| [2.1.1](/releases/v2.1.1) | 2026.06.09 | Self-Evolution, Web Console message management and parallel sessions, cross-platform MCP enhancements with concurrent calls, new models (MiniMax-M3, qwen3.7-plus, etc.), various improvements |
| [2.1.0](/releases/v2.1.0) | 2026.06.01 | Internationalization, new Telegram / Discord / Slack / WeChat Customer Service channels, CLI interaction upgrades (streaming output, fuzzy command matching, task cancellation), MCP Streamable HTTP, new models |
| [2.0.9](/releases/v2.0.9) | 2026.05.22 | Model management console, MCP protocol support, browser persistent login, new models (gpt-5.5, gemini-3.5-flash, qwen3.7-max, etc.), deployment hardening |
| [2.0.8](/releases/v2.0.8) | 2026.05.06 | Major Feishu channel upgrade (voice, streaming and Markdown, one-click QR-scan setup), DeepSeek V4 and Baidu models, scheduler tool enhancements |
| [2.0.7](/releases/v2.0.7) | 2026.04.22 | Image Generation Skill (6-provider auto-routing), new models (Kimi K2.6, Claude Opus 4.7, GLM 5.1), knowledge base and Web Console improvements |
| [2.0.6](/releases/v2.0.6) | 2026.04.14 | Project rename, Knowledge Base system, Deep Dream Memory Distillation, Smart Context Compression, Web Console multi-session and various improvements |
| [2.0.5](/releases/v2.0.5) | 2026.04.01 | Cow CLI, Skill Hub open source, Browser tool, WeCom Bot QR scan, and more |
| [2.0.4](/releases/v2.0.4) | 2026.03.22 | Personal WeChat channel, new model support, Japanese docs, script refactoring and bug fixes |
| [2.0.3](/releases/v2.0.3) | 2026.03.18 | WeCom Smart Bot and QQ channels, Coding Plan support, multiple new models, Web file processing, memory system upgrade |
| [2.0.2](/releases/v2.0.2) | 2026.02.27 | Web Console upgrade, multi-channel concurrency, session persistence |
| [2.0.1](/releases/v2.0.1) | 2026.02.13 | Built-in Web Search tool, smart context management, multiple fixes |
| [2.0.0](/releases/v2.0.0) | 2026.02.03 | Full upgrade to AI super assistant |
| 1.7.6 | 2025.05.23 | Web Channel optimization, AgentMesh plugin |
| 1.7.5 | 2025.04.11 | DeepSeek model |
| 1.7.4 | 2024.12.13 | Gemini 2.0 model, Web Channel |
| 1.7.3 | 2024.10.31 | Stability improvements, database features |
| 1.7.2 | 2024.09.26 | One-click install script, o1 model |
| 1.7.0 | 2024.08.02 | iFlytek 4.0 model, knowledge base references |
| 1.6.9 | 2024.07.19 | gpt-4o-mini, Alibaba voice recognition |
| 1.6.8 | 2024.07.05 | Claude 3.5, Gemini 1.5 Pro |
| 1.6.0 | 2024.04.26 | Kimi integration, gpt-4-turbo upgrade |
| 1.5.8 | 2024.03.26 | GLM-4, Claude-3, edge-tts |
| 1.5.2 | 2023.11.10 | Feishu channel, image recognition chat |
| 1.5.0 | 2023.11.10 | gpt-4-turbo, dall-e-3, tts multimodal |
| 1.0.0 | 2022.12.12 | Project created, first ChatGPT integration |

See [GitHub Releases](https://github.com/zhayujie/CowAgent/releases) for full history.


# v2.0.1
Source: https://docs.cowagent.ai/releases/v2.0.1

CowAgent 2.0.1: web search becomes a built-in tool, smart context trimming prevents token overflow, Claude Opus 4.6 and WeCom image recognition arrive, and scheduler memory loss is fixed.

**Release Date**: 2026.02.27 | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.0.0..2.0.1)

## New Features

* **Built-in Web Search tool**: Integrated web search as a built-in Agent tool, reducing decision cost ([4f0ea5d](https://github.com/zhayujie/CowAgent/commit/4f0ea5d7568d61db91ff69c91c429e785fd1b1c2))
* **Claude Opus 4.6 model support**: Added support for Claude Opus 4.6 model ([#2661](https://github.com/zhayujie/CowAgent/pull/2661))
* **WeCom image recognition**: Support image message recognition in WeCom channel ([#2667](https://github.com/zhayujie/CowAgent/pull/2667))

## Improvements

* **Smart context management**: Resolved chat context overflow with intelligent context trimming strategy to prevent token limits ([cea7fb7](https://github.com/zhayujie/CowAgent/commit/cea7fb7490c53454602bf05955a0e9f059bcf0fd), [8acf2db](https://github.com/zhayujie/CowAgent/commit/8acf2dbdfe713b84ad74b761b7f86674b1c1904d)) [#2663](https://github.com/zhayujie/CowAgent/issues/2663)
* **Runtime info dynamic update**: Automatic update of timestamps and other runtime info in system prompts via dynamic functions ([#2655](https://github.com/zhayujie/CowAgent/pull/2655), [#2657](https://github.com/zhayujie/CowAgent/pull/2657))
* **Skill prompt optimization**: Improved Skill system prompt generation, simplified tool descriptions for better Agent performance ([6c21833](https://github.com/zhayujie/CowAgent/commit/6c218331b1f1208ea8be6bf226936d3b556ade3e))
* **GLM custom API Base URL**: Support custom API Base URL for GLM models ([#2660](https://github.com/zhayujie/CowAgent/pull/2660))
* **Startup script optimization**: Improved `run.sh` script interaction and configuration flow ([#2656](https://github.com/zhayujie/CowAgent/pull/2656))
* **Decision step logging**: Added Agent decision step logging for debugging ([cb303e6](https://github.com/zhayujie/CowAgent/commit/cb303e6109c50c8dfef1f5e6c1ec47223bf3cd11))

## Bug Fixes

* **Scheduler memory loss**: Fixed memory loss caused by Scheduler dispatcher ([a77a874](https://github.com/zhayujie/CowAgent/commit/a77a8741b500a408c6f5c8868856fb4b018fe9db))
* **Empty tool calls & long results**: Fixed handling of empty tool calls and excessively long tool results ([0542700](https://github.com/zhayujie/CowAgent/commit/0542700f9091ebb08c1a56103b0f0f45f24aa621))
* **OpenAI Function Call**: Fixed function call compatibility with OpenAI models ([158c87a](https://github.com/zhayujie/CowAgent/commit/158c87ab8b05bae054cc1b4eacdbb64fc1062ba9))
* **Claude tool name field**: Removed extraneous tool name field from Claude model responses ([eec10cb](https://github.com/zhayujie/CowAgent/commit/eec10cb5db6a3d5bc12ef606606532237d2c5f6e))
* **MiniMax reasoning**: Optimized MiniMax model reasoning content handling, hidden thinking process output ([c72cda3](https://github.com/zhayujie/CowAgent/commit/c72cda33864bd1542012ee6e0a8bd8c6c88cb5ed), [72b1cac](https://github.com/zhayujie/CowAgent/commit/72b1cacea1ba0d1f3dedacbab2e088e98fd7e172))
* **GLM thinking process**: Hidden GLM model thinking process display ([72b1cac](https://github.com/zhayujie/CowAgent/commit/72b1cacea1ba0d1f3dedacbab2e088e98fd7e172))
* **Feishu connection & SSL**: Fixed Feishu channel SSL certificate errors and connection issues ([229b14b](https://github.com/zhayujie/CowAgent/commit/229b14b6fcabe7123d53cab1dea39f38dab26d6d), [8674421](https://github.com/zhayujie/CowAgent/commit/867442155e7f095b4f38b0856f8c1d8312b5fcf7))
* **model\_type validation**: Fixed `AttributeError` caused by non-string `model_type` ([#2666](https://github.com/zhayujie/CowAgent/pull/2666))

## Platform Compatibility

* **Windows compatibility**: Fixed path handling, file encoding, and `os.getuid()` unavailability on Windows across multiple tool modules ([051ffd7](https://github.com/zhayujie/CowAgent/commit/051ffd78a372f71a967fd3259e37fe19131f83cf), [5264f7c](https://github.com/zhayujie/CowAgent/commit/5264f7ce18360ee4db5dcb4ebe67307977d40014))


# v2.0.2
Source: https://docs.cowagent.ai/releases/v2.0.2

CowAgent 2.0.2: a rebuilt web console with streaming chat, visible reasoning and tool calls, and online management of models, skills, memory, channels and tasks, plus multi-channel runs.

**Release Date**: 2026.02.27 | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.0.1...master)

## Highlights

### 🖥️ Web Console Upgrade

The Web Console has been fully upgraded with streaming conversation output, visual display of tool execution and reasoning processes, and online management of **models, skills, memory, channels, and Agent configuration**.

#### Chat Interface

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:

![](https://cdn.link-ai.tech/doc/20260227180120.png)

#### Model Management

Manage model configurations online without manually editing config files:

![](https://cdn.link-ai.tech/doc/20260227173811.png)

#### Skill Management

View and manage Agent skills (Skills) online:

![](https://cdn.link-ai.tech/doc/20260227173403.png)

#### Memory Management

View and manage Agent memory online:

![](https://cdn.link-ai.tech/doc/20260227173349.png)

#### Channel Management

Manage connected channels online with real-time connect/disconnect operations:

![](https://cdn.link-ai.tech/doc/20260227173331.png)

#### Scheduled Tasks

View and manage scheduled tasks online, including one-time tasks, fixed intervals, and Cron expressions:

![](https://cdn.link-ai.tech/doc/20260227173704.png)

#### Logs

View Agent runtime logs in real-time for monitoring and troubleshooting:

![](https://cdn.link-ai.tech/doc/20260227173514.png)

Related commits: [f1a1413](https://github.com/zhayujie/CowAgent/commit/f1a1413), [c0702c8](https://github.com/zhayujie/CowAgent/commit/c0702c8), [394853c](https://github.com/zhayujie/CowAgent/commit/394853c), [1c71c4e](https://github.com/zhayujie/CowAgent/commit/1c71c4e), [5e3eccb](https://github.com/zhayujie/CowAgent/commit/5e3eccb), [e1dc037](https://github.com/zhayujie/CowAgent/commit/e1dc037), [5edbf4c](https://github.com/zhayujie/CowAgent/commit/5edbf4c), [7d258b5](https://github.com/zhayujie/CowAgent/commit/7d258b5)

### 🔀 Multi-Channel Concurrency

Multiple channels (e.g., Feishu, DingTalk, WeCom, Web) can now run simultaneously, each in an independent thread without interference.

Configuration: Set multiple channels in `config.json` via `channel_type` separated by commas, or connect/disconnect channels in real-time from the Web Console's channel management page.

```json theme={null}
{
  "channel_type": "web,feishu,dingtalk"
}
```

Related commits: [4694594](https://github.com/zhayujie/CowAgent/commit/4694594), [7cce224](https://github.com/zhayujie/CowAgent/commit/7cce224), [7d258b5](https://github.com/zhayujie/CowAgent/commit/7d258b5), [c9adddb](https://github.com/zhayujie/CowAgent/commit/c9adddb)

### 💾 Session Persistence

Session history is now persisted to a local SQLite database. Conversation context is automatically restored after service restarts. Historical conversations in the Web Console are also restored.

Related commits: [29bfbec](https://github.com/zhayujie/CowAgent/commit/29bfbec), [9917552](https://github.com/zhayujie/CowAgent/commit/9917552), [925d728](https://github.com/zhayujie/CowAgent/commit/925d728)

## New Models

* **Gemini 3.1 Pro Preview**: Added `gemini-3.1-pro-preview` model support ([52d7cad](https://github.com/zhayujie/CowAgent/commit/52d7cad))
* **Claude 4.6 Sonnet**: Added `claude-4.6-sonnet` model support ([52d7cad](https://github.com/zhayujie/CowAgent/commit/52d7cad))
* **Qwen3.5 Plus**: Added `qwen3.5-plus` model support ([e59a289](https://github.com/zhayujie/CowAgent/commit/e59a289))
* **MiniMax M2.5**: Added `Minimax-M2.5` model support ([48db538](https://github.com/zhayujie/CowAgent/commit/48db538))
* **GLM-5**: Added `glm-5` model support ([48db538](https://github.com/zhayujie/CowAgent/commit/48db538))
* **Kimi K2.5**: Added `kimi-k2.5` model support ([48db538](https://github.com/zhayujie/CowAgent/commit/48db538))
* **Doubao 2.0 Code**: Added `doubao-2.0-code` coding-specialized model ([ab28ee5](https://github.com/zhayujie/CowAgent/commit/ab28ee5))
* **DashScope Models**: Added Alibaba Cloud DashScope model name support ([ce58f23](https://github.com/zhayujie/CowAgent/commit/ce58f23))

## Website & Documentation

* **Official Website**: [cowagent.ai](https://cowagent.ai/)
* **Documentation**: [docs.cowagent.ai](https://docs.cowagent.ai/)

## Bug Fixes

* **Gemini DingTalk image recognition**: Fixed Gemini unable to process image markers in DingTalk channel ([05a3304](https://github.com/zhayujie/CowAgent/commit/05a3304)) ([#2670](https://github.com/zhayujie/CowAgent/pull/2670)) Thanks [@SgtPepper114](https://github.com/SgtPepper114)
* **Startup script dependencies**: Fixed dependency installation issue in `run.sh` script ([b6fc9fa](https://github.com/zhayujie/CowAgent/commit/b6fc9fa))
* **Bare except cleanup**: Replaced `bare except` with `except Exception` for better exception handling ([adca89b](https://github.com/zhayujie/CowAgent/commit/adca89b)) ([#2674](https://github.com/zhayujie/CowAgent/pull/2674)) Thanks [@haosenwang1018](https://github.com/haosenwang1018)


# v2.0.3
Source: https://docs.cowagent.ai/releases/v2.0.3

CowAgent 2.0.3: new WeCom smart bot and QQ channels, file input and processing in the web console, Coding Plan support, plus a memory system upgrade, refactored tools and better Docker deployment.

## 🔌 New Channels

### WeCom Smart Bot

Added the WeCom Smart Bot (`wecom_bot`) channel with streaming card output, support for receiving and replying to text and image messages, and full configuration through the Web Console.

Documentation: [WeCom Smart Bot](https://docs.cowagent.ai/en/channels/wecom-bot).

Related commits: [d4480b6](https://github.com/zhayujie/CowAgent/commit/d4480b6), [a42f31f](https://github.com/zhayujie/CowAgent/commit/a42f31f), [4ecd4df](https://github.com/zhayujie/CowAgent/commit/4ecd4df), [8b45d6c](https://github.com/zhayujie/CowAgent/commit/8b45d6c)

### QQ Channel

Added the QQ official bot (`qq`) channel with support for text and image messages in both private chats and group chats.

Documentation: [QQ Bot](https://docs.cowagent.ai/en/channels/qq).

Related commits: [005a0e1](https://github.com/zhayujie/CowAgent/commit/005a0e1), [a4d54f5](https://github.com/zhayujie/CowAgent/commit/a4d54f5)

## 🖥️ Web Console File Input and Processing

The Web Console chat UI now supports file and image uploads — files can be sent directly to the agent for processing. The Read tool gains parsing support for Office documents (Word, Excel, PPT).

Related commits: [30c6d9b](https://github.com/zhayujie/CowAgent/commit/30c6d9b)

## 🤖 New Models

* **GPT-5.4 Series**: Added `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano` ([1623deb](https://github.com/zhayujie/CowAgent/commit/1623deb))
* **Gemini 3.1 Flash Lite Preview**: Added `gemini-3.1-flash-lite-preview` ([ba915f2](https://github.com/zhayujie/CowAgent/commit/ba915f2))

## 💰 Coding Plan Support

Added integration with provider Coding Plan (monthly programming subscription) tiers via the unified OpenAI-compatible path. Supported providers include Aliyun, MiniMax, GLM, Kimi, and Volcengine.

See [Coding Plan docs](https://docs.cowagent.ai/en/models/coding-plan) for detailed configuration.

## 🧠 Memory System Upgrade

Memory flush improvements:

* Use the LLM to summarize out-of-window conversations into compact daily memory entries
* Summarization runs asynchronously on a background thread, never blocking replies
* Smarter batch trimming policy reduces flush frequency
* Daily scheduled flush as a safety net for low-activity scenarios
* Fixed context-memory loss issues

Related commits: [022c13f](https://github.com/zhayujie/CowAgent/commit/022c13f), [c116235](https://github.com/zhayujie/CowAgent/commit/c116235)

## 🔧 Tool Refactoring

* **Image Vision**: Image recognition (Vision) is refactored from a Skill into a built-in Tool with a dedicated Vision Provider configuration, improving stability and maintainability ([a50fafa](https://github.com/zhayujie/CowAgent/commit/a50fafa), [3b8b562](https://github.com/zhayujie/CowAgent/commit/3b8b562))
* **Web Fetch**: Web fetch is refactored from a Skill into a built-in Tool with support for downloading and parsing remote documents (PDF, Word, Excel, PPT) ([ccb9030](https://github.com/zhayujie/CowAgent/commit/ccb9030), [fa61744](https://github.com/zhayujie/CowAgent/commit/fa61744))

## 🐳 Docker Deployment Improvements

* **Config Template Alignment**: `docker-compose.yml` env vars aligned with `config-template.json`, covering full model API key and Agent settings
* **Web Console Port Mapping**: Added `9899` port mapping so the Web Console is reachable in browser after Docker deployment
* **Hot Config Reload**: Bot API key and API base are now read at request time — changes from the Web Console take effect without restart
* **Workspace Persistence**: Added a `./cow` volume mount so agent workspace data (memories, persona, skills, etc.) persists across container rebuilds and upgrades

## ⚡ Performance Improvements

* **Faster Startup**: The Feishu channel imports its dependencies lazily, avoiding a 4–10s startup delay ([924dc79](https://github.com/zhayujie/CowAgent/commit/924dc79))
* **Channel Stability**: Improved channel connection stability and added env-var support for channel configuration ([f1c04bc](https://github.com/zhayujie/CowAgent/commit/f1c04bc), [46d97fd](https://github.com/zhayujie/CowAgent/commit/46d97fd))

## 🐛 Bug Fixes

* **bot\_type Propagation**: Fixed `bot_type` propagation under Agent mode ([#2691](https://github.com/zhayujie/CowAgent/pull/2691)) Thanks [@Weikjssss](https://github.com/Weikjssss)
* **bot\_type Resolution Priority**: Adjusted `bot_type` resolution priority under Agent mode ([#2692](https://github.com/zhayujie/CowAgent/pull/2692)) Thanks [@6vision](https://github.com/6vision)
* **Zhipu Config**: Fixed Zhipu `bot_type` naming, Web Console persistence, and regex escaping ([#2693](https://github.com/zhayujie/CowAgent/pull/2693)) Thanks [@6vision](https://github.com/6vision)
* **OpenAI-Compat Layer**: Unified error handling via the `openai_compat` layer ([#2688](https://github.com/zhayujie/CowAgent/pull/2688)) Thanks [@JasonOA888](https://github.com/JasonOA888)
* **OpenAI-Compat Migration**: Completed the `openai_compat` migration across all model bots ([#2689](https://github.com/zhayujie/CowAgent/pull/2689))
* **Gemini Tool Calling**: Fixed tool-call matching for Gemini ([eda82ba](https://github.com/zhayujie/CowAgent/commit/eda82ba))
* **Session Concurrency**: Fixed race conditions in concurrent session scenarios ([9879878](https://github.com/zhayujie/CowAgent/commit/9879878))
* **History Recovery**: Fixed incomplete history recovery — only user/assistant text messages are restored, tool calls are stripped ([b788a3d](https://github.com/zhayujie/CowAgent/commit/b788a3d), [a33ce97](https://github.com/zhayujie/CowAgent/commit/a33ce97))
* **Feishu Group Chat**: Removed the `bot_name` dependency for Feishu group chats ([b641bff](https://github.com/zhayujie/CowAgent/commit/b641bff))
* **Safari Compatibility**: Fixed an IME Enter key issue that mistakenly sent messages on Safari ([0687916](https://github.com/zhayujie/CowAgent/commit/0687916))
* **Windows Compatibility**: Fixed bash-style `$VAR` to `%VAR%` env-var conversion on Windows ([7c67513](https://github.com/zhayujie/CowAgent/commit/7c67513))
* **MiniMax Params**: Added a `max_tokens` cap for MiniMax models ([1767413](https://github.com/zhayujie/CowAgent/commit/1767413))
* **.gitignore**: Added Python directory ignore rules ([#2683](https://github.com/zhayujie/CowAgent/pull/2683)) Thanks [@pelioo](https://github.com/pelioo)
* **AGENT.md Proactive Evolution**: Improved the system prompt guidance around AGENT.md — instead of waiting for explicit user edits, the agent now proactively detects persona/style shifts in the conversation and updates AGENT.md accordingly

## 📦 Upgrade

Run `./run.sh update` for a one-click upgrade, or manually pull the latest code and restart. See [Upgrade Guide](https://docs.cowagent.ai/en/guide/upgrade) for details.

**Release Date**: 2026.03.18 | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.0.2...2.0.3)


# v2.0.4
Source: https://docs.cowagent.ai/releases/v2.0.4

CowAgent 2.0.4: a personal WeChat channel with QR login for text, image, file, video and voice messages, saved credentials and auto-reconnect; MiniMax-M2.7, GLM-5-Turbo and full Japanese docs.

## 🔌 Personal WeChat Channel

Added personal WeChat (`weixin`) channel — the most important update in this release. Simply scan a QR code to connect CowAgent to your personal WeChat account, with support for:

* **Messaging**: Send and receive text, image, file, and video messages; receive voice messages
* **QR Code Login**: QR code displayed in terminal, scan with WeChat to log in; auto-refresh on expiry
* **Credential Persistence**: Login credentials saved to `~/.weixin_cow_credentials.json` automatically, no re-scan needed on restart
* **Session Auto-Reconnect**: Automatically clears expired credentials and re-initiates QR code login
* **Web Console Integration**: Add WeChat channel from the Web Console with synchronized QR code login flow
* **Docker & Script Support**: Both `run.sh` and `docker-compose.yml` now support the WeChat channel

Documentation: [WeChat Channel](https://docs.cowagent.ai/channels/weixin).

Related commits: [ce89869](https://github.com/zhayujie/CowAgent/commit/ce89869), [a483ec0](https://github.com/zhayujie/CowAgent/commit/a483ec0), [c1421e0](https://github.com/zhayujie/CowAgent/commit/c1421e0)

## 🤖 New Models

* **MiniMax-M2.7**: Added MiniMax-M2.7 model support
* **GLM-5-Turbo**: Added Zhipu glm-5-turbo model support

Related commits: [9192f6f](https://github.com/zhayujie/CowAgent/commit/9192f6f)

## 🔧 Script Refactoring

* **run.sh Refactoring**: Extracted shared logic and eliminated duplication, reducing from 600+ lines to 177 lines ([49d8707](https://github.com/zhayujie/CowAgent/commit/49d8707))
* **Executable Permission**: Fixed `run.sh` file permission issue ([652156e](https://github.com/zhayujie/CowAgent/commit/652156e))

## ⚡ Improvements

* **Unified Request Headers**: Added identification headers to external requests across Agent services (Chat, Embedding, Vision, WebSearch, etc.) ([b4e711f](https://github.com/zhayujie/CowAgent/commit/b4e711f))
* **Auto-Repair Messages**: Enhanced message protocol fault tolerance with automatic repair of malformed message sequences ([b8b57e3](https://github.com/zhayujie/CowAgent/commit/b8b57e3))

## 🌍 Japanese Documentation

Added complete Japanese documentation covering getting started guide, channel integration, model configuration and other major sections. Thanks [@Ikko Ashimine](https://github.com/ikoamu)

Related commits: [5487c0b](https://github.com/zhayujie/CowAgent/commit/5487c0b)

## 🐛 Bug Fixes

* **WeCom Bot Compatibility**: Fixed compatibility with older `websocket-client` versions, added unified WebSocket compatibility layer ([bc7f627](https://github.com/zhayujie/CowAgent/commit/bc7f627))
* **run.sh PID**: Fixed process PID retrieval error in `run.sh` ([9febb07](https://github.com/zhayujie/CowAgent/commit/9febb07))
* **Feishu Encoding**: Fixed message and log encoding issue in Feishu channel ([7d0e156](https://github.com/zhayujie/CowAgent/commit/7d0e156))
* **Feishu Config**: Removed redundant `feishu_bot_name` dependency in `run.sh` ([1b5be1b](https://github.com/zhayujie/CowAgent/commit/1b5be1b))

## 📦 Upgrade

Run `./run.sh update` for a one-click upgrade, or manually pull the latest code and restart. See [Upgrade Guide](https://docs.cowagent.ai/guide/upgrade) for details.

**Release Date**: 2026.03.22 | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.0.3...master)


# v2.0.5
Source: https://docs.cowagent.ai/releases/v2.0.5

CowAgent 2.0.5: the Cow CLI for managing the service from a terminal or chat, the open-source Cow Skill Hub with one-command installs, a new browser tool, and QR-code creation of WeCom smart bots.

## 🖥️ Cow CLI

New CLI command system for managing CowAgent from terminal and chat:

* **Terminal commands**: Run `cow <command>` for `start`, `stop`, `restart`, `update`, `status`, `logs`, etc.
* **Chat commands**: Type `/<command>` in conversation for `/help`, `/status`, `/config`, `/skill`, `/context`, `/logs`, `/version`, etc.
* **Web console**: Type `/` in the input box to open a slash command menu, with arrow-key input history
* **Windows support**: New PowerShell script `scripts/run.ps1` with `cow` command support

Docs: [Command Overview](https://docs.cowagent.ai/en/cli)

![](https://cdn.link-ai.tech/doc/20260401114549.png)

## 🧩 Cow Skill Hub Open Source

[Cow Skill Hub](https://skills.cowagent.ai) is now open source and live — browse, search, install, and publish AI Agent skills:

* **One-command install**: `/skill install <name>` in chat or `cow skill install <name>` in terminal
* **Multi-source**: Install from Skill Hub, GitHub, ClawHub, LinkAI, and more
* **Search**: `/skill search` and `/skill list --remote` to browse the hub
* **Publish**: Submit your own skills at [skills.cowagent.ai/submit](https://skills.cowagent.ai/submit)
* **Mirror**: Mirror acceleration for faster downloads in China

Open source repo: [cow-skill-hub](https://github.com/zhayujie/cow-skill-hub)

Docs: [Skill Hub](https://docs.cowagent.ai/en/skills/hub), [Install Skills](https://docs.cowagent.ai/en/skills/install)

![](https://cdn.link-ai.tech/doc/20260401110103.png)

## 🌐 Browser Tool

New Browser tool — Agent can control a Chromium browser to visit and interact with web pages:

* **Navigation & interaction**: `navigate`, `click`, `fill`, `select`, `scroll`, `press`, etc.
* **Page snapshot**: Compact DOM snapshot for efficient page understanding, auto-snapshot after navigation
* **Screenshot**: Save page screenshots to workspace
* **JavaScript execution**: Run custom scripts on pages
* **CLI install**: `cow install-browser` for one-command setup
* **Docker support**: Browser install built into Docker image

Docs: [Browser Tool](https://docs.cowagent.ai/en/tools/browser)

![](https://cdn.link-ai.tech/doc/20260401115728.png)

## 🤖 WeCom Bot QR Code Setup

WeCom Bot channel now supports QR code scan for one-click bot creation:

* **QR scan in Web console**: Select "Scan QR" mode, scan with WeCom to auto-create and connect a bot — no manual configuration needed
* **Manual mode**: Still supports manual Bot ID and Secret input
* **Stream push optimization**: Throttled push to avoid WebSocket congestion

Docs: [WeCom Bot](https://docs.cowagent.ai/en/channels/wecom-bot)

PR: [#2735](https://github.com/zhayujie/CowAgent/pull/2735). Thanks [@WecomTeam](https://github.com/WecomTeam)

## 🐛 Other Improvements & Fixes

* **DeepSeek module**: Independent DeepSeek Bot with dedicated `deepseek_api_key` config ([#2719](https://github.com/zhayujie/CowAgent/pull/2719)). Thanks [@6vision](https://github.com/6vision)
* **Web console**: Slash command menu, input history, new model options, mobile optimization ([#2731](https://github.com/zhayujie/CowAgent/pull/2731)). Thanks [@zkjqd](https://github.com/zkjqd)
* **Context loss**: Fix context loss after trimming ([393f0c0](https://github.com/zhayujie/CowAgent/commit/393f0c0))
* **System prompt**: Fix system prompt not rebuilding on every turn ([13f5fde](https://github.com/zhayujie/CowAgent/commit/13f5fde))
* **Gemini**: Fix missing model attribute in GoogleGeminiBot ([#2716](https://github.com/zhayujie/CowAgent/pull/2716)). Thanks [@cowagent](https://github.com/cowagent)
* **WeChat channel**: Fix file send failures and filename loss ([6d9b7ba](https://github.com/zhayujie/CowAgent/commit/6d9b7ba), [45faa9c](https://github.com/zhayujie/CowAgent/commit/45faa9c))
* **Docker**: Fix volume permissions, reduce image size ([3eb8348](https://github.com/zhayujie/CowAgent/commit/3eb8348), [4470d4c](https://github.com/zhayujie/CowAgent/commit/4470d4c))
* **Security**: Fix Memory Content path traversal risk. Thanks [@August829](https://github.com/August829)

## 📦 Upgrade

Run `cow update` or `./run.sh update` to upgrade, or pull the latest code and restart. See [Upgrade Guide](https://docs.cowagent.ai/en/guide/upgrade).

**Release Date**: 2026.04.01 | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.0.4...master)


# v2.0.6
Source: https://docs.cowagent.ai/releases/v2.0.6

CowAgent 2.0.6 - Knowledge Base, Deep Dream Memory Distillation, Smart Context Compression, Web Console Multi-Session and More

## Project Renamed to CowAgent

The repository has been officially renamed from `chatgpt-on-wechat` to **CowAgent**, evolving into a full-featured AI Agent assistant.

* New URL: [github.com/zhayujie/CowAgent](https://github.com/zhayujie/CowAgent) — GitHub auto-redirects the old URL
* CLI commands, config files, and documentation links remain compatible — no extra steps needed

## 📚 Knowledge Base

New personal knowledge base system — Agent can autonomously build and maintain structured knowledge, retrieving it on demand during conversations:

* **Index-driven self-organizing structure**: Knowledge is stored in `knowledge/` directory, auto-organized by category, with each knowledge page as an independent Markdown file
* **Auto-write**: Send files, links, or other knowledge to the Agent, or it will automatically create/update knowledge pages when valuable information is identified in conversation
* **Hybrid retrieval**: Supports keyword full-text search and vector semantic retrieval, loading relevant knowledge on demand during conversations
* **Visualization**: File tree browsing and knowledge graph visualization, with in-document links for direct navigation
* **Command management**: `/knowledge` for stats, `/knowledge list` for directory structure, `/knowledge on|off` to toggle

![](https://cdn.link-ai.tech/doc/20260413105435.png)

Docs: [Knowledge Base](https://docs.cowagent.ai/en/knowledge)

## 🌙 Deep Dream Memory Distillation

A new memory consolidation mechanism that automatically distills scattered conversation memories into refined long-term memory daily:

* **Three-tier memory flow**: Conversation context (short-term) → Daily memory (mid-term) → MEMORY.md (long-term), forming a complete memory lifecycle
* **Auto-distillation**: Runs daily at 23:55, reads the day's daily memory and MEMORY.md, performs deduplication, merging, and pruning via LLM, outputting a refined MEMORY.md
* **Dream diary**: Each distillation generates a narrative-style dream diary recording discoveries and insights, stored in `memory/dreams/`
* **Manual trigger**: `/memory dream [N]` to manually trigger with configurable lookback days (default 3, max 30), with chat notification on completion
* **Web console**: Memory management page now includes a "Dream Diary" tab for browsing all dream diaries

Docs: [Deep Dream](https://docs.cowagent.ai/en/memory/deep-dream)

![](https://cdn.link-ai.tech/doc/20260414120158.png)

## 🧠 Smart Context Compression

When context exceeds limits, trimmed portions are summarized by LLM and asynchronously injected to maintain conversation continuity:

* **Async LLM summary**: Trimmed messages are summarized into key information by LLM, written to daily memory files and injected into retained context
* **Multi-model compatible**: Uses the primary model for summarization, compatible with Claude, OpenAI, MiniMax and other model message format requirements

Docs: [Short-term Memory](https://docs.cowagent.ai/en/memory/context)

## 💬 Web Console Upgrades

Multiple enhancements to the Web console:

* **Multi-session management**: Create and switch between independent sessions, sidebar session list with auto-generated and manually editable titles
* **Password protection**: Set a login password via `web_console_password` config option
* **Deep thinking**: Display model thinking process in Web console, controlled by `enable_thinking` config option
* **Scheduled push**: Scheduled task results can be pushed to Web console
* **Message copy**: One-click copy of raw Markdown content from AI reply bubbles
* **Language toggle**: Top language switch button now shows current language for more intuitive interaction

## 🤖 Model Updates

* **Vision optimization**: Image recognition tool prefers the primary model with automatic multi-provider fallback. Docs: [Vision Tool](https://docs.cowagent.ai/en/tools/vision)
* **MiniMax new model**: Added MiniMax-M2.7-highspeed model and MiniMax TTS voice synthesis support. Thanks @octo-patch
* **Qwen**: Added qwen3.6-plus model support

## 🐛 Other Improvements & Fixes

* **Memory prompts**: `MEMORY.md` injected into system prompt by default, with refined memory retrieval and write trigger conditions for enhanced proactive writing
* **System prompt**: Optimized system prompt style and tone guidance
* **Browser tool**: Enhanced implicit interactive element detection
* **File send**: Fixed common file types (tar.gz, zip, etc.) not being sent correctly. Thanks @6vision
* **macOS compatibility**: Fixed network pre-check timeout compatibility issue. Thanks @Moliang Zhou
* **Windows compatibility**: Fixed PowerShell compatibility, process updates, terminal encoding and other issues on Windows
* **Python 3.13+**: Fixed missing `legacy-cgi` dependency for Python 3.13+
* **WeChat channel**: Updated personal WeChat channel version

## 📦 Upgrade

Run `cow update` or `./run.sh update` to upgrade, or pull the latest code and restart. See [Upgrade Guide](https://docs.cowagent.ai/en/guide/upgrade).

**Release Date**: 2026.04.14 | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.0.5...master)


# v2.0.7
Source: https://docs.cowagent.ai/releases/v2.0.7

CowAgent 2.0.7 - Image Generation Skill (6-provider auto-routing), new models, knowledge base enhancements, Web Console improvements and bug fixes

## 🎨 Image Generation Skill

New built-in `image-generation` skill supporting text-to-image, image-to-image, and multi-image fusion across six major providers:

* **6-provider auto-routing**: OpenAI (GPT-Image-2) → Gemini (Nano Banana) → Seedream (Volcengine Ark) → Qwen (DashScope) → MiniMax → LinkAI — automatically selects from configured providers in fixed priority order, with automatic fallback on failure
* **Zero model selection**: Just configure an API key and it works — no need to manually specify a model. You can also name a specific model in conversation (e.g. "draw a cat with seedream")
* **Flexible control**: Supports `quality`, `size` (512/1K–4K), and `aspect_ratio` parameters, with each provider automatically mapping to its supported values
* **Image editing**: Pass existing images for editing, style transfer, or multi-image fusion (Seedream supports up to 14 reference images)
* **Skill-level config**: Pin a default model via `skills.image-generation.model` in `config.json`
* **Image lightbox**: All images in the Web console now support click-to-enlarge preview

Docs: [Image Generation Skill](https://docs.cowagent.ai/en/skills/image-generation)

## 🤖 New Model Support

* **Kimi K2.6**: Added `kimi-k2.6` model support
* **Claude Opus 4.7**: Added `claude-opus-4-7` model support
* **GLM 5.1**: Added `glm-5.1` model support
* **Kimi Coding Plan**: Support for Kimi Coding Plan mode
* **Custom model providers**: New custom model provider configuration for easier integration with additional providers

## 💬 Web Console Improvements

* **Smart auto-scroll**: Improved chat scroll behaviour — no longer forces scroll to bottom while the user is reading earlier messages
* **Reasoning content cap**: Deep thinking content capped at 4 KB to prevent frontend lag
* **Mobile optimisation**: Session sidebar hidden by default on mobile, with overlay dismiss support
* **Session title fix**: Fixed title auto-generation fallback logic and Bridge reset on config change
* **Image preview dedup**: Fixed duplicate image rendering within the same message

## 📚 Knowledge Base Enhancements

* **Nested directory support**: Knowledge base listing and display now support multi-level nested directories
* **Root-level file display**: Show `index.md`, `log.md` and other root-level files in the knowledge tree
* **Empty state stats fix**: Root-level files no longer interfere with empty-state detection

## 🌙 Dream Memory Improvements

* **Structured organisation**: Dream memory files are now auto-archived by date with a cleaner directory structure
* **Schedule jitter**: Daily dream trigger includes random jitter to avoid concurrency conflicts in cluster deployments

## 🛠 Skill System Improvements

* **Skill manager refresh**: `/skill` commands now automatically refresh the skill manager to keep state in sync
* **Installation sources**: Skill installation supports multiple source formats (URL, zip, local file, etc.) with automatic target directory handling

## 🐛 Other Fixes

* **Gemini fix**: Fixed Gemini tool calls not returning results
* **Agent retry**: Empty-response retries no longer drop `tool_calls`
* **Docker env sync**: Fixed environment variables not syncing after config update in Docker environments
* **Python 3.7 compat**: Deferred `Literal` import for Python 3.7 compatibility
* **Model switch notification**: Fixed bot\_type change notification not showing after model switch. Thanks @6vision
* **Config command**: `/config` now supports setting `enable_thinking`
* **Thinking display**: Deep thinking display disabled by default

## 📦 Upgrade

Run `cow update` or `./run.sh update` to upgrade, or pull the latest code and restart. See [Upgrade Guide](https://docs.cowagent.ai/en/guide/upgrade).

**Release Date**: 2026.04.22 | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.0.6...master)


# v2.0.8
Source: https://docs.cowagent.ai/releases/v2.0.8

CowAgent 2.0.8 - Major Feishu channel upgrade (voice, streaming typewriter, one-click QR app creation), DeepSeek V4 / ERNIE 5.0 support, scheduler memory enhancements and multiple fixes

## 🪶 Major Feishu Channel Upgrade

### 1. One-click QR-scan App Creation

No more manual app setup, permission scopes and event subscriptions in the Feishu Open Platform. When `feishu_app_id` is not configured, both the Web Console and CLI startup flow now show a QR-scan entry — scan with Feishu, authorize, and the bot is created and config is filled back automatically. Out-of-the-box.

Documentation: [Feishu Channel](https://docs.cowagent.ai/en/channels/feishu)

### 2. Voice Messages

Receive Feishu voice messages with automatic speech-to-text, and reply in voice via TTS. Recognition accuracy for short Chinese voice messages has been improved.

### 3. Streaming Typewriter Replies

Integrated with Feishu CardKit streaming cards, **enabled by default**, matching the Web Console experience:

* Multi-turn agent flows render intermediate updates and the final reply on separate cards
* Tuned for high-throughput models like DeepSeek to keep pace with the Web Console
* Falls back to plain text replies automatically when not supported, no manual config needed
* Requires Feishu client ≥ 7.20

The voice and streaming building blocks come from a community contribution #2791. Thanks [@yangluxin613](https://github.com/yangluxin613)

## 🤖 New Model Support

* **DeepSeek V4 series**: Added `deepseek-v4-pro` / `deepseek-v4-flash`, with `deepseek-v4-flash` set as the new default
* **Unified thinking-mode toggle**: DeepSeek V4, Qwen3 and other thinking-capable models now share the same `enable_thinking` switch
* **ERNIE first-class integration**: New `qianfan` provider supporting `ernie-5.0` (default recommendation), `ernie-x1.1`, `ernie-4.5-turbo-128k`, `ernie-4.5-turbo-32k`. Dedicated `qianfan_api_key` / `qianfan_api_base` settings keep OpenAI config clean; legacy `wenxin` / `wenxin-4` paths are fully preserved. #2790 Thanks [@jimmyzhuu](https://github.com/jimmyzhuu)

  Documentation: [ERNIE](https://docs.cowagent.ai/en/models/qianfan)

## 🌐 Translation Provider

* **Youdao translator**: Added a Youdao provider to the `translate/` module using the v3 SHA-256 signing scheme, with automatic ISO 639-1 language-code mapping (`zh`, `zh-TW`, etc.) #2797 Thanks [@Zmjjeff7](https://github.com/Zmjjeff7)

## 🛠 OpenAI Client Refactor

* **Drop SDK dependency**: The OpenAI bot is reimplemented on a native HTTP client — leaner startup, fewer dependency conflicts
* **Web Console hint**: API base inputs in the model config UI now include version-path placeholder hints

## ⏰ Scheduler Memory Enhancements

* **Follow-up on task results**: Scheduled task results are automatically injected into the receiver's session history — the next turn can ask follow-up questions without re-stating context. Thanks [@huangrichao2020](https://github.com/huangrichao2020)
* **No long-term memory pollution**: Scheduler-injected pairs are excluded from the daily memory flush so high-frequency tasks don't drown the memory store
* **Bounded scheduler context**: The scheduler's own session context is automatically capped, so long-running periodic tasks don't accumulate state and slow down replies

## 🔧 Tools and Safety

* **Vision model selection**: `tools.vision.model` config now actually takes effect, with automatic fallback when unconfigured #2792
* **Bash safety prompt**: The destructive-deletion confirm prompt is now scoped to paths outside the workspace — routine in-workspace operations are no longer interrupted

## 🐛 Other Fixes

* Fixed Deep Dream firing duplicate runs in multi-instance setups
* Fixed missing `reasoning_content` on some history turns in DeepSeek multi-turn conversations

## 📦 Upgrade

Source-code deployments can run `cow update` or `./run.sh update` for a one-click upgrade, or pull the latest code and restart manually. See [Upgrade Guide](https://docs.cowagent.ai/en/guide/upgrade) for details.

> ⚠️ One-click Feishu app creation requires `lark-oapi>=1.5.5`. `cow update` pulls it automatically; manual deployments must update dependencies.

**Release Date**: 2026.05.05 | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.0.7...2.0.8)


# v2.0.9
Source: https://docs.cowagent.ai/releases/v2.0.9

CowAgent 2.0.9 - Web Console model management, MCP protocol support, browser persistent login, new models and deployment hardening

## 🖥️ Model Management Console

The Web Console adds a new **Models** page that organizes everything by **provider × capability**, covering chat, image, voice, embedding and search models in one place:

* **Per-provider configuration**: Each provider's API Key / API Base is configured once at the top, and every capability below picks it up automatically — no more re-entering credentials
* **Image models**: Image understanding and image generation can each pick their own provider and model independently; falls back to the main model when unspecified
* **Voice models**: ASR (speech-to-text) and TTS (text-to-speech) can be configured independently, with new Qwen and Zhipu ASR/TTS models added
* **Embedding models**: Configurable embedding models (used for memory and knowledge-base retrieval), with new support for OpenAI, Tongyi, Doubao, Zhipu and others; run `/memory rebuild-index` after switching to rebuild the index online
* **Search capability**: Web search has been upgraded to support Bocha, Baidu, Zhipu and more providers — in auto mode the agent can synthesize results from multiple sources for deeper research

Documentation: [Models Overview](https://docs.cowagent.ai/en/models)

![20260522113305](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/web-console-models-config.png)

## 🧩 MCP Protocol Support

Adds support for **MCP (Model Context Protocol)**, expanding from a fixed built-in toolset to an open, pluggable tool ecosystem — any MCP-compatible service can be plugged in directly as an agent tool.

* Native JSON-RPC implementation, zero extra dependencies, supports both `stdio` and `sse` transports
* Compatible with the `mcpServers` configuration style used by Claude Desktop / Cursor, reads `~/cow/mcp.json` by default

Documentation: [MCP Tools](https://docs.cowagent.ai/en/tools/mcp). Thanks [@yangluxin613](https://github.com/yangluxin613) (#2801)

## 🌐 Browser Persistent Login

For sites that require login or have anti-bot protection, the browser tool can now persist a login session for long-term reuse, and supports attaching to your real Chrome browser to bypass fingerprint detection:

* **Persistent user profile (default)**: Uses `~/.cow/browser_profile` as the browser user data dir by default; once logged in, sessions are reused automatically on subsequent runs
* **CDP mode**: Configure `tools.browser.cdp_endpoint` to take over a real Chrome instance with full browser permissions

Documentation: [Browser Tool](https://docs.cowagent.ai/en/tools/browser). Thanks [@leafmove](https://github.com/leafmove) (#2809)

## 🤖 New Models and Improvements

* **New models**: `gpt-5.5`, `gemini-3.5-flash`, `qwen3.7-max`, `ernie-5.1`
* **Improvements**: DeepSeek V4 supports the `reasoning_effort` thinking-depth parameter; fixed thinking models like MiMo failing to connect via the OpenAI-compatible protocol

## 🔒 Deployment & Security

* **Bind to localhost by default**: The Web Console `web_host` now defaults to `127.0.0.1`; for server deployments, set it to `0.0.0.0` and configure a password manually. Thanks @August829, @yidaozhongqing, @YLChen-007, @icysun
* **Fully bundled frontend assets**: All third-party CSS / JS are now served locally — the console works offline and on intranet deployments. Thanks [@gitlayzer](https://github.com/gitlayzer) (#2816)

## 🛠 UX Improvements & Fixes

* **TTS rolls out to more channels**: Web Console, Personal WeChat, Feishu, DingTalk and WeCom Smart Bot all support voice replies — see the [Channels Overview](https://docs.cowagent.ai/en/channels)
* **Log panel enhancements**: Differentiated highlighting by log level, with level-based filtering. Thanks [@yangluxin613](https://github.com/yangluxin613) (#2807)
* **Auto-launch Web Console**: The Web Console now opens automatically on startup. Thanks [@yangluxin613](https://github.com/yangluxin613) (#2804)
* **Clean Ctrl+C exit**: No more long `KeyboardInterrupt` stack traces. Thanks [@yangluxin613](https://github.com/yangluxin613) (#2806)
* **Folder upload**: Web Console supports directory uploads, with path validation adapted for Windows. Thanks [@TryToMakeUsBetter](https://github.com/TryToMakeUsBetter) (#2814)
* Fixed scheduled tasks executing duplicates under certain conditions. Thanks [@CNXudiandian](https://github.com/CNXudiandian) (#2820)
* Fixed one-shot scheduled tasks with timezone not firing. Thanks @AethericSpace
* Fixed failed tool calls not being displayed after page refresh. Thanks [@a1094174619](https://github.com/a1094174619) (#2822)
* Fixed WeCom bot messages with illegal control characters failing to be delivered. Thanks [@Jacques-Zhao](https://github.com/Jacques-Zhao) (#2810)

## 📦 Upgrade

Source-code deployments can run `cow update` for a one-click upgrade, or pull the latest code and restart manually. See the [Upgrade Guide](https://docs.cowagent.ai/en/guide/upgrade) for details.

**Release Date**: 2026.05.22 | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.0.8...2.0.9)


# v2.1.0
Source: https://docs.cowagent.ai/releases/v2.1.0

CowAgent 2.1.0 - Internationalization, new Telegram / Discord / Slack / WeChat Customer Service channels, CLI interaction upgrades, MCP protocol enhancements and new models

🌐 [English](https://docs.cowagent.ai/releases/v2.1.0) | [中文](https://docs.cowagent.ai/zh/releases/v2.1.0)

## 📱 New Channels

This release adds several mainstream platform channels — configure and go, ready out of the box:

* **Telegram Bot**: Connect a Telegram bot with support for text and multimedia messages
* **Discord Bot**: Connect a Discord bot to chat in channels and direct messages
* **Slack Bot**: Connect a Slack bot and bring CowAgent into your team's workflow
* **WeChat Customer Service**: New WeChat Customer Service channel that receives images and files and automatically merges them into the next turn, bringing its multimedia context experience in line with other channels. Thanks [@6vision](https://github.com/6vision) (#2840)

Documentation: [Channels Overview](https://docs.cowagent.ai/en/channels)

## 🌍 Internationalization

CowAgent introduces an end-to-end internationalization framework built for developers worldwide, adapting automatically based on the system language:

* **End-to-end localization**: The install flow, CLI, logs and error messages, agent system prompts and more are all localized
* **Automatic language detection**: The default `auto` mode infers the language from the system locale, or you can set `cow_lang` explicitly in `config.json`. English and Chinese ship first, with more languages to follow
* **One-click switch in the console**: The Web Console supports switching the system language online, taking effect in real time

## ⌨️ CLI Interaction Upgrades

* **Streamlined one-line install**: The install script is simplified with an interactive setup — pick your language, and optionally choose a model and channel right from the prompts, getting you up and running in minutes
* **Streaming output**: The Terminal channel now renders the agent's reasoning, tool calls and streaming replies in real time
* **Fuzzy command matching**: Supports command abbreviations and near-miss typo suggestions, ships with built-in shortcuts, and lets you define custom aliases in the config file. Thanks [@lyteen](https://github.com/lyteen) (#2850)
* **Task cancellation**: In-flight agent runs can be interrupted on demand — the Web Console adds a stop button, and other channels can send `/cancel` to abort

Documentation: [CLI Guide](https://docs.cowagent.ai/en/cli/general)

## 🧩 MCP Protocol Enhancements

MCP tools now support the **Streamable HTTP** transport. On top of the existing `stdio` and `sse` options, this makes more MCP services compatible, letting you connect directly to remote tools that use the streamable HTTP protocol.

Documentation: [MCP Tools](https://docs.cowagent.ai/en/tools/mcp)

## 🤖 New Models & Improvements

* **New models**: `claude-opus-4-8`, Xiaomi `MiMo`
* **Improvements**: Fixed JSON parsing failures for tool-call arguments returned by some models (#2823)

Documentation: [Models Overview](https://docs.cowagent.ai/en/models)

## 🧠 Memory & Retrieval Improvements

* **Keyword search**: Fixed low hit rates for Chinese keyword search and empty results for pure-English keyword queries
* **Vector retrieval**: Optimized the vector retrieval flow and improved Python version compatibility

Thanks [@yangluxin613](https://github.com/yangluxin613) (#2832)

## 🛠 UX Improvements & Fixes

* **Confined file access**: Web file reads and sends are now limited to the user home directory and agent workspace by default to prevent arbitrary file reads; the scope can be widened via `web_file_serve_root`
* **More stable scheduled tasks**: Fixed scheduled-task pushes failing after a restart on the Personal WeChat channel
* **Browser tool**: Fixed non-HTTP schemes being dropped from navigation URLs; reduced browser memory usage
* **WeChat Official Account**: Passive replies now merge cached text segments, flush ready segments while a task is still running, and support sending local `file://` images. Thanks [@6vision](https://github.com/6vision) (#2848)
* **Faster WeCom bot responses**: Callbacks are now dispatched asynchronously to avoid message loss from WeCom's 5-second timeout
* **More robust login**: Fixed a login error when `web_password` was not a string

## 📦 Upgrade

Source-code deployments can run `cow update` for a one-click upgrade, or pull the latest code and restart manually. See the [Upgrade Guide](https://docs.cowagent.ai/en/guide/upgrade) for details.

**Release Date**: 2026.06.01 | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.0.9...2.1.0)


# v2.1.1
Source: https://docs.cowagent.ai/releases/v2.1.1

CowAgent 2.1.1 - Self-Evolution, Web Console message management and parallel sessions, cross-platform MCP enhancements, new models and improvements

🌐 [English](https://docs.cowagent.ai/releases/v2.1.1) | [中文](https://docs.cowagent.ai/zh/releases/v2.1.1)

## 🧬 Self-Evolution

CowAgent introduces **Self-Evolution**, letting the agent go beyond completing a single task and keep improving through everyday collaboration with you:

* **Automatic review after idle**: Once a conversation goes idle, the agent reviews it in the background to fix problems a skill exposed in use, create reusable new skills, follow up on unfinished tasks, and record important information into memory and the knowledge base
* **Silent by default, notify on demand**: It reports what it changed only when it actually made a change, and stays silent otherwise
* **Safe and reversible**: Every review is backed up beforehand and can be undone at any time. Built-in skills are protected, and all reads and writes stay within the workspace

Enabled by default for new installs. Existing users can turn it on with a single click in the Web Console under **Settings → Agent Config**.

![Self-Evolution conversation example](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/web-console-evolution-demo.png)

Documentation: [Self-Evolution](https://docs.cowagent.ai/memory/self-evolution)

## 💬 Web Console Upgrades

The Web Console chat experience gets several enhancements:

* **Message management**: Edit, delete, and regenerate both user and bot messages; code blocks now include language labels and a one-click copy button
* **Parallel sessions**: Run multiple sessions at the same time without interference, with live streaming automatically resumed when you switch back to a session
* **Refinements**: Drag and drop files anywhere in the chat view; automatically switch to a sibling session after deleting the active one

Thanks [@core-power](https://github.com/core-power) (#2865)

## 🧩 Cross-platform MCP Enhancements

* **Windows compatibility fix**: Fixed `stdio` communication failing on Windows, and made the server timeout configurable via `mcp.json`
* **Concurrent calls**: The `sse` and `streamable-http` transports now support concurrent calls across sessions for faster multi-tool responses

Thanks [@xliu123321](https://github.com/xliu123321) (#2859)

Documentation: [MCP Tools](https://docs.cowagent.ai/tools/mcp)

## 🤖 New Models & Improvements

* **MiniMax-M3**: Added and set as the default model, with the M2.7 series kept as an option. Thanks [@octo-patch](https://github.com/octo-patch) (#2855)
* **Qwen3.7-plus**: Added support for multi-modal conversations
* **Selectable ASR model**: The Web Console can now select and persist the ASR (speech recognition) model. Thanks [@nightwhite](https://github.com/nightwhite) (#2857)
* **Simplified install menu**: The one-line install script streamlines the model menu and adds the Xiaomi MiMo option

Documentation: [Models Overview](https://docs.cowagent.ai/models)

## 🛠 Improvements & Fixes

* **Python 3.13 support**: Fixed installation and dependency compatibility on Python 3.13
* **Internationalization**: The channel list is now ordered by the interface language; refined the automatic language fallback under `auto` mode
* **More reliable cancellation**: Fixed cases where a streaming reply could not be interrupted
* **CLI**: `cow status` now shows the current project path
* **Hardened deployment security**: The credential-file block is narrowed to `~/.cow/.env` so other directories are no longer affected (Thanks [@orbisai0security](https://github.com/orbisai0security) #2863); the WeChat Official Account now rejects webhook requests when `wechatmp_token` is empty
* **Group task board plugin**: Added the group task board plugin source. Thanks [@Wyh-max-star](https://github.com/Wyh-max-star) (#2853)

## 📦 Upgrade

Source-code deployments can run `cow update` for a one-click upgrade, or pull the latest code and restart manually. See the [Upgrade Guide](https://docs.cowagent.ai/guide/upgrade) for details.

**Release Date**: 2026.06.09 | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.1.0...2.1.1)


# v2.1.2
Source: https://docs.cowagent.ai/releases/v2.1.2

CowAgent 2.1.2 - Web Console management upgrades, Self-Evolution improvements, new models, WeCom smart-bot callback mode, and security hardening

🌐 [English](https://docs.cowagent.ai/releases/v2.1.2) | [中文](https://docs.cowagent.ai/zh/releases/v2.1.2)

## 💬 Web Console Improvements

This release adds several visual management capabilities to the Web Console, so more configuration can be done in the UI without editing files:

* **Scheduled task management**: View, edit, enable/disable, and delete any scheduled task directly in the console. The task list is sorted by enabled status first, then by next run time. Thanks @HnBigVolibear (#2892)
* **Knowledge base categories and document management**: The knowledge base can now be organized by category, with documents under each category managed in the UI. Thanks @yangziyu-hhh (#2893)
* **Multiple custom model providers**: Configure multiple OpenAI-compatible providers and switch the active one with a single click, fully compatible with existing configuration. Thanks @kirs-hi (#2877)
* **Session renaming**: Rename sessions manually to tell parallel tasks apart (#2897)
* **Bash streaming output**: Long-running Bash commands now stream their progress in real time. Thanks @yangziyu-hhh (#2879)

## 🧬 Self-Evolution Improvements

Building on the Self-Evolution introduced in the previous release, this version refines it further:

* **Lower trigger thresholds**: The default review thresholds are lowered, so everyday collaboration turns into improvements sooner
* **No concurrent reviews**: When a single turn runs long, the idle review no longer fires by mistake, avoiding interference with the active conversation
* **Better review summary**: Refined the summary prompt to keep summaries concise, raise their information density, and output them in the conversation language

Documentation: [Self-Evolution](https://docs.cowagent.ai/memory/self-evolution)

## 🤖 New Models

* **kimi-k2.7-code**: Added and set as the default Kimi model, with `kimi-k2.7-code-highspeed` also available
* **glm-5.2**: Added and set as the default GLM model

Documentation: [Models Overview](https://docs.cowagent.ai/models)

## 🏢 WeCom Smart-Bot Callback Mode

The WeCom smart-bot channel adds an **HTTP callback mode** alongside the existing long connection, so deployments that cannot keep a long connection open can still connect reliably:

* **Mode switching**: Switch between `websocket` (long connection) and `webhook` (callback) via `wecom_bot_mode`
* **Encrypted transport**: Callback mode fully supports URL verification, message decryption, and passive-reply encryption
* **Stability fixes**: Fixed reply interruption, premature stream termination, and temporary image file leaks

Thanks @6vision (#2896 #2869)

Documentation: [WeCom Smart Bot](https://docs.cowagent.ai/channels/wecom-bot)

## 🔒 Security Hardening

* **Vision tool SSRF protection**: Validates the target address before resolving an image URL, blocking requests to internal, loopback, and cloud server metadata endpoints. Thanks @kirs-hi (#2886)
* **Web fetch SSRF protection**: `web_fetch` validates the target address before fetching and re-validates every redirect hop, preventing redirects from bypassing the check to reach internal addresses. Thanks @christop (#2900)
* **Skill install path traversal protection**: Validates the path when installing a skill, preventing a malicious skill name from escaping the `skills/` directory through path traversal and writing to an unauthorized location. Thanks @kirs-hi (#2886)

## 🛠 Improvements & Fixes

* **CLI self-restart**: Added the self-restart command so the agent can restart its own process
* **Windows compatibility**: Persist the cow CLI directory to the user PATH; fixed `python -c` long commands exceeding the `cmd.exe` length limit; avoid building greenlet from source during install
* **Custom roles**: The role plugin supports customization via standalone prompt files under `roles/*.json`. Thanks @sufan721 (#2891)
* **Stability fixes**: Fixed a KeyError on `/cancel` and an infinite loop in image compression (Thanks @kirs-hi #2888)
* **Install improvements**: Updated the startup script and default config; fixed ASR/TTS defaults, the self-evolution flag, and install hangs
* **Vision tool stability**: Increased the vision tool timeout and max\_tokens
* **Memory distillation**: Removed the output length cap in deep-dream distillation to avoid truncating a large `MEMORY.md`

## 📦 Upgrade

Source-code deployments can run `cow update` for a one-click upgrade, or pull the latest code and restart manually. See the [Upgrade Guide](https://docs.cowagent.ai/guide/upgrade) for details.

**Release Date**: 2026.06.18 | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.1.1...2.1.2)


# v2.1.3
Source: https://docs.cowagent.ai/releases/v2.1.3

CowAgent 2.1.3: the desktop app for macOS and Windows, better knowledge base document management, on-demand MCP tool retrieval, Traditional Chinese, new models, and security and usability fixes.

🌐 [English](https://docs.cowagent.ai/releases/v2.1.3) | [中文](https://docs.cowagent.ai/zh/releases/v2.1.3)

## 🖥 Desktop Client

Introducing the **CowAgent Desktop client** for **macOS and Windows** — your local super AI assistant, truly ready to use out of the box.

Download: [CowAgent Desktop](https://cowagent.ai/download/)

![CowAgent Desktop client](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/desktop-chat-demo-en.png)

Highlights:

* **Out of the box**: the full Agent runtime is bundled — launch right after install, no need to set up Python or other dependencies
* **Full chat experience**: streaming replies, session management, tool-call step display, Markdown rendering, plus sending and previewing images / videos / files
* **Visual management**: configuration, models, knowledge base, scheduled tasks, skills, and memory pages mirror the Web console, all manageable in the native UI
* **Channel onboarding**: connect messaging channels by scanning a QR code right inside the app
* **Auto update**: automatic version checks and one-click updates, with download speed optimized across regions
* **Native experience**: first-run onboarding, follows the system language, and platform-adaptive window interactions

Docs: [Desktop Client](https://docs.cowagent.ai/guide/desktop)

## 📚 Knowledge Base

* **Create & import documents**: create new documents or import external ones directly from the UI
* **Automatic index maintenance**: the knowledge base index is rebuilt automatically from the actual directory tree, preventing index drift or lost documents
* **Vectorization fix**: the index now reuses the unified embedding provider, ensuring real semantic vectors instead of falling back to keyword search

Thanks @yangziyu-hhh

Docs: [Knowledge Base](https://docs.cowagent.ai/memory/knowledge)

## 🔌 On-demand MCP Tool Retrieval

To address context bloat when many MCP tools are connected, we added **on-demand tool retrieval**: relevant MCP tools are loaded on demand via RAG vector search based on the current task, reducing the context taken up by irrelevant tools. Thanks @fengyl07

Docs: [MCP Tools](https://docs.cowagent.ai/tools/mcp)

## 🌏 Traditional Chinese Support

The Web console, logs, and documentation now support **Traditional Chinese (zh-Hant)**; the interface language can follow the system or be switched manually. Thanks @anomixer (#2935)

## 🤖 New Models

* Added support for **claude-sonnet-5** and **claude-fable-5**
* Added support for **doubao-seed-2-1-pro** and **doubao-seed-2-1-turbo**

Docs: [Models](https://docs.cowagent.ai/models)

## 🔒 Security Hardening

* **Sensitive file read protection**: hardened access to credential and other sensitive files to prevent bypass reads. Thanks @fengyl07 (#2913)
* **Browser access protection**: blocks browser requests targeting internal network and cloud server internal endpoints, reducing the risk of being tricked into reaching internal services. Thanks @Jiangrong-W
* **Safer config parsing**: config content is parsed in a safer way to avoid potential code execution risks. Thanks @shunfeng8421

## 🛠 Improvements & Fixes

* **Custom provider support**: embedding and vision models can now use custom providers; also fixed a memory query issue on Windows. Thanks @HnBigVolibear
* **More reliable file editing**: better preserves original indentation, and fuzzy matching no longer touches unrelated content. Thanks @weijun-xia (#2942)
* **Command output encoding fix**: fixed garbled Chinese characters when a command produces large output. Thanks @weijun-xia (#2941)
* **Azure OpenAI fixes**: fixed streaming output and related configuration issues for Azure OpenAI. Thanks @Tunnello
* **WeCom Smart Bot**: added channel docs for the webhook (callback) mode. Thanks @6vision
* **Deep Dream toggle**: added a dedicated `deep_dream_enabled` switch to enable or disable Deep Dream distillation independently.
* **Stability**: improved connection recycling in the Web service and fixed several Self-Evolution issues (#2924, #2904)

## 📦 How to Upgrade

* **Desktop client**: get the latest version from the [download page](https://cowagent.ai/download/).
* **Source deployment**: run `cow update` for a one-click upgrade, or pull the latest code and restart. See the [upgrade guide](https://docs.cowagent.ai/guide/upgrade).

**Release date**: 2026.07.08 | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.1.2...2.1.3)


# v2.1.4
Source: https://docs.cowagent.ai/releases/v2.1.4

CowAgent 2.1.4: Desktop experience improvements, MCP OAuth authorization, Feishu channel enhancements, plus scheduler, data backup, and new models

🌐 [English](https://docs.cowagent.ai/releases/v2.1.4) | [中文](https://docs.cowagent.ai/zh/releases/v2.1.4)

## 🖥 Desktop Client

Following the desktop client launched in the previous release, this version further improves browser capabilities, system compatibility, and overall experience:

* **Browser tool support**: the client bundles browser capabilities and prefers reusing the system's installed Chrome / Edge, with optimized browser startup and access performance.
* **UI polish**: refined visuals and interactions for the chat view, message bubbles, tool-call steps, and channel pages.
* **Windows code signing**: Windows installers are now code-signed, reducing security warnings during installation.
* **Windows 7/8 support**: added client support for legacy systems such as Windows 7/8, covering more environments.
* **Knowledge base link fix**: fixed in-document links in the desktop knowledge base that failed to navigate.
* **Password login**: the desktop client supports setting a login password, and fixes an issue where the window failed to load after a password was set.

Download: [CowAgent Desktop](https://cowagent.ai/download/)

Docs: [Desktop Client](https://docs.cowagent.ai/guide/desktop)

## 🔌 MCP Remote Server OAuth Authorization

Remote MCP servers now support **OAuth authorization**. When connecting to third-party MCP servers that require login, authentication can be completed via the standard OAuth flow — no more manually configuring and maintaining tokens.

Docs: [MCP Tools](https://docs.cowagent.ai/tools/mcp)

## ⏰ Scheduled Tasks

* **Silent mode**: create silently-running scheduled tasks that execute in the background without pushing messages — ideal for undisturbed scenarios like data organization or periodic archiving. (#2954)
* **Manual run**: manually trigger an existing task to run immediately from the console, without waiting for the next schedule. (#2958)
* **Preserve config on edit**: fixed an issue where editing a task in the Web console could drop hidden fields such as the mode type. (#2959)
* **Cross-channel task command**: added the `/tasks` management command, compatible across channels. (#2965)

Thanks @AaronZ345

Docs: [Scheduled Tasks](https://docs.cowagent.ai/tools/scheduler)

## 💬 Feishu Channel Improvements

The Feishu channel gains a series of message-display and interaction enhancements for a better experience.

* **Streaming card polish**: streaming cards add collapsible panels showing the thinking process, tool calls, and execution time. (#2963)
* **Markdown formatting**: for non-streaming replies and scheduled pushes, messages containing Markdown are rendered as cards for clearer display. (#2962)
* **Scheduler cards**: the `/tasks` command is presented as cards, with the ability to enable or disable tasks right from the card. (#2961)
* **Quoted message context**: when a user quotes a message, the quoted content is automatically added to the context sent to the Agent. (#2966)
* **Remote image rendering**: remote image links can now be rendered inside Feishu cards. (#2967)
* **Cancel on message recall**: recalling a Feishu message automatically cancels its corresponding running or queued task. (#2978)

Thanks @AaronZ345

Docs: [Feishu](https://docs.cowagent.ai/channels/feishu)

## 💾 Data Backup & Restore

Added the `cow backup` and `cow restore` commands to export and restore local data — configuration, knowledge base, memory, and more — with one command, making migration and backup easy. Thanks @AaronZ345 (#2957)

Docs: [Data Backup](https://docs.cowagent.ai/cli/backup)

## 🤖 New Models

* Added support for **claude-opus-5**, now the default recommended Claude model
* Added support for **kimi-k3**
* Added support for **gpt-5.6-luna**, **gpt-5.6-terra**, and **gpt-5.6-sol**

Docs: [Models](https://docs.cowagent.ai/models)

## 🛠 Improvements & Fixes

* **Active-task steering**: added the `/steer` command to inject new instructions during task execution, guiding or redirecting the running task on the fly. Thanks @AaronZ345 (#2977)
* **File editing**: fixed an issue where fuzzy matching could locate the wrong position when editing files. Thanks @weijun-xia (#2945)

## 📦 How to Upgrade

* **Source deployment**: run `cow update` for a one-click upgrade, or pull the latest code and restart. See the [upgrade guide](https://docs.cowagent.ai/guide/upgrade).
* **Desktop client**: check for updates and update with one click inside the client, or get the latest version from the [download page](https://cowagent.ai/download/).

**Release date**: 2026.07.20 | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.1.3...2.1.4)


# v2.1.5
Source: https://docs.cowagent.ai/releases/v2.1.5

CowAgent 2.1.5: workspace with file preview, a systematic pass over the core tools, context management improvements, and one-click prompt optimization

🌐 [English](https://docs.cowagent.ai/releases/v2.1.5) | [中文](https://docs.cowagent.ai/zh/releases/v2.1.5)

## 🗂 Workspace & File Preview

The chat page gains a visual view of the workspace: documents, web pages, and images the Agent produces can be previewed in place. Both the Web console and the desktop client support it.

* **Workspace browsing**: browse the files under the workspace directory from the panel, with search and download to local.
* **File preview**: HTML pages, documents, and images open directly in the side panel, and file paths in a reply are rendered as clickable cards.
* **File references**: drag a workspace file into the conversation, or use `@` in the input box to reference files and directories and pull them into the context.

![](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/workspace-file-preview-demo-en.png)

## 🔧 Core Tool Improvements

A systematic pass over file search, read, write, edit, and shell tools, strengthening the Agent's file handling and coding abilities.

* **New file search tool**: `search_files` searches the workspace by content or by file name, backed by ripgrep by default — markedly faster on large directories. Thanks @Maaayhan (#2982)
* **Line-numbered read output**: `read` output now always carries line numbers, making it easier to locate and cite specific lines.
* **More accurate edits**: `edit` no longer rewrites the surrounding indentation on a fuzzy match, and no longer lands on the wrong occurrence when the text repeats; replace-all was added; a file modified outside the Agent is now flagged.
* **Write-time syntax checks**: `write` / `edit` validate the format of structured files before writing, and parse source files to report syntax errors back to the Agent.
* **Background commands**: `bash` can run a command in the background, for long-running work such as starting a service or following logs; the default timeout for foreground commands was raised.
* **Cancellation takes effect immediately**: clicking stop or running `/cancel` terminates the command that is currently running.

Docs: [File Search](https://docs.cowagent.ai/tools/search-files)

## 🧠 Context Management

* **Context compaction**: the new `/compact` command summarizes and compacts the conversation context on demand, effectively cutting token usage.
* **Unified commands**: `/clear` now uniformly clears the current session's context, with `/context clear` kept as an alias.
* **Larger default window**: the default context limit was raised, so long conversations start trimming later.

Docs: [Context Management](https://docs.cowagent.ai/memory/context)

## 🖥 Desktop Client

* **Native on Mac**: fixed the macOS arm64 installer carrying an x64 backend, substantially speeding up the main process and the browser tool on Apple Silicon machines.
* **Feishu channel added**: fixed the Feishu channel missing from the client. The Feishu SDK is now a trimmed dependency (about 1 MB) downloaded on demand the first time the channel is enabled. Thanks @EvanProgramming (#2988)
* **Update prompt**: the update dialog for a given version only opens automatically once.
* **Bundled search backend**: the Windows client ships with ripgrep, so file search works out of the box.

Download: [CowAgent Desktop](https://cowagent.ai/download/)

Docs: [Desktop Client](https://docs.cowagent.ai/guide/desktop)

## ✨ One-Click Prompt Optimization

The Web input box can now expand what you typed into a more complete and explicit instruction, and the optimization rules support custom templates. Thanks @sufan721 (#2989)

## 🔒 Security Hardening

* **MCP and file-write hardening**: fixed an attack chain exploitable through prompt injection — malicious content could lead the Agent into rewriting the MCP config, and from there run arbitrary commands and steal keys. Thanks @Correctover (#2968)
* **Credential file protection**: fixed the `edit` tool bypassing credential protection to read and write `~/.cow/.env`.

## 🛠 Improvements & Fixes

* **bash config honored**: fixed `tools.bash.timeout` and `tools.bash.safety_mode` in `config.json` being ignored. Thanks @EvanProgramming (#2986)
* **Memory workspace path**: fixed the workspace path being resolved incorrectly in the global memory config. Thanks @Maaayhan (#2992)
* **Conversation history protection**: fixed memory index self-repair that could clear conversation history along with it.
* **Session deletion**: fixed a reply still in flight writing a deleted session back into the list.
* **Browser launch**: fixed launching a duplicate instance when the browser was already running.
* **Accurate tool results**: fixed misleading failures from several tools — exit codes from `grep` / `find` judged wrong, browser scripts falsely reported as syntax errors, relative image paths failing to resolve — reducing pointless retries.

## 📦 How to Upgrade

* **Source deployment**: run `cow update` for a one-click upgrade, or pull the latest code and restart. See the [upgrade guide](https://docs.cowagent.ai/guide/upgrade).
* **Desktop client**: check for updates and update with one click inside the client, or get the latest version from the [download page](https://cowagent.ai/download/).

**Release date**: 2026.07.28 | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.1.4...2.1.5)


# v2.1.6
Source: https://docs.cowagent.ai/releases/v2.1.6

CowAgent 2.1.6: sub agents for parallel task delegation, native reasoning-effort settings, a pluggable memory vector backend, and desktop client improvements

🌐 [English](https://docs.cowagent.ai/releases/v2.1.6) | [中文](https://docs.cowagent.ai/zh/releases/v2.1.6)

## 🤝 Sub Agents

The main Agent can hand independent tasks off to sub agents and run them in parallel — improving results, lowering context cost, and speeding up work that can happen at the same time:

* **Isolated context**: the intermediate work stays out of the main conversation, saving tokens and keeping the model focused.
* **Parallel execution**: several sub agents can run at once, and the main Agent gathers their results when they finish. Both the Web console and the desktop client show the full run.
* **Customizable**: two built-in types, `general-purpose` and `explore`, plus your own — drop a `.md` file under the workspace `subagents/` directory to define a type with its own system prompt and tool set.
* **On by default**: no setup needed; the main Agent decides when to delegate. Toggle it under Config → Agent, and tune nesting depth, concurrency, and timeout in `config.json`.

![](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/cow-subagent-demo.png)

Docs: [Sub Agents](https://docs.cowagent.ai/multi-agent/subagent)

## 🖥 Desktop Client

* **Scheduled-task notifications**: the client receives scheduled and pushed messages and raises OS notifications.
* **Update panel**: the update dialog now links to the release notes, so you can see what changed.
* **Custom provider models**: custom providers get a free-form model input.
* **Startup fixes**: fixed the backend startup hanging, added automatic port retry, and surfaced the real error on failure.

Download: [CowAgent Desktop](https://cowagent.ai/download/)

Docs: [Desktop Client](https://docs.cowagent.ai/guide/desktop)

## 🧠 Reasoning Effort & Thinking

* **Reasoning-effort settings**: native `reasoning_effort` configuration across Claude, Qwen, Kimi, and more, remembered per model. Thanks @tshicheng (#3007, #3009)
* **Claude thinking**: Claude's thinking process can now be shown in the Web console and the desktop client, making its reasoning easier to follow.

## 🔒 Security Hardening

* **Guarded self-evolution writes**: unattended writes now get validation and rollback, writes are serialized per workspace, and the protected write paths were narrowed so task files in the workspace are no longer touched by mistake. Thanks @lisheng-SenLee (#3011, #3016)
* **Skill path validation**: skill install validates each file path more thoroughly. Thanks @LHMQ878 (#3006)
* **Dependency upgrades**: the desktop client bumps js-yaml and linkify-it, fixing two exploitable denial-of-service issues. Thanks @anupamme

## 💾 Memory & Retrieval

* **Pluggable vector backend**: memory's vector storage and retrieval sit behind a single interface, with SQLite as the default, making it easy to plug in an external vector store later. Thanks @AaronZ345 (#3021)
* **Index repair**: fixed trigram FTS5 index corruption on chunk updates; a corrupted shared database now self-repairs.

Docs: [Memory](https://docs.cowagent.ai/memory)

## 🛠 Improvements & Fixes

* **Custom image providers**: image generation supports custom providers, with live credential refresh and cleanup on deletion. Thanks @AaronZ345 (#3022)
* **Reliable SSE reconnection**: the Web SSE lifecycle is now complete, reconnecting with event replay after a network drop and cutting message loss on long tasks. Thanks @lisheng-SenLee (#3014)
* **Reasoning display**: fixed several issues with tool cards, file links, and image display in reasoning mode.
* **Rate-limit backoff**: capped the backoff when the LLM is rate-limited, avoiding long waits. Thanks @tim-korso (#3018)
* **Quiet scheduled tasks**: a scheduled task with nothing to report no longer sends an empty message. Thanks @kowkowhuang (#3001)
* **Service stop time**: fixed an end-of-day time (such as 23:59) being rejected as a service stop time. Thanks @Iams4kura (#3020)
* **Domain scheme**: fixed an explicit http/https scheme in `WEBSITES_DOMAIN` not being honored. Thanks @6vision (#3015)
* **WeChat media**: fixed personal WeChat failing to send or receive images, files, and other media over unreliable networks, and refined image recognition.
* **Feishu channel**: fixed new messages being dropped when their delivery lagged.
* **Telegram**: fixed Markdown rendering and a long summary dropping attached files.
* **File replies**: fixed a file reply dropping the accompanying text and other attachments, and a tool's file link stranding the client's tool card.
* **Docker**: installs tzdata so the `TZ` environment variable takes effect.

## 📦 How to Upgrade

* **Source deployment**: run `cow update` for a one-click upgrade, or pull the latest code and restart. See the [upgrade guide](https://docs.cowagent.ai/guide/upgrade).
* **Desktop client**: check for updates and update with one click inside the client, or get the latest version from the [download page](https://cowagent.ai/download/).

**Release date**: 2026.08.12 | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.1.5...2.1.6)


# v2.1.7
Source: https://docs.cowagent.ai/releases/v2.1.7

CowAgent 2.1.7: multiple workspaces isolated per session, session-level permission modes, task notifications and desktop improvements, and new models

🌐 [English](https://docs.cowagent.ai/releases/v2.1.7) | [中文](https://docs.cowagent.ai/zh/releases/v2.1.7)

## 🗂 Multiple Workspaces

The Agent is no longer tied to a single directory — you can set up several project workspaces and give each session its own. Available in both the Web console and the desktop client:

* **Multiple workspaces**: create or open any directory as a project workspace; the documents, web pages, and code the Agent produces are created and managed there.
* **Per-session workspace**: each session is bound to its own project workspace, so tasks running side by side stay out of each other's way.
* **Per-session model**: switch the model for a single session; new sessions start from the global default.
* **Grouped sessions**: the session list is grouped by workspace, with pinning, reordering, renaming, and deleting.
* **Shared system resources**: memory, skills, and the knowledge base still live in the system workspace (`~/cow` by default).

![](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/web-console-workspace-project-demo.png)

Docs: [Workspace](https://docs.cowagent.ai/intro/architecture#workspace)

## 🔐 Permission Modes

Sessions now carry their own permission mode, which works together with workspaces to control how far the Agent can reach:

* **Three levels**: read-only, workspace-write, and full-access, set independently for each session.
* **Default mode**: pick a default permission mode, and new sessions start with it.
* **Actionable denials**: when a tool call is blocked, the hint is clickable so you can adjust the permission on the spot.

![](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/web-console-access-mode.png)

## 🖥 Desktop Client

* **Voice input**: a voice button in the chat input transcribes what you say straight into the box; speech recognition and synthesis also work with custom providers and models. Thanks @chimyves (#3052, #3050)
* **Drafts kept**: leaving the chat page and coming back no longer loses unsent text and attachments. Thanks @chimyves (#3040)
* **Launch at login**: a new toggle in system settings, off by default.
* **Startup diagnostics**: when the backend fails to start, the client reports what actually went wrong instead of a generic error.
* **Log download**: the run-log page can download the log file, and local uploads gained retries and clearer errors.

Download: [CowAgent Desktop](https://cowagent.ai/download/)

Docs: [Desktop Client](https://docs.cowagent.ai/guide/desktop)

## 🔔 Task Notifications

The Web console and the desktop client both raise a notification (with a sound) when an Agent run finishes or fails, so you can walk away from a long task:

* **Both clients**: OS notifications on the desktop, browser notifications on the Web — only while the window isn't focused. Clicking one takes you back to the session.
* **Unread badge**: the Web tab shows an unread count while it's hidden, cleared once you switch back.
* **Separate toggles**: notifications and the sound are two independent switches, both on by default. Cancelling a task yourself no longer triggers a failure notification.

Thanks @chimyves (#3056, #3055)

## 🤖 Model Updates

* **New models**: `glm-5.3`, `qwen3.8-max`, `gemini-3.7-flash`, and `gemini-3.6-flash`, each set as its provider's default.
* **Merged config page**: the Web console folds the Models page into Config, split into a Basic and a Models tab, so there's less jumping around.
* **Call fixes**: fixed GLM-5.3's forced thinking, plus routing and base-URL handling for some DashScope models; custom models now show up in the session model picker.

## 🛠 Improvements & Fixes

* **Image display**: fixed local-path images and relative-path images inside knowledge docs not rendering; on the desktop, clicking an image in a chat or a document zooms it in place. Thanks @chimyves (#3046)
* **Windows drives**: fixed the folder picker not listing drives on Windows. Thanks @CNXudiandian (#3048)
* **Windows shell guidance**: better recovery guidance when a shell command fails on Windows. Thanks @dajiaohuang (#3065)
* **Cleaner IM replies**: Agent replies on IM channels no longer carry thinking content. Thanks @LHMQ878 (#3044)
* **Scheduled tasks**: fixed a task that failed across midnight never getting back on schedule (Thanks @chimyves #3054), and scheduled tasks being acknowledged instead of run.
* **Faster first message**: streamlined memory system initialization so it no longer blocks a session's first message, noticeably cutting the wait before the initial reply.
* **Context trimming**: fixed the AI reply not being saved when the context was trimmed.
* **Feishu channel**: the streaming card now accumulates text across turns.
* **Docker**: `config.json` survives container upgrades through the `COW_DATA_DIR` mount.

## 📦 How to Upgrade

* **Source deployment**: run `cow update` for a one-click upgrade, or pull the latest code and restart. See the [upgrade guide](https://docs.cowagent.ai/guide/upgrade).
* **Desktop client**: check for updates and update with one click inside the client, or get the latest version from the [download page](https://cowagent.ai/download/).

**Release date**: 2026.08.20 | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.1.6...2.1.7)


# v2.1.8
Source: https://docs.cowagent.ai/releases/v2.1.8

CowAgent 2.1.8: multi-Agent teams, manual scheduled tasks, context-usage visualization, new models and search providers, and in-place workspace file editing

🌐 [English](https://docs.cowagent.ai/releases/v2.1.8) | [中文](https://docs.cowagent.ai/zh/releases/v2.1.8)

## 🤝 Multi-Agent Teams

CowAgent is now a **multi-Agent framework**. You can create multiple Agents, each with its own role, to form a team and collaborate on complex tasks within a single session. Supported on the Web console, the desktop client, and channel integrations:

* **Team management**: create and maintain Agents, configure name, responsibilities, default model, skills, and knowledge, and copy the setup from an existing Agent.
* **Resource isolation**: each Agent has its own workspace, memory, and sessions; the knowledge base and skills can be shared or kept independent.

![Agent team](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/team-overview.png)

* **Group collaboration**: add multiple Agents to one session and use `@` to direct a message to a specific member, with each Agent using its own configured model.
* **Task delegation**: a group chat has a lead Agent that can hand a task off to the member best suited for it based on their responsibilities, with support for multi-level delegation and configurable scope, depth, and timeout.

![Agent-team-group](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/agent-group-chat-demo.png)

* **Multiple channel instances**: an IM channel of the same type can now run multiple instances, each bound to a single Agent or an Agent team. Supported on WeChat, WeCom smart bots, Feishu, DingTalk, QQ, Telegram, Slack, Discord, and more.

![Agent-team-channel](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/channel-config.png)

Thanks @AaronZ345 (#2975, #2973), @zkjqd (#3096), @cowagent (#3118)

Docs: [Agent Teams](https://docs.cowagent.ai/multi-agent/team)

## ⏰ Scheduled Task Upgrades

Scheduled tasks can now be created and managed from the console, with channel recipients and execution records added:

* **Manual task creation**: create, edit, and run tasks directly on the tasks page, and select the channel instance and recipient.
* **Channel recipient management**: maintain trusted recipients per channel instance, so a task can be delivered to a designated recipient rather than only the channel where it was created. Thanks @dajiaohuang (#3043)
* **Execution records**: a new execution-records page lets you review the history list and the details of each run. Thanks @mengluo04 (#3107)
* **Concurrent-update fix**: fixed tasks being lost on concurrent updates (Thanks @Whxuan0701 #3062).

![](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/scheduler-create.png)

## 📊 Context-Usage Visualization

Context consumption is now visible and controllable, making token cost easier to manage:

* **Context-usage view**: a ring view replaces the previous clear-context button and shows a full breakdown of what makes up the context.
* **Context actions**: below the ring view you can trigger smart compaction, clear the context, or set the maximum context size.
* **Context calculation**: the usage breakdown is derived automatically from the model's reported usage, with `agent_max_context_tokens` available as a user-configurable cost cap.

Thanks @chimyves (#3087), @sufan721 (#3079)

![](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/context-pie.png)

## 🤖 Model Capabilities

* **New models**: added `deepseek-flash` (DeepSeek V4.1 Flash), `gpt-6-astra`, `claude-fable-5-1`, `qwen3.8-flash`, `glm-5.3-flash`, `gemini-3.8-flash`, and the vision model `deepseek-v4-flash-vision-exp` (Thanks @a1094174619 #3094).
* **Model fallback**: configure a fallback model under Model Config > Primary Model, which takes over automatically when the primary model fails, preventing interruptions from a single provider outage. Thanks @alanyz106 (#3099)
* **Six new search providers**:
  * **AnySearch** (supports anonymous mode). Thanks @WangPan59 (#3083)
  * **Serply** (Google/Bing SERP API). Thanks @googio (#3071)
  * **Parallel Search**. Thanks @georgeatparallel (#3116)
  * **Tavily** (search API optimized for LLMs). Thanks @1printf (#3124)
  * **SearXNG** (self-hosted search engine, only the instance URL is required). Thanks @1printf (#3124)
  * **Keenable** (supports anonymous mode, no API key required). Thanks @ilya-bogin-keenable (#3122)

## 📝 Workspace File Editing

Workspace files, long-term memory documents, and skill definitions can now be edited and saved directly in the Web console and the desktop client:

* **In-place editing**: text files in the workspace, memory, and skill modules (Markdown, code, CSV, HTML, plain text, and more) can be edited directly, with keyboard shortcuts for `Ctrl+S` to save, `Esc` to exit, and `Tab` to indent.
* **Safe saving**: saving checks for conflicts against the file's modification time when it was opened; if the Agent changed the file in the meantime, you are asked first instead of overwriting it. Closing the panel, switching files, switching sessions, or switching workspaces prompts for confirmation on unsaved changes.

Thanks @zkjqd (#3076)

## 🛠 Improvements & Fixes

* **Skill fixes**:
  * hardened tar archive extraction (Thanks @Whxuan0701 #3063)
  * resolve a repository's default branch instead of defaulting to `main` when installing a skill (Thanks @aniruddhaadak80 #3080)
* **MCP enhancements**:
  * support tool-name prefixes (Thanks @georgeatparallel #3116)
  * recover expired Streamable HTTP sessions (Thanks @yiheng-kkk ad1f686)
  * reuse the subprocess and drop duplicate load logs when multiple Agents share the same `mcp.json`
* **Image generation**:
  * fixed ModelScope `IMAGE_CREATE` failing due to a parameter mismatch (Thanks @Anai-Guo #3097)
  * fixed empty base64 data being misdetected and producing an empty image file (Thanks @c020627 #3133, @justinguo7777 #3131)
* **Sub-Agent fix**: fixed a sub-Agent clearing the parent session's fallback settings (Thanks @alanyz106 #3111).
* **Structured chunking**: Markdown memory and knowledge documents are chunked by heading structure, with a prompt to rebuild when the chunk version is outdated. Thanks @alanyz106 (#3115)
* **Streaming error fix**: fixed seven model bots raising a `NameError` on streaming errors because the generator closed over the already-cleared exception variable, masking the real upstream error (Thanks @Anai-Guo #3128).
* **Memory index fix**: fixed blank text chunks causing the embeddings API to error and the entire memory index build to fail, falling back to keyword search (Thanks @6vision #3121).
* **Interruption detection**: pass `stop_reason` through to the Agent loop to distinguish a model ending on its own from being cut off by the output limit (Thanks @6vision #3074).
* **Attachment detection**: match keyword attachment URLs against the resolved path (Thanks @Whxuan0701 #3061).
* **Gateway attribution**: add source attribution to OrcaRouter gateway requests (Thanks @Marc-oss-hub #3058).
* **Proxy rendering**: set the Content-Type on `/chat` so the console renders correctly behind a reverse proxy with nosniff (Thanks @alanyz106 #3110).
* **Avatar handling**: fixed avatar upload failing due to text decoding, now reading raw bytes (Thanks @mengluo04).
* **Evaluation tool**: added a minimal Agent trajectory evaluation flow. Thanks @yanzhiliaoliao (#3100)
* **DingTalk channel**: disable the proxy on streaming connections and back off on reconnect, eliminating recurring errors.
* **Windows client**: fixed an update installation breaking the shortcut.
* **Desktop client**: fixed numeric Agent settings like max context tokens not being clearable (Thanks @zkjqd #3130).
* **Backup and restore**: backups now include all Agent workspaces, with fixes for nested archiving, restore layout, and version compatibility in multi-Agent setups.
* **Docs**:
  * added a Traditional Chinese entry to the Japanese docs language switcher (Thanks @c020627 #3072)
  * added Kimi-related links (Thanks @oriengy #2885)

## 📦 How to Upgrade

* **Source deployment**: run `cow update` for a one-click upgrade, or pull the latest code and restart. See the [upgrade guide](https://docs.cowagent.ai/guide/upgrade).
* **Desktop client**: check for updates and update with one click inside the client, or get the latest version from the [download page](https://cowagent.ai/download/).

**Release date**: 2026.09.10 | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.1.7...2.1.8)


# v2.1.9
Source: https://docs.cowagent.ai/releases/v2.1.9

CowAgent 2.1.9: builds on the 2.1.8 multi-agent release with smoother agent collaboration, configurable model lists with model fallback, and fixes for channel integration, image generation and voice.

🌐 [English](https://docs.cowagent.ai/releases/v2.1.9) | [中文](https://docs.cowagent.ai/zh/releases/v2.1.9)

> This is a refinement release for the [2.1.8 multi-Agent version](https://docs.cowagent.ai/releases/v2.1.8), building on it with a series of improvements and fixes across multi-Agent collaboration, model capabilities, and channel integration.

## 🤝 Multi-Agent Experience

Further polish around using multi-Agent teams:

* **Multi-Agent session selection**: the in-session multi-Agent selector adds a lead-Agent marker that clearly separates the lead Agent from members, while simplifying the view in single-Agent setups.
* **Collaboration fix**: fixed failures when delegating tasks from non-lead Agents in multi-Agent group chats, now correctly identifying member Agents.
* **Member Agent image rendering**: fixed images generated by non-default Agents failing to render on the Web console and desktop client.
* **Group-chat entry**: the desktop **Team** page adds a group-chat entry, so you can start a group session directly from an Agent team.

![Multi-Agent group chat](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/agent-group-chat-picker.png)

## 📡 Channel Integration Fixes

Fixed key issues along the console's channel start/stop path for more stable channel integration:

* **Desktop channel integration fix**: fixed channels failing to start in the desktop client.
* **Channel stop fix**: fixed a lost `app_module` lookup during the channel stop flow that caused disconnect errors (a regression introduced by #3141).
* **QQ channel reconnection**: fixed the QQ channel not reconnecting after a silent WebSocket disconnect; it now reconnects automatically.

## 🤖 Model Capabilities

* **Model list configuration**: model providers can now configure a model list, setting the model name, model type, context window, max output, and more. Thanks @alanyz106 (#3146)

![Model list configuration](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/model-catalog-config.png)

* **Multiple fallback models**: when the primary model fails, CowAgent now tries an ordered fallback chain in turn, replacing the previous single fallback model. Thanks @alanyz106 (#3125)

![Multiple fallback models](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/model-fallback-chain.png)

* **Fallback credential fix**: fixed credential resolution during fallback, which now resolves credentials by the provider actually routed to rather than the global configuration. Thanks @alanyz106 (#3142)
* **New image models**: added `gpt-image-2.5-flare` and `gpt-image-2.5-sunburst`. Thanks @cowagent (#3140)

## 🛠 Improvements & Fixes

* **Config file tolerance**: tolerate a UTF-8 BOM in `config.json`, and stop the pre-login 401 polling to avoid invalid requests before sign-in.
* **Image generation fixes**:
  * fixed Baidu Ernie `IMAGE_CREATE` crashing when unsupported, now returning an error message instead (Thanks @c020627 #3144).
  * fixed Midjourney reply retries not recursing into the send logic correctly (Thanks @c020627 #3151).
* **Voice fix**: fixed silk voice transcoding by first decoding silk into a standalone wav and then re-encoding to mp3, avoiding overwriting the source file (Thanks @c020627 #3149).
* **Media URL classification**: determine media type from the resolved URL path, fixing misclassified media links (Thanks @c020627 #3150).
* **Baidu Translate**: fixed Baidu Translate not reporting the API error after all retries failed (Thanks @c020627 #3147).
* **Background command detection**: restrict `run_in_background` to long-running processes, preventing tasks from being marked complete too early.
* **Tool output truncation**: report the byte-based truncation reason correctly when kept lines are partially truncated (Thanks @c020627 #3137).
* **Web mobile layout**: improved the console layout on mobile.
* **Desktop client**: fixed the multi-Agent team menu not showing.

## 📦 How to Upgrade

* **Source deployment**: run `cow update` for a one-click upgrade, or pull the latest code and restart. See the [upgrade guide](https://docs.cowagent.ai/guide/upgrade).
* **Desktop client**: check for updates and update with one click inside the client, or get the latest version from the [download page](https://cowagent.ai/download/).

**Release date**: 2026.09.14 | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.1.8...2.1.9)


# v2.2.0
Source: https://docs.cowagent.ai/releases/v2.2.0

CowAgent 2.2.0: a new Capabilities center, improved multi-Agent collaboration, a rebuilt Web console, higher model cache hit rates, and broad stability and security hardening

🌐 [English](https://docs.cowagent.ai/releases/v2.2.0) | [中文](https://docs.cowagent.ai/zh/releases/v2.2.0)

## 🧩 Capabilities Center

The former **Skills** menu is now **Capabilities**, a single place in the Web console and desktop client to manage built-in tools, MCP tools, and skills:

* **Skill installation**: install from Cow Skill Hub, GitHub, or ClawHub, or upload an archive, a `SKILL.md`, or a folder. Every skill is previewed first and only installed after you confirm.
* **MCP configuration**: add, edit, and remove MCP servers in the UI, covering the stdio, SSE, and Streamable HTTP transports. Both form and JSON editing are available, and you can paste one or more `mcpServers` entries directly. Saving checks the connection and lists the server's tools; changes take effect on the next message without a restart. Thanks @tsumon (#3155)
* **Tool retrieval diagnostics**: see how MCP tools were ranked and why retrieval fell back during a conversation, making it easier to find out why a tool was not picked. Thanks @zhongjunqi7657 (#3165)

![Capabilities](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/capabilities-overview.png)

Related docs: [MCP Tools](https://docs.cowagent.ai/tools/mcp), [Installing Skills](https://docs.cowagent.ai/skills/install)

## 🤝 Multi-Agent Collaboration

* **Task handoff as separate messages**: when an Agent delegates a task to a team member, the member's reply streams as its own message under its own name and avatar, on both the Web console and the desktop client.
* **Team session management**: clearing context now clears it for every participant in a team session; a group chat shows its members in the session list before the first message is sent; the `@` picker can select the Agent that owns the session.
* **Data isolation**: skills, uploaded file previews, and website directories are now scoped per Agent.
* **Fixes**:
  * Fixed an Agent answering on behalf of a team member, and an Agent's own tool calls disappearing after a refresh.
  * Fixed deleted Agents lingering in member lists, which left direct chats unable to use tools (Thanks @Frank-zhu0404 #3234).
  * Fixed the default Agent not being resolved when building team members and cleaning up channel teams (Thanks @c020627 #3205).
  * Fixed some endpoints failing to locate the Agent when the parameter was sent only in the request body (Thanks @c020627 #3177).

![Task handoff as separate messages](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/agent-task-handoff.png)

## 🖥 Console Upgrades

* **Frontend and backend rebuild**: the Web console's frontend pages and backend API controllers are split into feature modules, replacing the oversized single files that had become hard to maintain. Frontend assets load per module and are cached, so a refresh no longer downloads everything again. Each page has its own URL (such as `/agents`, `/settings`, `/scheduler`), browser back and forward work, a refresh stays on the current page, and the old `/chat` address redirects automatically. Thanks @zkjqd (#3167, #3172)
* **Message navigator**: jump quickly to earlier questions in a session. The Web console opens a question list from a button in the header, and the desktop client adds a navigation rail on the right.
* **One-click update**: the version menu in the sidebar checks for and applies source updates in one click. User data is backed up before updating, and a failed update does not affect the running service. Thanks @tsumon (#3154)
* **Reply status**: stopped, interrupted, and in-progress replies are labeled accordingly. A reply cut off by a service restart shows a clear notice, and after a refresh you can keep following a reply that is still being generated.

## 🧠 Memory & Knowledge Base

* **Reranking**: memory retrieval supports an optional rerank model that re-scores recalled results for better precision. It is off by default and enabled via `rerank_provider`. Thanks @SummerCaptain (#3230)
* **Hybrid retrieval scoring**: vector and keyword retrieval are now fused by rank-normalized scores, fixing diluted scores when one side has no hits and mismatched score scales between the two. Thanks @SummerCaptain (#3164)
* **Knowledge base index**: `index.md` is updated when documents are deleted or moved (Thanks @alanyz106 #3237); a large index injects only the list of titles to avoid taking up too much conversation context.
* **Shared knowledge base**: fixed reading and syncing a shared knowledge base located outside the Agent workspace (Thanks @lorenzozanee #3182, @Jeremy-xuan #3183); edits made through tools or the console now mark the index for refresh (Thanks @NBSW002 #3184, @c020627 #3206).
* **Long-term memory**: when `MEMORY.md` exceeds its length limit, the newest entries are kept first (Thanks @SEVEN-us #3244).
* **Document chunking**: fixed content before the first heading of a long Markdown document not being indexed, and content being indexed twice when heading levels are skipped; `/memory status` prompts you to rebuild the index (Thanks @Bdysj #3309).
* **Session loading**: opening a session no longer triggers a memory scan and index rebuild, so the first message in a new session responds faster.

Related docs: [Memory](https://docs.cowagent.ai/memory/index)

## 📐 Context & Token Cost

* **Higher model cache hit rate**: the system prompt now carries only the current date, and the exact time comes from a new `time` tool. The system prompt stays stable throughout the day, which greatly improves model cache hit rates and lowers token usage. Thanks @a1094174619 (#3250)
* **Context trimming**: turn-based and token-budget trimming are merged into a single budget-driven pass. No summarization call is made while within budget, avoiding unnecessary model requests, and the previous turn is always kept. Thanks @liuns-yang (#3188), @Frank-zhu0404 (#3199), @lorenzozanee (#3185)
* **Follow-up messages**: messages you send while the model is still streaming are now picked up promptly (Thanks @tsumon #3190).

## 🤖 Model Capabilities

* **New models**: added `gpt-6.1-sol`, `gpt-6-luna` and `gpt-6-sol`, with `gpt-6.1-sol` as the default recommended OpenAI model (tool calling goes through the Responses API); added `claude-opus-5-5` as the default recommended Claude model.
* **Context window**: the Claude 5 family (`claude-opus-5-5`, `claude-opus-5`, `claude-sonnet-5`, `claude-fable-5`, etc.) is now counted at a 1M context window and 128K max output, instead of the previous flat 200K. Claude 4 and earlier are unchanged.
* **OpenAI Responses API**: a new `open_ai_api_type` setting. Set it to `responses` to call the Responses API, for endpoints that no longer provide `/chat/completions`. The default `auto` keeps the existing behavior.
* **MiniMax**: image understanding now uses M3's native multimodal capability (Thanks @octo-patch #3160).
* **Qwen**: `qwen3.8-max` and `qwen3.8-flash` are handled as hybrid-thinking models; fixed DashScope sessions ignoring the system prompt set by the role plugin (Thanks @Bdysj #3310).
* **Speech recognition**: uses the configured ASR model instead of always using `whisper-1`.
* **AnySearch**: configurable search region and language, with stricter validation of returned results (Thanks @WangPan59 #3153, #3163).

## 📡 Channels

* **DingTalk**:
  * AI card streaming replies when `dingtalk_card_enabled` is on (Thanks @tsumon #3162); replies fall back to Markdown when cards are off or a card fails to send.
  * Receives file attachments (Thanks @tsumon #3161).
  * Fixed error and notice replies being dropped, group messages outside the allowlist raising errors, and rich-text messages without images getting no response (Thanks @Lesereingrape #3282, #3284, #3293).
* **QQ**:
  * Voice messages use the official transcription and are handed to the Agent immediately (Thanks @HnBigVolibear #3195).
  * Receives files, renders Markdown replies, and keeps the original file name when sending documents (Thanks @c020627 #3209).
  * Group chat sessions now follow `group_shared_session`, consistent with other channels: each member gets their own session by default, whereas earlier versions shared one session across the whole group. Set `"group_shared_session": true` to keep the previous behavior (Thanks @c020627 #3209).
* **Feishu**: group messages that only @-mention other members no longer trigger a reply, and rich-text group messages are checked against their @ list (Thanks @c020627 #3173); image and file replies upload directly from memory (Thanks @c020627 #3226); webhook callbacks now verify the token.
* **WeCom**: the WeCom app supports file and video replies (Thanks @c020627 #3249) and replying with locally generated images (Thanks @Lesereingrape #3312), and its callback verifies the Corp ID (Thanks @c020627 #3159); WeCom Bot group messages are correctly recognized as @-mentions (Thanks @c020627 #3193).
* **WeChat Customer Service**: sends local media files, and file replies include their accompanying text (Thanks @c020627 #3262); fixed the message sync cursor not advancing in time (Thanks @rudycelekli #3258).
* **WeChat**: fixed managing multiple channel instances in multi-Agent setups; login state is kept when channel instances change.
* **Video replies**: Discord, Slack, Telegram, Feishu, DingTalk, WeChat Customer Service, and WeChat Official Account upload locally generated videos directly, instead of dropping them or sending only the file path (Thanks @Lesereingrape #3289, #3299, #3321, @c020627 #3297).
* **Slack / Telegram**: Telegram renders `~~~` code blocks correctly (Thanks @huiq777 #3287); Slack files with the same name no longer overwrite each other (Thanks @rudycelekli #3265).
* **WeChat Official Account**: compatible with Python 3.13 (Thanks @c020627 #3214).

## 🛡 Stability & Security

This release makes task execution more reliable and systematically hardens external resource access and local file writes:

* **Persistent execution**: each step's model reply, tool calls, and results are written to the session database as soon as the step completes, instead of all at once at the end of the turn. After a service restart or an unexpected process exit, an interrupted turn is restored together with its completed steps, and the next message can continue from there. Thanks @liuns-yang (#3191)
* **Download limits**: external downloads — channel media, terminal images, image understanding, keyword files, and more — are capped in file size and total time, so oversized files or slow connections cannot drag the service down. Image understanding re-validates the address on every redirect. Thanks @rudycelekli (#3255, #3256, #3257, #3264, #3266, #3267, #3268, #3269, #3270, #3271, #3272), @c020627 (#3219, #3225, #3252, #3300, #3322)
* **Request timeouts**: every external request for models, voice, translation, and more now has a timeout, so an unresponsive upstream no longer hangs the conversation. Thanks @c020627 (#3217, #3220, #3240, #3254, #3275)
* **Safe config writes**: `config.json`, plugin configs, model lists, scheduled tasks, skill configs, credential files, `MEMORY.md`, and more are written atomically, so a write that fails midway cannot corrupt the original file; a corrupted scheduled-task file is restored from its backup automatically. Thanks @c020627 (#3223, #3239, #3241, #3242, #3259, #3273, #3274, #3276, #3279, #3280, #3281), @rudycelekli (#3260)
* **Temporary files**: file names received by channels are confined to the temporary directory and limited in length (Thanks @Lesereingrape #3247, #3248, @c020627 #3212, #3301); downloaded media, reply attachments, and synthesized speech are stored in the owning Agent's temporary directory (Thanks @c020627 #3198, #3207, #3208, #3213); the temporary directory is cleaned up when a skill archive fails to extract (Thanks @Lesereingrape #3325).
* **Log redaction**: channel credentials are masked in debug logs (Thanks @fuxicodex #3228).

## 🛠 Other Improvements & Fixes

* **Voice**:
  * Converts silk voice and amr files with upper-case extensions (Thanks @c020627 #3152).
  * Alibaba Cloud, Edge, ElevenLabs, and other voice services return an error message on failure instead of silently dropping the reply (Thanks @c020627 #3243, #3263, #3278).
  * Fixed WAV file handles not being closed (Thanks @aniruddhaadak80 #3286).
  * Google speech recognition returns an error message on exceptions instead of masking the original error (Thanks @aniruddhaadak80 #3326).
* **Scheduled tasks**: local run times are kept across daylight saving transitions (Thanks @liuns-yang #3189, #3204); files produced by scheduled skill runs are delivered directly instead of as file paths (Thanks @c020627 #3253).
* **Backup**: backups can be written to a different file system (Thanks @zyc2022 #3200, @chen1070109514 #3246); restoring a multi-Agent backup keeps this machine's existing Agent workspace paths (Thanks @Lesereingrape #3319).
* **Plugins**: plugins start normally when their config is empty or incomplete (Thanks @c020627 #3224); Midjourney reports an invalid image index (Thanks @Lesereingrape #3291); the role plugin returns help when a custom role has no description (Thanks @Lesereingrape #3296); admin commands report invalid arguments when setting plugin priority or switching models (Thanks @Lesereingrape #3303, #3305); a missing or malformed entry in `plugins.json` is filled with defaults instead of breaking every plugin (Thanks @Lesereingrape #3314); fixed file naming and unclosed handles in the summary plugin (Thanks @c020627 #3215).
* **Agent management**: deleting an Agent also removes its project data (Thanks @c020627 #3216).
* **Agent Mail**: Docker Compose adds an optional Agent Mail setup that lets the Agent send, receive, search, and manage email. See [Agent Mail](https://docs.cowagent.ai/extensions/agent-mail) (Thanks @tsumon #3236).
* **Message handling**: fixed message context parameters being shared across sessions (Thanks @c020627 #3222); file cache expiry is measured from the most recent file (Thanks @c020627 #3218); fixed the rate limiter blocking process exit and failing at a rate of 0 (Thanks @aniruddhaadak80 #3285); unsupported reply types show the original type in the error message, and voice sessions no longer error after a plugin drops the reply (Thanks @Bdysj #3306, #3307); fixed `#reset`, Feishu message recall, and session deletion failing to clear queued messages under non-default Agents (Thanks @Lesereingrape #3316).
* **Browser tool**: recovers automatically after the browser driver disconnects instead of erroring repeatedly.
* **Desktop client**: fixed the microphone permission prompt not appearing on macOS (Thanks @cowagent #3181); fixed a startup crash caused by Windows shortcuts and duplicated backend log lines.
* **Engineering**: added a full test pipeline and lint gate (Thanks @fuxicodex #3166, #3203); improved test isolation (Thanks @c020627 #3169, #3201, @rudycelekli #3261).
* **Docs**:
  * Documented MCP configuration with static Bearer authentication (Thanks @ct-jaryn #3227).
  * Fixed broken links and log wording in the README (Thanks @yetuge #3194, #3196, #3197).

## 📦 How to Upgrade

* **Source deployment**: run `cow update` for a one-click upgrade, update from the version menu in the Web console sidebar, or pull the latest code and restart. See the [upgrade guide](https://docs.cowagent.ai/guide/upgrade).
* **Desktop client**: check for updates and update with one click inside the client, or get the latest version from the [download page](https://cowagent.ai/download/).

**Release date**: 2026.09.30 | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.1.9...2.2.0)


# v2.2.1
Source: https://docs.cowagent.ai/releases/v2.2.1

CowAgent 2.2.1: a new Artifacts center and custom menu, an open Agent Chat API, prompt caching and context cost savings, plus improvements to tools, channels, and security

🌐 [English](https://docs.cowagent.ai/releases/v2.2.1) | [中文](https://docs.cowagent.ai/zh/releases/v2.2.1)

## 📁 Artifacts

A new **Artifacts** page brings together the files created in your conversations, in both the Web console and the desktop client:

* **Automatic collection**: documents, web pages, images, and videos your Agents create show up in Artifacts automatically, on one timeline across all Agents.
* **Preview and trace back**: filter by type or Agent, search, preview in place, and jump back to the conversation that produced a file (Thanks @rudycelekli #3732).
* **Pin and manage**: pin, rename, or remove artifacts; a file card in a conversation takes you straight to it in Artifacts. The Artifacts page is hidden by default and can be turned on in the menu editor.

![Artifacts](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/web-console-artifacts.png)

Related docs: [Web Console - Artifacts](https://docs.cowagent.ai/channels/web#artifacts)

## 🧭 Custom Menu & Console Improvements

* **Custom menu**: customize the groups, order, names, icons, and visibility of menu entries in the Web console and desktop client, with one shared configuration; artifacts and web links can be added as menu entries. See [Custom Menu](https://docs.cowagent.ai/extensions/custom-menu).
* **Mermaid diagrams**: Mermaid code blocks can switch to a rendered diagram, with zoom and full screen. Thanks @akushonkamen (#3620)
* **Faster long sessions**: long sessions with many tool calls open faster.
* **Fixes**: new session titles are no longer lost, and session actions on the default Agent no longer fail (Thanks @6vision #3625, #3617); settings saved together now all take effect, and workspace files are saved under the Agent they belong to (Thanks @aniruddhaadak80 #3454, #3488).
* **Collapsible sidebar**: the Web console sidebar can collapse into an icon rail.

![Custom menu](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/web-console-custom-menu.png)

## 🔌 Open Agent Chat API

Agents are now available through a standard chat API, so you can connect third-party clients or call an Agent directly from your own systems:

* **Switch and key**: turn the API on and generate an API key in one click on the Config page; the key is kept when the API is turned off. It can also be enabled through the config file or environment variables (Thanks @AaronZ345 #3068, @Bdysj #3342).
* **Agent and model selection**: choose the Agent with `agent_id` and the model with `model`; without a model, the Agent's default model is used.
* **Multi-turn conversations**: by default the caller sends the full message history; with a `conversation_id`, the server keeps the history and only the latest message needs to be sent.
* **Complete output**: streaming and non-streaming responses, including reasoning, token usage, and the tool call trace (Thanks @AaronZ345 #3068, @c020627 #3545, #3588).

![Chat API](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/web-console-chat-api-config.png)

Related docs: [Chat API](https://docs.cowagent.ai/extensions/chat-api)

## 📐 Prompt Caching & Context Cost

* **Claude prompt caching**: the system prompt, tool definitions, and conversation prefix are cached, greatly improving cache hit rates and cutting token cost and latency. The cache lifetime is configurable via `claude_cache_ttl`.
* **Headroom after trimming**: trimming the context now leaves headroom, so the prefix stays unchanged for the next several turns and long sessions keep hitting the cache.
* **Budget changes apply immediately**: changes to the context budget and maximum steps apply to running Agents right away, without clearing the session.
* **Tool records kept in compaction**: compacted turns keep a summary of their tool calls, so the model does not make up results (Thanks @tsumon #3634).
* **Token usage**: each reply shows the tokens actually used in that turn, including cache hits. Thanks @Harbor404 (#3440)
* **Fixes**: messages arriving during compaction are no longer lost, and orphaned tool results are cleaned up more accurately (Thanks @c020627 #3518, @rudycelekli #3652, #3653).

## 🤖 Model Capabilities

* **Claude extended thinking**: the connection stays open during long thinking, and when output stalls the request is retried at a lower thinking effort.
* **Custom headers**: custom model providers support `headers`, with support for OpenCode Go.
* **Model discovery**: when editing a model list, available models can be fetched from the provider automatically. Thanks @Harbor404 (#3441)
* **Reasoning content**: both `reasoning` and `thinking` fields are supported, and an unclosed `<think>` tag no longer cuts off the reply (Thanks @a1094174619 #3601, @fly0sheep-1734 #3538).
* **Fallback models**: the fallback model is reset at the start of each turn instead of staying in use.
* **OpenAI**: improved handling of the Responses API and streaming responses (Thanks @rudycelekli #3659, #3660, #3661, #3663, @aniruddhaadak80 #3486).
* **Model list**: fixed concurrent edits overwriting each other, custom primary models not taking effect, and capability tag matching (Thanks @rudycelekli #3577, #3662, #3666, @aniruddhaadak80 #3501).
* **Other providers**: fixed compatibility issues with MiniMax, ModelScope, Baidu ERNIE, and Azure DALL·E (Thanks @aniruddhaadak80 #3464, #3476, #3479, #3507, #3512, @rudycelekli #3678).
* **Error handling**: rejected requests are no longer resent, errors are recognized more accurately, and context usage shows real token counts (Thanks @c020627 #3442, #3443, #3445, @aniruddhaadak80 #3505, @6vision #3624).
* **Images**: image generation keeps the original format and prompt, and image understanding on macOS no longer upscales images (Thanks @aniruddhaadak80 #3503, #3504, @rudycelekli #3568).

## 🧠 Memory & Knowledge Base

* **Knowledge editing and skill authoring**: edit knowledge base pages directly in the console with the index updated automatically, write skills from scratch, and edit the files in a skill's directory. Thanks @zkjqd (#3377)
* **Hit-based ranking**: a new optional `memory.hit_boost` ranks frequently retrieved memories slightly higher. Off by default. Thanks @foreverjix (#3621)
* **Time decay**: applies only to daily memory files, so dated knowledge base pages are no longer ranked down (Thanks @fly0sheep-1734 #3376).
* **Indexing**: fixed content lost on very long lines, chunks exceeding the budget, and stale index entries after clearing notes (Thanks @fly0sheep-1734 #3585, @rudycelekli #3426, #3578, #3616).
* **Retrieval**: improved full-text search fallback, Unicode keywords, and handling of invalid parameters and vectors (Thanks @aniruddhaadak80 #3480, #3481, #3482, #3483, @rudycelekli #3559, #3656, #3658).
* **Memory writes**: failed writes can be retried, and session data from older versions can be imported (Thanks @aniruddhaadak80 #3406, @c020627 #3590, @rudycelekli #3387).
* **Knowledge base**: fixed graph paths on Windows and documents with upper-case extensions not showing, and tightened import path validation (Thanks @Lesereingrape #3332, @rudycelekli #3612, #3649, #3651).

## 🤝 Multi-Agent Collaboration

* **Permissions and delegation**: delegation and handoff keep the initiator's permission mode, and the receiving Agent re-checks the delegation allowlist, depth, and wait time (Thanks @c020627 #3541, #3546, #3547, #3548, #3552).
* **Default Agent aliases**: always resolved to the default Agent's real ID (Thanks @c020627 #3553, #3554).
* **Team sessions**: deleting a team session now removes it for every participant; fixed the model setting display and follow-up message delivery (Thanks @c020627 #3519, #3537, #3549, #3550, #3613).
* **Sub-agents**: stopping a task also stops its sub-agents; fixed prompt parsing (Thanks @rudycelekli #3637, #3638, #3639).
* **Sessions and projects**: fixed error handling for session settings and project paths (Thanks @c020627 #3551, @rudycelekli #3640, #3654).

## 🧩 Tools & Skills

* **File read/write**: the original file is kept when a write fails; fixed line ending detection, concurrent edits overwriting each other, and argument parsing (Thanks @aniruddhaadak80 #3365, #3404, #3413, @rudycelekli #3525, #3531, #3563, #3566, #3567, #3667).
* **Document parsing**: Word tables, Excel formulas, and PowerPoint tables are preserved in full (Thanks @rudycelekli #3393, #3394, #3560, #3629, #3631).
* **File search**: falls back automatically when the external search command fails; fixed filter rules, case handling, and special files (Thanks @aniruddhaadak80 #3400, @rudycelekli #3391, #3533, #3534, #3558, #3570, #3571, #3630, #3675, #3679).
* **Web fetch**: detects charsets and document types correctly, and limits transfer time and size (Thanks @aniruddhaadak80 #3401, #3478, @rudycelekli #3392, #3569, #3574, #3632, #3669, #3670, #3671).
* **Browser**: pages follow the window size (Thanks @zkjqd #3623); the bundled Chromium is detected correctly in Docker, and installation no longer needs `sudo` (Thanks @handoing #3743, #3744); fixed cleanup after failed launches, scrolling, and element interactions (Thanks @c020627 #3524, @aniruddhaadak80 #3490, @rudycelekli #3562, #3573).
* **Terminal**: fixed truncated multi-byte characters, misreported exit codes, and `.env` parsing (Thanks @rudycelekli #3530, #3564, #3668).
* **MCP**: commands such as `npx` and `uvx` start correctly on Windows (Thanks @6vision #3408); tools can be fetched with pagination, and structured results and errors are passed through (Thanks @rudycelekli #3672, #3673, #3674, @aniruddhaadak80 #3425); connection timeouts and config saving are more reliable (Thanks @aniruddhaadak80 #3414, #3452, #3466, #3469, @c020627 #3438, #3523, #3542, #3610, #3615).
* **Skills**: more GitHub directory layouts are supported; fixed install paths, directory loops, and YAML parsing (Thanks @aniruddhaadak80 #3379, @rudycelekli #3389, #3594, #3597, #3598, @c020627 #3516, #3682).
* **Scheduled tasks**: one-time tasks set in the past are rejected; fixed daylight saving time, task type validation, task file recovery, and delivery targets; compatible with Python versions below 3.9 (Thanks @aniruddhaadak80 #3359, #3374, #3375, #3429, @c020627 #3540, #3604, #3683, @rudycelekli #3390, #3526, #3532, #3575, #3576, #3593, #3636).

## 📡 Channels

* **WeChat**: more stable login; credentials are removed when an instance is deleted; fixed attachments with the same name overwriting each other and leftover temporary files (Thanks @c020627 #3277, #3544, #3581, #3589, #3622, @6vision #3609, @aniruddhaadak80 #3498, @rudycelekli #3635).
* **WeCom**: recovers automatically after a failed token refresh; fixed the WeCom Bot reply stream, image conversion, and duplicate callbacks; temporary files are cleaned up promptly (Thanks @c020627 #3345, #3435, #3529, #3611, #3614, @aniruddhaadak80 #3397, #3497, @rudycelekli #3645).
* **WeChat Customer Service**: retries automatically when saving the message cursor fails (Thanks @rudycelekli #3677).
* **WeChat Official Account**: fixed video replies being dropped and users getting no response after a passive reply (Thanks @aniruddhaadak80 #3360, #3411, @c020627 #3536, #3543, #3606).
* **Feishu**: Markdown image syntax inside code is kept as is (Thanks @huiq777 #3434); fixed token request timeouts and app re-registration (Thanks @aniruddhaadak80 #3358, @c020627 #3539).
* **DingTalk**: code blocks in card replies are kept as is (Thanks @huiq777 #3420); fixed send result checks and image captions being sent twice (Thanks @aniruddhaadak80 #3396, #3496, @c020627 #3432, #3517, #3586).
* **QQ**: sends files larger than 5 MB (Thanks @HnBigVolibear #3647); supports image replies; fixed reconnecting after a disconnect (Thanks @c020627 #3341, @aniruddhaadak80 #3405).
* **Telegram**: fixed formatted message handling stopping midway and link rendering (Thanks @fly0sheep-1734 #3522, @rudycelekli #3665, @aniruddhaadak80 #3416).
* **Slack / Discord**: retries automatically when sending fails (Thanks @aniruddhaadak80 #3415).
* **General**:
  * Expired attachments are no longer sent with the next message (Thanks @SEVEN-us #3407); fixed attachment concurrency, cache cleanup, and file extensions (Thanks @c020627 #3437, @rudycelekli #3561, #3644).
  * The deduplication cache is cleaned up periodically, so memory no longer keeps growing on long-running instances (Thanks @Bdysj #3340).
  * Fixed interrupted message handling, cancellation deadlocks, channel shutdown, and credentials being overwritten (Thanks @c020627 #3348, #3515, @aniruddhaadak80 #3373, #3395, #3410, @rudycelekli #3384, #3648, #3655).

## 🛡 Security Hardening

* **Permissions**: read-only mode now blocks git write operations it previously missed (Thanks @aniruddhaadak80 #3352, @drakeo338 #3357); dangerous operations such as command substitution, writes through arguments, and deleting the root directory are detected (Thanks @c020627 #3579, #3602, @aniruddhaadak80 #3506); outside full-access mode, the MCP config and session permissions cannot be changed.
* **Path access**: stricter path checks for uploads, static assets, skill uninstall, backup restore, and more, and credential files are blocked (Thanks @aniruddhaadak80 #3409, #3460, #3461, #3463, @c020627 #3446, @rudycelekli #3527, #3528, @Harbor404 #3436).
* **External resources**: a unified download size limit, with media URLs and certificates validated (Thanks @c020627 #3327, #3328, #3329, #3336, #3555, #3556, #3557, @rudycelekli #3428, @aniruddhaadak80 #3457, #3477).
* **Log redaction**: access tokens and secrets are no longer written to logs in plain text (Thanks @c020627 #3356, #3444, @aniruddhaadak80 #3369, #3399, #3511).
* **Robust config**: `.env` rejects values containing line breaks (Thanks @Lesereingrape #3344); config files with a BOM are supported, with stricter type checks and atomic writes (Thanks @c020627 #3412, #3433, #3447, #3448, @aniruddhaadak80 #3431, #3499, @rudycelekli #3641).

## 🛠 Other Improvements & Fixes

* **Artifacts**: fixed upgrades from older databases, Windows paths, and locating earlier messages (Thanks @Lesereingrape #3450, #3514, @aniruddhaadak80 #3402).
* **Agent execution**: fixed tool exceptions, the step limit overriding the answer, cancellation, and concurrency issues (Thanks @aniruddhaadak80 #3383, #3403, #3424, @c020627 #3582, #3583, #3587, @rudycelekli #3388, #3643, #3650).
* **Voice**: the text reply is still sent when text-to-speech fails; fixed timeouts and error handling in several voice services (Thanks @c020627 #3684, @aniruddhaadak80 #3330, #3363, #3491).
* **Plugins**: fixed plugin reloading, duplicate registration, empty messages, and the keyword and role plugins (Thanks @aniruddhaadak80 #3367, #3398, @c020627 #3520, #3521, #3584, @rudycelekli #3664, #3728).
* **Self-evolution**: snapshot restore and backups are more reliable (Thanks @rudycelekli #3385, #3657, @c020627 #3600).
* **Agent management**: deleting an Agent also removes its avatar and sessions (Thanks @c020627 #3580, #3603).
* **CLI and backup**: `/status` shows loaded MCP servers (Thanks @HnBigVolibear #3474); fixed backups, config loading, knowledge base listing, and updates in Git worktrees (Thanks @rudycelekli #3592, #3595, #3596, #3599, #3607).
* **Logs**: the Logs page loads more reliably, and live logs no longer drop lines (Thanks @c020627 #3349, @rudycelekli #3642).
* **Chinese conversion**: corrected the Simplified–Traditional Chinese mapping table (Thanks @aniruddhaadak80 #3347).
* **Docker**: the Compose template enables the Web console by default, so models can be configured in the console after the first start.
* **Desktop client**: shortcuts are restored after reinstalling, and the update channel is kept when using a custom update source.
* **Docs**:
  * Documented the data directory for Docker upgrades (Thanks @Frank-zhu2000 #3680).
  * Fixed links on the Japanese models page (Thanks @pratikgx #3681).
  * Aligned the MCP docs with the console wording (Thanks @c020627 #3418).

## 📦 How to Upgrade

* **Source deployment**: run `cow update` for a one-click upgrade, update from the version menu in the Web console sidebar, or pull the latest code and restart. See the [upgrade guide](https://docs.cowagent.ai/guide/upgrade).
* **Desktop client**: check for updates and update with one click inside the client, or get the latest version from the [download page](https://cowagent.ai/download/).

**Release date**: 2026.10.14 | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.2.0...2.2.1)


# Create Skills
Source: https://docs.cowagent.ai/skills/create

Create custom skills by chatting: CowAgent's built-in Skill Creator turns a workflow or an API spec into a skill, generating SKILL.md and scripts and saving them to your workspace.

CowAgent includes a built-in Skill Creator that lets you quickly create, install, or update skills through natural language conversation.

## Usage

Simply describe the skill you want in a conversation, and the Agent will handle the creation:

* Codify workflows as skills: "Create a skill from this deployment process"
* Integrate third-party APIs: "Create a skill based on this API documentation"
* Install remote skills: "Install xxx skill for me"

## Creation Flow

1. Tell the Agent what skill you want to create
2. Agent automatically generates `SKILL.md` description and execution scripts
3. Skill is saved to the workspace `~/cow/skills/` directory
4. Agent will automatically recognize and use the skill in future conversations

![](https://cdn.link-ai.tech/doc/20260202202247.png)

## SKILL.md Format

Created skills follow the standard SKILL.md format:

```markdown theme={null}
---
name: my-skill
description: Brief description of the skill
metadata:
  emoji: 🔧
  requires:
    bins: ["curl"]
    env: ["MY_API_KEY"]
  primaryEnv: "MY_API_KEY"
---

# My Skill

Detailed instructions...
```

| Field | Description |
| - | - |
| `name` | Skill name, must match directory name |
| `description` | Skill description, Agent decides whether to invoke based on this |
| `metadata.requires.bins` | Required system commands |
| `metadata.requires.env` | Required environment variables |
| `metadata.always` | Always load (default false) |

> [!TIP]
>
> See the [Skill Creator documentation](https://github.com/zhayujie/CowAgent/blob/master/skills/skill-creator/SKILL.md) for details.


# Skill Hub
Source: https://docs.cowagent.ai/skills/hub

Cow Skill Hub is an open-source marketplace of AI agent skills from official, community and third-party sources like GitHub and ClawHub. Browse, search, read docs and install with one command.

[Cow Skill Hub](https://skills.cowagent.ai/) is an open-source skill marketplace for AI Agents, aggregating official picks, community contributions, and third-party skills from GitHub, ClawHub, and beyond.

Source code: [github.com/zhayujie/cow-skill-hub](https://github.com/zhayujie/cow-skill-hub)

![](https://cdn.link-ai.tech/doc/20260401110103.png)

## Features

* **Browse skills** — filter by category (Featured / Community / Third-party) and tags
* **Search skills** — find skills by name or description
* **View details** — read the skill manifest, file contents, install command, and required environment variables
* **One-click install** — copy the install command and run it in CowAgent

## Installing a skill

Run the install command in chat or in your terminal:

```text Chat theme={null}
/skill install <name>
```

```bash Terminal theme={null}
cow skill install <name>
```

You can also browse the marketplace directly from chat:

```text theme={null}
/skill list --remote
/skill search <keyword>
```

Beyond the curated list, you can install third-party skills from **GitHub, ClawHub, LinkAI, or any URL** via the CLI. See [Installing skills](/skills/install) for details.

## Contributing a skill

To submit your own skill:

1. Visit [skills.cowagent.ai/submit](https://skills.cowagent.ai/submit)
2. Sign in with GitHub or Google
3. Upload a folder or zip file containing `SKILL.md`
4. Skill name, display name, and description are auto-detected — adjust as needed
5. Submit for review; skills go live after security and quality checks

![](https://cdn.link-ai.tech/doc/20260401111904.png)

Skill file layout:

```
your-skill/
├── SKILL.md        # required, in the root
├── scripts/        # optional, runtime scripts
└── resources/      # optional, additional assets
```

> [!TIP]
>
> Skills are built around the `SKILL.md` manifest. You can also download `SKILL.md` from a skill's detail page and use it with any Agent that supports custom instructions (OpenClaw, Cursor, Claude Code, and more).


# image-generation
Source: https://docs.cowagent.ai/skills/image-generation

The image-generation skill handles text-to-image, image-to-image and multi-image fusion across OpenAI, Gemini, Seedream, Qwen, MiniMax and more, with automatic routing and fallback between providers.

A general-purpose image generation and editing skill supporting six providers: OpenAI, Gemini, Seedream (Volcengine Ark), Qwen (DashScope), MiniMax, and LinkAI. Configure any one provider's key to start using it; configure multiple to enable automatic fallback.

## Supported Models

| Provider | Models / Aliases | Notes |
| - | - | - |
| OpenAI | `gpt-image-2.5-flare`, `gpt-image-2.5-sunburst`, `gpt-image-2`, `gpt-image-1` | General-purpose, high quality, supports `quality` parameter |
| Gemini Nano Banana | `nano-banana-2`, `nano-banana-pro`, `nano-banana` | Corresponds to the image variants of `gemini-3.1-flash`, `gemini-3-pro`, `gemini-2.5-flash` |
| Seedream (Volcengine Ark) | `seedream-5.0-lite`, `seedream-4.5` | Native 2K–4K, up to 14 reference images for fusion |
| Qwen (DashScope) | `qwen-image-2.0`, `qwen-image-2.0-pro` | Strong with Chinese text rendering and text-image layouts |
| MiniMax | `image-01` | Fast and simple |
| LinkAI | Any model | Universal gateway, used as fallback |

## Model Selection

By default, "auto routing + automatic fallback" is used:

1. Pick the first configured provider in the order `OpenAI → Gemini → Seedream → Qwen → MiniMax → LinkAI`
2. On errors such as 401, model not enabled, or network issues, automatically switch to the next provider
3. If the user specifies a model in the conversation (e.g. "use seedream to draw a cat"), the corresponding provider is promoted to the front

To pin a specific model:

```json theme={null}
{
  "skills": {
    "image-generation": {
      "model": "seedream-5.0-lite"
    }
  }
}
```

## Configuring API Keys

> [!TIP]
>
> It is recommended to configure providers from the "Model Management" page in the [Web console](/channels/web). Chat model keys configured there are automatically reused by the image generation skill — no need to set them twice. You can also edit the configuration file manually or temporarily set keys in a conversation using the `env_config` tool.

Credentials are shared with the main model providers:

| Field | Provider |
| - | - |
| `openai_api_key` | OpenAI |
| `gemini_api_key` | Gemini |
| `ark_api_key` | Volcengine Ark (Seedream) |
| `dashscope_api_key` | Alibaba DashScope (Qwen) |
| `minimax_api_key` | MiniMax |
| `linkai_api_key` | LinkAI |

## Enabling and Disabling

The skill automatically adjusts its status based on API keys:

* **Key configured**: the Agent calls the skill directly when it receives a drawing request
* **Key not configured**: the skill still appears in context (marked as "needs configuration") — the Agent will guide the user to set up a key

To control it manually:

```text theme={null}
/skill disable image-generation    # Disable
/skill enable image-generation     # Re-enable
```

Equivalent terminal commands: `cow skill disable image-generation` / `cow skill enable image-generation`.

## Parameters

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `prompt` | string | Yes | — | Image description |
| `image_url` | string / list | No | null | Input image for editing — local path or URL; pass a list for multi-image fusion |
| `quality` | string | No | auto | `low` / `medium` / `high`, supported only by some providers |
| `size` | string | No | auto | `512` / `1K` / `2K` / `3K` / `4K`, or pixel value like `1024x1024` |
| `aspect_ratio` | string | No | null | `1:1` / `3:2` / `2:3` / `16:9` / `9:16` / `21:9`; Gemini also supports `1:4` / `4:1` / `1:8` / `8:1` |

> [!WARNING]
>
> **Higher quality and larger size cost more and take longer.** For everyday conversations, use the defaults (`auto`) or `quality=low` + `size=1K` — about 20 seconds per image. For posters or when high resolution is explicitly requested, use `quality=high` + `size=2K/4K` — may take 1–5 minutes.

## Common Use Cases

* **Text-to-image**: generate illustrations, posters, icons, avatars, storyboards, etc. from a description
* **Image-to-image**: change styles, swap elements, add decorations or text on an existing image
* **Multi-image fusion**: combine multiple reference images into one (outfit swaps, character group photos, etc.)

> [!NOTE]
>
> * Bash timeout should be set to 600 seconds: each provider has a 300-second HTTP timeout, and the script may try multiple providers sequentially
> * Input images are automatically compressed to ≤ 4 MB with the longest edge ≤ 4096 px
> * Gemini / Seedream / Qwen / MiniMax do not support the `quality` parameter
> * Seedream defaults to 2K; `seedream-5.0-lite` supports up to 3K; `seedream-4.5` supports up to 4K


# Skills Overview
Source: https://docs.cowagent.ai/skills/index

How CowAgent skills work: a SKILL.md file with optional scripts and resources that combines tools into workflows. See built-in skills and get more from the Skill Hub, GitHub or ClawHub.

Skills provide infinite extensibility for the Agent. Each Skill consists of a description file (`SKILL.md`), execution scripts (optional), and resources (optional), describing how to accomplish specific types of tasks.

The difference between Skills and Tools: Tools are atomic operations implemented in code (e.g., file read/write, command execution), while Skills are high-level workflows based on description files that can combine multiple Tools to complete complex tasks.

## Getting Skills

CowAgent offers multiple ways to acquire skills:

* **Cow Skill Hub** — Browse and install community skills via `/skill list --remote`
* **GitHub** — Install directly from GitHub repositories, with batch install support
* **ClawHub** — Install ClawHub skills via `/skill install clawhub:name`
* **URL** — Install from zip archives or SKILL.md links
* **Conversational creation** — Let the Agent create skills through natural language conversation

See [Install Skills](/skills/install) and [Skill Management Commands](/cli/skill) for details. You can also [create skills](/skills/create) through conversation.

## Skill Loading Priority

1. **Workspace skills** (highest): `~/cow/skills/`
2. **Project built-in skills** (lowest): `skills/`

Skills with the same name are overridden by priority.

## Skill File Structure

```
skills/
├── my-skill/
│   ├── SKILL.md          # Skill description (frontmatter + instructions)
│   ├── scripts/          # Execution scripts (optional)
│   └── resources/        # Additional resources (optional)
```

### SKILL.md Format

```markdown theme={null}
---
name: my-skill
description: Brief description of the skill
metadata:
  emoji: 🔧
  requires:
    bins: ["curl"]
    env: ["MY_API_KEY"]
  primaryEnv: "MY_API_KEY"
---

# My Skill

Detailed instructions...
```

| Field | Description |
| - | - |
| `name` | Skill name, must match directory name |
| `description` | Skill description, Agent decides whether to invoke based on this |
| `metadata.requires.bins` | Required system commands |
| `metadata.requires.env` | Required environment variables |
| `metadata.always` | Always load (default false) |


# Install Skills
Source: https://docs.cowagent.ai/skills/install

Install skills with one command from the Skill Hub, GitHub, ClawHub or any URL (zip or SKILL.md), or add them from the market or by local upload with a preview in the web console and desktop app.

CowAgent supports installing skills from [Cow Skill Hub](https://skills.cowagent.ai/), GitHub, ClawHub, LinkAI, and any URL via a unified `install` command. Use `/skill install` in chat or `cow skill install` in the terminal.

You can also add skills from the Capabilities page in the web console and desktop app. Click **Add skill**, then either:

* **From a market**: pick Cow Skill Hub or ClawHub and enter the skill name, or pick GitHub and enter a repository or folder URL.
* **Upload**: drop in a `.zip` / `.tar.gz` archive, a `SKILL.md`, or a whole skill folder.

The skill is fetched first and shown for review (its `SKILL.md`, file list, and whether it would replace an installed skill). Nothing is installed until you confirm.

## From the Skill Hub

Browse all available skills at [skills.cowagent.ai](https://skills.cowagent.ai/) and install by name:

```text theme={null}
/skill list --remote
/skill install pptx
```

## From GitHub

Any GitHub-hosted skill can be installed directly. Supports both repository-level batch install and subdirectory-level single install:

```text theme={null}
/skill install larksuite/cli
/skill install https://github.com/larksuite/cli/tree/main/skills/lark-im
```

## From ClawHub

All [ClawHub](https://clawhub.ai/) skills (40k+) can be installed with a single command:

```text theme={null}
/skill install clawhub:<name>
```

ClawHub skill names are only unique per publisher. When several publishers share a name, include the publisher or use the skill's page URL:

```text theme={null}
/skill install clawhub:steipete/gog
/skill install https://clawhub.ai/steipete/skills/gog
```

## From LinkAI

All public resources on [LinkAI](https://link-ai.tech/console?utm_source=cowagent\&utm_medium=docs\&utm_campaign=skills-install) (10k+ apps / workflows / plugins), as well as your own resources (apps, workflows, knowledge bases, databases, plugins), can be installed via:

```text theme={null}
/skill install linkai:<code>
```

> Every resource created on the LinkAI platform has a unique `code`. Find it on each resource's page in the [console](https://link-ai.tech/console?utm_source=cowagent\&utm_medium=docs\&utm_campaign=skills-install).

## From URL

Supports zip archives and SKILL.md file links:

```text theme={null}
/skill install https://cdn.link-ai.tech/skills/pptx.zip
/skill install https://example.com/path/to/SKILL.md
```

## Manage Skills

```text theme={null}
/skill list                  # View installed skills
/skill info pptx             # View skill details
/skill enable pptx           # Enable a skill
/skill disable pptx          # Disable a skill
/skill uninstall pptx        # Uninstall a skill
```

> [!TIP]
>
> All commands above work in the terminal by replacing `/skill` with `cow skill`. See [Skill Management Commands](/cli/skill) for full documentation.


# knowledge-wiki
Source: https://docs.cowagent.ai/skills/knowledge-wiki

The knowledge-wiki skill turns shared material, ideas and notes into a local structured knowledge base, filing pages and maintaining an index and cross-links. Always loaded, no dependencies.

Organises notes, insights, and reference materials from your conversations into a structured local knowledge base, automatically maintaining an index and cross-references between pages.

`knowledge-wiki` maintains a `knowledge/` directory in your workspace — essentially the Agent's "second brain". The skill is marked `always: true`, so it is **always loaded** and requires no external dependencies.

## When It Triggers

* You share an article, document, or URL that you want to keep for future reference
* A conversation produces conclusions worth retaining long-term
* You want to look up something you accumulated earlier

## Directory Structure

```
knowledge/
├── index.md           # Global index (must be maintained)
├── log.md             # Operation log (append-only)
└── <category>/        # Category subdirectories (grouped by content)
    └── <slug>.md      # Knowledge page (lowercase-hyphenated filename)
```

## Three Core Operations

### 1. Ingest

When you share some material, the Agent will:

1. Read and understand the original content, extracting key information
2. Decide which category it belongs to — check `index.md` first; create a new category if none fits
3. Generate a knowledge page at `knowledge/<category>/<slug>.md`
4. Update the index `index.md` and the log `log.md`

### 2. Synthesise

When a conversation produces new conclusions or insights:

1. Create a new knowledge page under an appropriate category
2. Add cross-links to and from related existing pages
3. Update the index and log

### 3. Query

When you ask about previously accumulated knowledge:

1. Search `index.md` for potentially relevant pages
2. Open specific pages with the `read` tool
3. Supplement with `memory_search` if needed
4. Include links to knowledge pages in the answer so you can click through to the source

## Page Format

```markdown theme={null}
# Page Title

> Source: <source URL or brief description>

Body content. Link between pages using relative paths:
[Related Page](../category/related-page.md)

## Key Points

- ...

## Related Pages

- [Page A](../category/page-a.md) — why it's related
```

> [!NOTE]
>
> * `> Source:` records where this knowledge came from. Always include it when there is a clear source
> * Cross-references are important: when creating or updating a page, remember to add back-links in the related pages too
> * **Only link to pages that already exist.** If a concept deserves its own page, create it first, then add the link

## Index Format

`knowledge/index.md` uses a flat list grouped by category, one knowledge page per line:

```markdown theme={null}
# Knowledge Index

## Category A
- [Page Title](category-a/page-slug.md) — one-line summary

## Category B
- [Page Title](category-b/page-slug.md) — one-line summary
```

No tables, no emojis. Category names and organisation can be adjusted freely.

## Log Format

`knowledge/log.md` is append-only — newest entries go at the bottom:

```markdown theme={null}
## [YYYY-MM-DD] ingest | Page Title
## [YYYY-MM-DD] synthesize | Page Title
```

## Writing Guidelines

* **Filenames**: lowercase with hyphens, e.g. `machine-learning.md`
* **One topic per page** — link related content across pages
* **Update, don't duplicate** — if a page already exists, update it rather than creating a new one
* **Always update the index** `knowledge/index.md` after any change
* **Distill, don't copy** — capture the key points, not the entire source
* **Use full paths when referencing knowledge pages in conversations**, e.g. `[Title](knowledge/<category>/<slug>.md)`. Use relative paths only for inter-page links
* **Include links when answering questions based on knowledge pages** so users can dig deeper


# skill-creator
Source: https://docs.cowagent.ai/skills/skill-creator

skill-creator is a built-in meta skill that helps the agent create, install, upgrade and refactor skills with a consistent SKILL.md and folder layout. Covers triggers, structure and conventions.

`skill-creator` is a "meta-skill" that helps the Agent create, install, and update other skills, ensuring every skill follows a consistent `SKILL.md` format and directory layout.

## When It Triggers

* The user wants to install a skill from a URL or remote repository
* The user wants to create a brand-new skill from scratch
* An existing skill needs upgrading or restructuring

## What Is a Skill?

A skill is a reusable instruction set plus optional scripts and assets. It injects domain expertise into the Agent so it can handle specific tasks like a specialist.

A skill typically contains:

1. **Specialised workflow** — step-by-step instructions for a category of tasks
2. **Tool usage** — how to call a particular API or process a particular file format
3. **Domain knowledge** — team conventions, business rules, data schemas, etc.
4. **Attached resources** — scripts, reference docs, templates, etc.

> [!NOTE]
>
> **Core principle: less is more.** Only write what the Agent wouldn't figure out on its own. For every line you add, ask yourself: is it worth the tokens?

## Directory Structure

```
skill-name/
├── SKILL.md            # Required: skill definition
│   ├── YAML frontmatter (name / description are mandatory)
│   └── Markdown body (instructions + examples)
└── Optional resources
    ├── scripts/        # Executable scripts (Python / Bash, etc.)
    ├── references/     # Large reference docs the Agent reads on demand
    └── assets/         # Templates, icons, etc. used directly in output
```

## SKILL.md Specification

Frontmatter fields in the SKILL.md header:

| Field | Description |
| - | - |
| `name` | Skill name — lowercase with hyphens, must match the directory name |
| `description` | **The most important field.** Clearly state what the skill does and when to use it. The Agent reads this to decide whether to invoke it. All trigger-related descriptions go here, not in the body |
| `metadata.cowagent.requires.bins` | System CLI tools that must be installed |
| `metadata.cowagent.requires.env` | Required environment variables (all must be present) |
| `metadata.cowagent.requires.anyEnv` | Multiple API keys — at least one must be set |
| `metadata.cowagent.requires.anyBins` | Multiple tools — at least one must be installed |
| `metadata.cowagent.always` | Set to `true` to always load, skipping dependency checks |
| `metadata.cowagent.emoji` | Display emoji (optional) |
| `metadata.cowagent.os` | OS restriction, e.g. `["darwin", "linux"]` |

> [!NOTE]
>
> The `category` field does not need to be set manually — the system automatically sets it to `skill`.

Two ways to declare API key dependencies:

```yaml theme={null}
metadata:
  cowagent:
    requires:
      env: ["MYAPI_KEY"]            # Must be present
```

```yaml theme={null}
metadata:
  cowagent:
    requires:
      anyEnv: ["OPENAI_API_KEY", "LINKAI_API_KEY"]   # At least one
```

**Skills are auto-enabled/disabled based on dependencies**: they activate when all required environment variables are present and deactivate when any are missing — no need for manual `/skill enable`.

## Resource Directories

| Directory | What goes here | What does NOT go here |
| - | - | - |
| `scripts/` | Code that needs to run repeatedly, or scripts that produce deterministic results | Demo-only code snippets |
| `references/` | Documents **over 500 lines** that genuinely won't fit in SKILL.md (e.g. a full DB schema) | General API docs, tutorials, examples |
| `assets/` | Files that appear in the final output (templates, icons, boilerplate, etc.) | Explanatory documentation |

> [!WARNING]
>
> **In principle, everything goes in `SKILL.md`** — only split into resource directories when it truly won't fit.
>
> Do not add `README.md`, `CHANGELOG.md`, or `INSTALLATION_GUIDE.md` to a skill — put everything in `SKILL.md`. Resource directories should only contain scripts that actually run or assets that are actually used.

## Installing External Skills

After installation, the skill lands in `<workspace>/skills/<name>/`.

| Source | How to install |
| - | - |
| URL (single file) | curl / web\_fetch |
| URL (zip archive) | Download and extract |
| Local SKILL.md | Read directly |
| Local zip archive | Extract |

Installation steps:

1. Locate the `SKILL.md` (may be at the root or in a subdirectory of the archive)
2. Read the `name` from the frontmatter
3. Copy the **entire skill directory** (including `SKILL.md`, `scripts/`, `assets/`, etc.) to `<workspace>/skills/<name>/`
4. If the archive contains an `INSTALL.md` or similar setup script, run it — but the final result must still reside under `<workspace>/skills/<name>/`

## Creating a Skill from Scratch

Recommended order:

1. **Clarify requirements** — ask the user for a few concrete use cases (don't ask too many at once)

2. **Plan the structure** — does this skill need scripts? Reference docs? Template assets?

3. **Scaffold** — use the init script:

   ```bash theme={null}
   scripts/init_skill.py <skill-name> --path <workspace>/skills [--resources scripts,references,assets] [--examples]
   ```

4. **Fill in content** — write SKILL.md, add scripts and resources. Always test scripts after writing them

5. **Validate** (optional):

   ```bash theme={null}
   scripts/quick_validate.py <workspace>/skills/<skill-name>
   ```

6. **Iterate** — keep improving based on real-world usage feedback

## Naming Conventions

* Use only lowercase letters, digits, and hyphens. Normalise user-given names, e.g. `Plan Mode` → `plan-mode`
* Maximum 64 characters
* Keep it short, start with a verb, make it self-explanatory
* Use tool names as prefixes when appropriate, e.g. `gh-address-comments`, `linear-address-issue`
* The directory name and the `name` field must match exactly

## Three-Level Loading

Skills are not loaded into context all at once — they use a three-level progressive loading mechanism:

1. **Metadata** (`name` + `description`) — always in context (\~100 words). The Agent uses this to decide whether to invoke the skill
2. **SKILL.md body** — loaded only when the skill is activated; keep it under 500 lines
3. **Resource files** — read on demand by the Agent

For skills with multiple variants (e.g. multi-cloud deployment), organise like this:

```
cloud-deploy/
├── SKILL.md             # Main workflow and provider selection logic
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md
```

When the user picks AWS, the Agent only reads `aws.md` — no need to load all three providers.

## Common Design Patterns

**Step-by-step**: numbered steps with corresponding scripts.

```markdown theme={null}
1. Analyse form structure (run analyze_form.py)
2. Generate field mappings (edit fields.json)
3. Auto-fill the form (run fill_form.py)
```

**Branching**: different flows based on user intent.

```markdown theme={null}
1. Determine operation type:
   **Creating new content?** → follow the "Create" workflow
   **Editing existing content?** → follow the "Edit" workflow
```

**Template-based**: when output format has strict requirements, include a template in SKILL.md for the Agent to follow.


# bash - Terminal
Source: https://docs.cowagent.ai/tools/bash

The bash tool runs shell commands in the working directory and returns stdout and stderr, with API keys from env_config injected, for installing packages, running code, deploying and troubleshooting.

Execute Bash commands in the current working directory, returns stdout and stderr. API keys configured via `env_config` are automatically injected into the environment.

## Dependencies

No extra dependencies, available by default.

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `command` | string | Yes | Command to execute |
| `timeout` | integer | No | Timeout in seconds |

## Use Cases

* Install packages and dependencies
* Run code and tests
* Deploy applications and services (Nginx config, process management, etc.)
* System administration and troubleshooting

![](https://cdn.link-ai.tech/doc/20260203121008.png)


# browser - Browser
Source: https://docs.cowagent.ai/tools/browser

The browser tool drives Chromium to navigate, click, type and extract content, including JavaScript-rendered pages, using compact DOM snapshots. Includes setup for Linux, macOS and Windows.

Control a Chromium browser for web navigation, element interaction and content extraction. Supports JavaScript-rendered pages and uses a compact DOM snapshot so the Agent can efficiently understand page structure.

## Installation

**CLI install (recommended)**

```bash theme={null}
cow install-browser
```

This command will:

* Install the `playwright` Python package (with auto-fallback for older systems)
* Install system dependencies on Linux
* Download the Chromium browser (Linux servers automatically use the headless build)
* Detect China-mainland networks and use mirror acceleration

**Manual install**

```bash theme={null}
pip install playwright
playwright install chromium
```

On Linux servers, install system dependencies as well:

```bash theme={null}
sudo playwright install-deps chromium
```

On older systems (e.g. Ubuntu 18.04, glibc \< 2.28), install a compatible version:

```bash theme={null}
pip install playwright==1.28.0
python -m playwright install chromium
```

To accelerate the Chromium download from China:

```bash theme={null}
export PLAYWRIGHT_DOWNLOAD_HOST=https://registry.npmmirror.com/-/binary/playwright
python -m playwright install chromium
```

> [!NOTE]
>
> 1. Supported on Ubuntu 20.04+, Debian 10+, macOS and Windows. Older systems such as Ubuntu 18.04 will fall back to a compatible version automatically.
> 2. The browser tool has heavy dependencies (\~300MB) and is optional. For lightweight web content retrieval, use the `web_fetch` tool.

> [!NOTE]
>
> **Desktop client users**: playwright is bundled in the installer, no separate install needed. On first use of the browser tool:
>
> * If **Google Chrome / Edge** is installed, it drives the system browser directly with **no download** (recommended);
> * Otherwise, send `/install-browser` in chat to download a lightweight browser engine into `~/.cow`.

## Workflow

A typical browser workflow for the Agent:

1. **`navigate`** — Open the target URL
2. **`snapshot`** — Get a compact DOM with auto-numbered interactive elements (`ref`)
3. **`click` / `fill` / `select`** — Operate elements by `ref`
4. **`snapshot`** — Snapshot again to verify the result

## Supported Actions

| Action | Description | Key parameters |
| - | - | - |
| `navigate` | Open URL | `url` |
| `snapshot` | Get structured page text (primary way) | `selector` (optional) |
| `click` | Click an element | `ref` or `selector` |
| `fill` | Fill text into an input | `ref` or `selector`, `text` |
| `select` | Select a dropdown option | `ref` or `selector`, `value` |
| `scroll` | Scroll the page | `direction` (up/down/left/right) |
| `screenshot` | Save a screenshot to the workspace | `full_page` |
| `wait` | Wait for an element or timeout | `selector`, `timeout` |
| `press` | Press a key (Enter, Tab, etc.) | `key` |
| `back` / `forward` | Browser back / forward | - |
| `get_text` | Get an element's text content | `selector` |
| `evaluate` | Run JavaScript | `script` |

## Use Cases

* Access a URL to retrieve dynamic page content
* Fill in forms and log in
* Operate web elements (click buttons, select options, etc.)
* Verify the result of a deployed web page
* Scrape content that requires JS rendering

## Run Mode

The browser picks a mode based on the runtime environment:

| Environment | Mode |
| - | - |
| macOS / Windows | Headed (browser window visible) |
| Linux desktop (with DISPLAY) | Headed |
| Linux server (no DISPLAY) | Headless |

You can override it in `config.json`:

```json theme={null}
{
  "tools": {
    "browser": {
      "headless": true
    }
  }
}
```

## Browser Engine

The browser engine is selected automatically, no configuration needed:

1. If **Google Chrome / Edge** is detected on the machine, it drives the system browser directly, with **no Chromium download**, using real browser fingerprints;
2. Otherwise it falls back to the Chromium engine downloaded into `~/.cow` via `install-browser`.

Both use the persistent login below and behave identically.

## Persistent Login

**Log in to a target site once and the Agent can keep using it.** Two ways are supported:

### Option 1: Persistent mode (default)

Works out of the box. Login state is saved under `~/.cow/browser_profile`. No configuration needed.

To disable persistence and start with a clean environment every time:

```json theme={null}
{
  "tools": {
    "browser": {
      "persistent": false
    }
  }
}
```

### Option 2: CDP mode (attach to real Chrome)

Have the Agent connect to a separately launched real Chrome (instead of the Chromium bundled with Playwright) for full browser fingerprints. Useful for sites with strict bot detection.

Launch Chrome with a debugging port and a dedicated user data directory:

**macOS**

```bash theme={null}
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.cow/chrome-cdp"
```

**Linux**

```bash theme={null}
google-chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.cow/chrome-cdp"
```

**Windows**

```powershell theme={null}
& "C:\Program Files\Google\Chrome\Application\chrome.exe" `
  --remote-debugging-port=9222 `
  --user-data-dir="$env:USERPROFILE\.cow\chrome-cdp"
```

Then point the Agent at the endpoint in `config.json`:

```json theme={null}
{
  "tools": {
    "browser": {
      "cdp_endpoint": "http://localhost:9222"
    }
  }
}
```

> [!NOTE]
>
> Chrome 137+ requires `--remote-debugging-port` to be paired with a dedicated `--user-data-dir`. As a result, the CDP-launched Chrome **cannot directly reuse the login state of your daily Chrome**; you'll need to log in once inside this dedicated profile.


# agent_delegate - Delegation
Source: https://docs.cowagent.ai/tools/delegate

The agent_delegate tool lets one agent hand a task to another resident agent in a team session, which answers from its own workspace, memory and skills. Available only with two or more agents.

`agent_delegate` lets one Agent hand a task to another Agent in the session. The delegate is a persistent, full member with its own workspace, memory, skills, and sessions; it answers within its own environment, and the result returns to the caller rather than being sent to the user directly.

This is the underlying capability behind [Agent team](/multi-agent/team) collaboration. For how a team is formed and how the lead Agent decides to delegate in a group chat, see the team documentation.

> [!NOTE]
>
> `agent_delegate` appears only in a team session, that is, when the session has two or more enabled Agents. It is not visible in a single-Agent deployment.

## Differences from Sub-Agents

| | [Sub-Agent](/multi-agent/subagent) | Delegation |
| - | - | - |
| Lifecycle | Created for one task, then discarded | Persistent Agent, configured in advance |
| Workspace | Shared with the caller | Independent |
| Memory | Has none of its own | Independent |
| Identity | Anonymous | Appears in the Agent list, can bind to channels |

Use a sub-Agent when you need to parallelize your own work. Use delegation only when the task genuinely belongs to someone else, that is, the Agent that owns that codebase, that knowledge base, or that customer relationship.

## Synchronous Execution

Delegation hands off the task, waits for the other Agent to answer, and then returns the reply. The call blocks until the other Agent finishes or the time budget runs out, so there is no status to poll and no handle to track.

```
agent_delegate(agent_id="research", task="...")
  -> { status: "done", content: "..." }
```

Under the hood, this run is recorded in the target's workspace with the delegating run as its parent, so a delegation chain can be traced from either end.

## Who Can Be Delegated To

The eligible targets are the members of the current session. Delegation is always confined to the session and never hands a task to an Agent outside it, even if the allowlist would otherwise permit it. If the target is not a session member, the tool rejects the call and lists the targets that are actually available.

## Parameters

| Parameter | Description |
| - | - |
| `agent_id` | The ID of a session member |
| `task` | A self-contained task description the other Agent can act on without seeing this session |

## Boundaries

Delegation happens between full Agents, so it comes with boundaries:

| Boundary | Description |
| - | - |
| Membership | The target must be a member of the current session |
| Allowlist | Who may reach whom; if unset, any Agent may delegate to any other |
| Cycles | An Agent already in the chain cannot be delegated to again |
| Depth | The maximum number of hops allowed in a chain |
| Length | The upper limit on the text of a single task |
| Time budget | The maximum time a single delegation run may take before it is abandoned |

## Configuration

```json theme={null}
{
  "agent_delegation": {
    "enabled": true,
    "allowed_targets": {
      "assistant": ["research", "support"],
      "research": []
    },
    "max_depth": 3,
    "timeout_seconds": 600,
    "max_message_chars": 8000
  }
}
```

| Field | Default | Meaning |
| - | - | - |
| `enabled` | `true` | Set to `false`, or set the whole block to `false`, to not provide the tool at all |
| `allowed_targets` | Unset | A mapping from a source Agent ID to the IDs it may reach, with `"*"` meaning any. If unset, all combinations are allowed. Targets are further confined to the members of the current session |
| `max_depth` | `3` | The number of delegation hops in a chain (1-8) |
| `timeout_seconds` | `600` | The time budget for a single delegation run (0.01-3600); a local run is cancelled when it expires |
| `max_message_chars` | `8000` | The length limit for a single delegation task |

An Agent configured with an empty array, like `"research"` above, can be delegated to but cannot delegate further.


# edit - File Edit
Source: https://docs.cowagent.ai/tools/edit

The edit tool changes files by exact text replacement, sending only the changed part. Matches must be unique unless replaceAll is set; it can append to the end and runs safety checks first.

Edit files via precise text replacement. Unlike `write`, which replaces the whole file, `edit` only sends the part being changed - faster, and less likely to disturb the rest of the file, so prefer it when modifying an existing file. If `oldText` is empty, appends to the end of the file.

## Dependencies

No extra dependencies, available by default.

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `path` | string | Yes | File path |
| `oldText` | string | Yes | Original text to replace, must match the file exactly including whitespace (empty to append) |
| `newText` | string | Yes | Replacement text |
| `replaceAll` | boolean | No | Replace every occurrence, default false |

By default `oldText` must be **unique** in the file: if it occurs more than once the edit fails and asks for more surrounding context, so the wrong spot is not changed. Set `replaceAll=true` when every occurrence really should be replaced.

> [!NOTE]
>
> Each line returned by `read` carries a line-number prefix like `12|`. Those are display aids, not file content - do not include them in `oldText` / `newText`.

## Safety checks

A few checks run before writing, and report back in the result:

* **Modified elsewhere**: if the file changed after the Agent last read it, the result carries a warning so another program's changes are not silently overwritten.
* **Syntax check**: if the edited content is JSON / YAML / TOML and fails to parse, the write is **refused** and the file is left untouched - these formats are corrupt when half-written. Source files (`.py`, for example) only warn, and only when this edit introduced a new syntax error.
* **Credential protection**: `~/.cow/.env`, which holds API keys, cannot be modified through this tool. Use the `env_config` tool instead.

## Use Cases

* Modify specific parameters in configuration files
* Fix bugs in code
* Insert content at specific positions in files


# env_config - Environment
Source: https://docs.cowagent.ai/tools/env-config

The env_config tool manages API keys and other secrets in the workspace .env file through chat, with masking built in. Saved keys are injected into the bash tool's environment automatically.

Manage environment variables (API keys and secrets) in the workspace `.env` file, with secure conversational updates. Built-in security protection and desensitization.

## Dependencies

| Dependency | Install Command |
| - | - |
| `python-dotenv` ≥ 1.0.0 | `pip install python-dotenv>=1.0.0` |

Included when installing optional dependencies: `pip3 install -r requirements-optional.txt`

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `action` | string | Yes | Operation type: `get`, `set`, `list`, `delete` |
| `key` | string | No | Environment variable name |
| `value` | string | No | Environment variable value (only for `set`) |

## Usage

Tell the Agent what key you need to configure, and it will automatically invoke this tool:

* "Configure my BOCHA\_API\_KEY"
* "Set OPENAI\_API\_KEY to sk-xxx"
* "Show configured environment variables"

Configured keys are automatically injected into the `bash` tool's execution environment.

![](https://cdn.link-ai.tech/doc/20260202234939.png)


# Tools Overview
Source: https://docs.cowagent.ai/tools/index

Overview of CowAgent's built-in tools for files, search, shell, sending files, memory, secrets, web fetching, scheduling and multi-agent work, plus optional browser, web search, vision and MCP.

Tools are the core capability for Agent to access operating system resources. The Agent intelligently selects and invokes tools based on task requirements, performing file operations, command execution, web search, scheduled tasks, and more. Tools are implemented in the `agent/tools/` directory.

## Built-in Tools

The following tools are available by default with no extra configuration:

> **[read - File Read](/tools/read)**
>
> Read file content, supports text, images, PDF

> **[write - File Write](/tools/write)**
>
> Create or overwrite files

> **[edit - File Edit](/tools/edit)**
>
> Edit files via precise text replacement

> **[ls - Directory List](/tools/ls)**
>
> List directory contents

> **[search\_files - File Search](/tools/search-files)**
>
> Search file contents, or find files by name

> **[bash - Terminal](/tools/bash)**
>
> Execute system commands

> **[send - File Send](/tools/send)**
>
> Send files or images to user

> **[memory - Memory](/tools/memory)**
>
> Search and read long-term memory

> **[agent\_delegate - Delegation](/tools/delegate)**
>
> Hand a task to another Agent in the session

> **[subagent - Sub-Agent](/tools/subagent)**
>
> Create temporary sub-Agents to run independent tasks in parallel

## Optional Tools

The following tools require additional dependencies or API key configuration:

> **[env\_config - Environment](/tools/env-config)**
>
> Manage API keys and secrets

> **[scheduler - Scheduler](/tools/scheduler)**
>
> Create and manage scheduled tasks

> **[web\_search - Web Search](/tools/web-search)**
>
> Search the internet for real-time information

## MCP Tools

Integrate thousands of community tools (maps, GitHub, Notion, etc.) via the [Model Context Protocol](https://modelcontextprotocol.io). Configure `mcp.json` once, ready to use:

> **[MCP - External Tool Ecosystem](/tools/mcp)**
>
> Supports standard stdio / SSE transports. Hot-reload, zero code changes.


# ls - Directory List
Source: https://docs.cowagent.ai/tools/ls

The ls tool lists one directory, sorted alphabetically with hidden files, truncating past 500 entries or 50 KB. Use it to browse a project; use search_files to find files recursively.

List the contents of **a single directory**, sorted alphabetically, directories suffixed with `/`, includes hidden files.

## Dependencies

No extra dependencies, available by default.

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `path` | string | No | Directory path, defaults to the workspace root; relative paths are based on workspace directory |
| `limit` | integer | No | Maximum entries to return, default 500 |

## Example output

```
__init__.py
__pycache__/
credentials.py
diff.py
file_state.py
```

Output is truncated beyond 500 entries or 50KB.

> [!NOTE]
>
> `ls` looks at one level only, answering "what is in this directory". To find a file recursively across directories, use [`search_files`](/tools/search-files) with `target=files`.

## Use Cases

* Browse project structure
* Check whether a directory exists and what is in it
* See what is already alongside a file before writing


# MCP Tools
Source: https://docs.cowagent.ai/tools/mcp

CowAgent supports the Model Context Protocol (MCP). Add servers in mcp.json or the console and the agent can call thousands of community MCP tools just like built-in ones.

CowAgent supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io), allowing the Agent to directly invoke tens of thousands of community MCP tools. Configure `mcp.json` once and the tools are exposed to the LLM in exactly the same way as built-in tools — automatically selected and invoked.

## Web and Desktop Console

The **MCP Tools** section of the Capabilities page in the **web console** and **desktop app** can add, edit, disable, and remove MCP servers without editing `mcp.json` by hand.

* **Form or JSON**: fill in the form, or paste a standard `mcpServers` config in JSON mode (several servers at once), for example `{"mcpServers":{"fetch":{"command":"uvx","args":["mcp-server-fetch"]}}}`.
* **Test connection**: checks that each server is reachable and lists its tools. Saving runs the same check first; if it fails, fix the config or choose **Save anyway** (for servers that require authorization after saving).
* **Storage**: written to the current Agent's `mcp.json`, in the same format as Claude Desktop / Cursor.
* **Immediate effect**: changes apply from the next message, with no restart.

stdio, SSE, and streamable HTTP transports are all supported. A disabled server stays in the file but is not booted.

![Add an MCP tool](https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/en/mcp-config.png)

## Configuration File

CowAgent reads `~/cow/mcp.json`. If the file does not exist, no MCP tools are loaded — and no error is raised.

For Docker deployments, the official `docker-compose.yml` already mounts the host's `./cow` directory to `/home/agent/cow` inside the container (i.e. the container user's `~/cow`). Just drop `mcp.json` into the host's `./cow/` directory and it will take effect.

### Standard Format

Fully compatible with the MCP community standard, identical to Claude Desktop / Cursor:

```json theme={null}
{
  "mcpServers": {
    "<server-name>": {
      "command": "npx",
      "args": ["-y", "some-mcp-package"],
      "env": {
        "API_KEY": "your-key-here"
      }
    }
  }
}
```

| Field | Required | Description |
| - | - | - |
| `command` | stdio | Executable to launch the server (e.g. `npx`, `python`, `uvx`) |
| `args` | No | Arguments passed to `command` |
| `env` | No | Environment variables for the subprocess, commonly used for API keys |
| `url` | SSE / Streamable HTTP | Remote endpoint URL (alternative to `command`) |
| `type` | Remote | Remote transport type: `sse` or `streamable-http` (defaults to `sse`) |
| `headers` | No | Extra HTTP headers for remote requests (e.g. `Authorization`); Streamable HTTP only |
| `scope` | No | OAuth scope, only for remote servers that require OAuth authorization (optional) |
| `tool_name_prefix` | No | String prepended to this server's tool names in CowAgent, e.g. `myserver_`. Defaults to an empty string. Include any separator in the prefix. Use a unique prefix to avoid collisions with built-in tools or other servers. |
| `disabled` | No | When `true`, this server is skipped — handy for temporary disabling |

### Full Example

```json theme={null}
{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}
```

* **fetch**: Generic web page fetcher that returns page text content. No API key required.
* **github**: Access GitHub repos, issues, PRs, etc. Requires a Personal Access Token.

### Streamable HTTP with a Bearer Key

For a remote server that authenticates with a static API key, set `type` explicitly — a remote URL without it falls back to `sse` — and pass the key in `headers`:

```json theme={null}
{
  "mcpServers": {
    "my-remote-tools": {
      "type": "streamable-http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

* Header values are sent literally: `${API_KEY}` is **not** expanded from the environment.
* The key is stored as plain text, so keep `mcp.json` out of version control.
* An `Authorization` header selects static authentication and skips the OAuth flow below, even when the value is wrong.

## Let the Agent Configure It for You

CowAgent ships with `read` / `write` / `edit` tools, so **you can simply send the MCP config to the Agent and ask it to write the file**:

For example:

```markdown theme={null}
Add this MCP to ~/cow/mcp.json:

{"mcpServers":{"fetch":{"command":"uvx","args":["mcp-server-fetch"]}}}
```

The Agent will:

1. Read the existing MCP config and merge the new server entry, preserving existing ones
2. Hot-reload the new MCP server, so the corresponding tools become available on the next message

> [!NOTE]
>
> Commands in `mcp.json` start with the Agent process's privileges, so the Agent may only change `mcp.json` in a **full-access** session. Read-only and workspace-write sessions refuse it: switch the session's permission, or add the server from the console.

## Web Authorization (OAuth)

Some remote MCP servers require OAuth web authorization, and connecting to them directly returns `401`. CowAgent has a built-in standard OAuth flow, so **no manual token is needed** — just configure the server normally, for example:

```json theme={null}
{
  "mcpServers": {
    "xmind": {
      "type": "streamable-http",
      "url": "https://app.xmind.com/api/mcp"
    }
  }
}
```

When a server returns `401` on its first load, authorization starts automatically: running locally **opens the browser automatically**, while server deployments **print the authorization link to the log** for you to open in a browser. Once you approve, the server comes online immediately; tokens are refreshed automatically on expiry, so you never have to re-authorize.

* **Requires the web service**: The authorization callback is received by the web console (default port `9899`), so the Web channel must be running.
* **Credential storage**: Tokens are persisted in `~/.cow/mcp_oauth.json` and reused across restarts.
* **Callback URL**: Defaults to `http://127.0.0.1:9899/mcp/oauth/callback`. If deployed on a server with the authorizing browser on another device, set `mcp_oauth_redirect_base` in `config.json` (e.g. `http://YOUR_IP:9899`).

## How It Works

* **Async loading at startup**: All servers configured in `mcp.json` are loaded asynchronously in the background, never blocking the main loop — chat is usable immediately.
* **Hot reload**: When you or the Agent modifies `mcp.json`, changed servers are automatically reloaded after the current message — no need to restart cow.
* **Flat exposure**: Each method exposed by an MCP server appears as an individual tool. The LLM picks one directly without a second-stage decision.

## Supported Transports

| Transport | Description | Config Field |
| - | - | - |
| **stdio** | Subprocess communication. The most common option, with the richest community ecosystem. | `command` + `args` |
| **SSE** | HTTP Server-Sent Events. Legacy remote transport. | `url` (default) |
| **Streamable HTTP** | New unified remote transport, gradually replacing SSE. | `type: "streamable-http"` + `url` |

## Troubleshooting

| Symptom | What to Check |
| - | - |
| Agent has no MCP tools after startup | Verify that `~/cow/mcp.json` exists and contains valid JSON |
| A specific server fails to load | Look for `[MCP] Server 'xxx' load failed` in startup logs — usually missing dependencies or API keys |
| Changes to `mcp.json` aren't applied | Changes take effect on **the next message**. If the server config didn't actually change (e.g. only comments edited), no restart is triggered |
| Docker deployment | Make sure host's `./cow` is mounted to `/home/agent/cow` in the container, then just drop `mcp.json` into host's `./cow/`. Or just ask the Agent to do it |

## Recommended MCP Marketplaces

You can browse third-party MCP marketplaces and copy a JSON config to use directly, for example:

* [mcp.so](https://mcp.so) — Global MCP service index
* [ModelScope MCP Hub](https://modelscope.cn/mcp) — ModelScope's MCP hub, more reliable from mainland China

Any MCP server that follows the standard protocol (stdio / SSE / Streamable HTTP) integrates with CowAgent out of the box.


# memory - Memory & Knowledge
Source: https://docs.cowagent.ai/tools/memory

The memory tools, memory_search and memory_get, search long-term memory and the knowledge base with hybrid keyword and vector retrieval and read specific files when the agent needs past context.

The memory tool contains two sub-tools: `memory_search` (search memory) and `memory_get` (read memory or knowledge files).

When the [knowledge base](/knowledge) feature is enabled, both tools also support accessing files under the `knowledge/` directory.

## Dependencies

No extra dependencies, available by default. Managed by the Agent Core memory system.

## memory\_search

Search historical memory and knowledge base content with hybrid keyword and vector retrieval.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `query` | string | Yes | Search query |

## memory\_get

Read the content of a specific memory or knowledge file.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `path` | string | Yes | Relative path to the file (e.g. `MEMORY.md`, `memory/2026-01-01.md`, `knowledge/concepts/rag.md`) |
| `start_line` | integer | No | Start line number |
| `end_line` | integer | No | End line number |

## How It Works

The Agent automatically invokes memory tools in these scenarios:

* When the user shares important information → stores to memory
* When historical context is needed → searches relevant memory
* When conversation reaches a certain length → extracts summary for storage
* When discussing domain knowledge → retrieves relevant pages from the knowledge base

> [!NOTE]
>
> When `knowledge` is set to `false` in config, the tool descriptions and search scope automatically adjust to include only memory files.


# read - File Read
Source: https://docs.cowagent.ai/tools/read

The read tool reads text, PDF, Word, Excel and PowerPoint files and image metadata with line numbers, up to 2,000 lines or 50 KB per call, with offset paging and credential protection.

Read file content. Supports text files, PDF, Office documents (Word / Excel / PPT), images (returns metadata), and more.

## Dependencies

No extra dependencies, available by default.

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `path` | string | Yes | File path, relative paths are based on workspace directory |
| `offset` | integer | No | Start line number (1-indexed), negative values read from the end, e.g. `-50` for the last 50 lines |
| `limit` | integer | No | Number of lines to read |
| `pages` | string | No | PDF only: page range such as `3`, `1-5`, `10-`. Defaults to the first 20 pages, at most 20 pages per call |

## Output format

Each line is prefixed with its line number and a pipe, so the Agent can locate positions and so output matches `search_files`:

```
1|from config import conf
2|
3|def main():
4|    print(conf())
```

> [!NOTE]
>
> The line numbers are display aids, not file content. When editing with `edit`, do not include prefixes like `1|` in `oldText` / `newText` - they will be rejected.

A single read is capped at 2000 lines or 50KB; beyond that the output is truncated and ends with a hint on using `offset` to continue.

## Credential protection

`~/.cow/.env`, which holds API keys, cannot be read through this tool. Use the `env_config` tool instead.

## Use Cases

* View configuration files, log files
* Read code files for analysis
* Extract text from PDF, Word and Excel files
* Check image/video file info


# scheduler - Scheduler
Source: https://docs.cowagent.ai/tools/scheduler

The scheduler tool creates and manages scheduled tasks in plain language: one-off, interval or cron schedules that send a fixed message or run an agent task, with a run-now option in the console.

Create and manage dynamic scheduled tasks with flexible scheduling and execution modes.

## Dependencies

| Dependency | Install Command |
| - | - |
| `croniter` ≥ 2.0.0 | `pip install croniter>=2.0.0` |

Included in core dependencies: `pip3 install -r requirements.txt`

## Scheduling Modes

| Mode | Description |
| - | - |
| One-time | Execute once at a specified time |
| Fixed interval | Repeat at fixed time intervals |
| Cron expression | Define complex schedules using Cron syntax |

## Execution Modes

* **Fixed message**: Send a preset message when triggered
* **Agent dynamic task**: Agent intelligently executes the task when triggered

## Usage

Create and manage scheduled tasks with natural language:

* "Send me a weather report every morning at 9 AM"
* "Check server status every 2 hours"
* "Remind me about the meeting tomorrow at 3 PM"
* "Show all scheduled tasks"

## Test-run an existing task

Open the task in the authenticated Web console or Desktop app and click **Run
now**. After you confirm the delivery, CowAgent queues one immediate execution
to the task's configured channel and receiver. This user-initiated action is not
exposed to the agent's scheduler tool.

Manual execution works for disabled tasks and does not enable, delete, or
reschedule the task. Its original `next_run_at` remains unchanged. A task cannot
be run manually while the same task is already executing on schedule.

![](https://cdn.link-ai.tech/doc/20260202195402.png)

## Results injected into the conversation

Scheduled tasks run inside an isolated session (so internal planning and tool calls do not pollute the user's chat), but the **final output** is written back to the user's real session as a message pair. You can directly follow up — e.g. "expand on point 2 from earlier".

**Default policy**

* Output of Agent dynamic tasks is injected into the conversation
* Fixed-message tasks are not injected by default (configurable)
* Each session keeps the most recent **3 pairs** of scheduler messages; older pairs are pruned automatically. Regular user messages are unaffected

**Configuration**

| Key | Default | Description |
| - | - | - |
| `scheduler_inject_to_session` | `true` | Master switch |
| `scheduler_inject_max_per_session` | `3` | Max scheduler message pairs kept per session |
| `scheduler_inject_send_message` | `false` | Whether to also inject fixed-message tasks |

```json theme={null}
{
  "scheduler_inject_to_session": true,
  "scheduler_inject_max_per_session": 3,
  "scheduler_inject_send_message": false
}
```

## Context inside scheduled task execution

The isolated session for scheduled tasks retains a few recent runs of conversation history, so you can naturally do "compare with last time" or "continue from previous conclusion". To prevent prompts from growing unbounded for high-frequency tasks (e.g. a 5-minute monitor), history is auto-trimmed:

```
scheduler_keep_turns = max(1, agent_max_context_turns / 5)
```

`agent_max_context_turns` defaults to `30`, so each scheduled run keeps the most recent **6 turns** of history by default. Increase `agent_max_context_turns` if you need longer memory.

> [!NOTE]
>
> For group-chat scenarios (Feishu / WeCom group bots / DingTalk, etc.), the user's real `session_id` looks like `user_id:group_id` — different from `receiver`. Scheduler records the correct `session_id` when a task is created. For older `tasks.json` entries missing this field, the runtime falls back to `receiver`, matching legacy behavior.


# search_files - File Search
Source: https://docs.cowagent.ai/tools/search-files

The search_files tool searches file contents by regex or finds files by name in the workspace, with structured output, dependency folders skipped, ripgrep acceleration and Windows support.

Search files in the workspace. One tool answers two questions: **what is written in the files** (regex search inside contents) and **where is that file** (match by file name), selected with the `target` parameter.

The Agent prefers this tool over running `grep` / `find` in the terminal: it returns structured results, skips dependency directories automatically, and works the same on Windows.

## Dependencies

No extra dependencies, available by default. If [ripgrep](https://github.com/BurntSushi/ripgrep) (`rg`) is installed it is used automatically for faster searches.

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `pattern` | string | Yes | A regex when `target=content`; a file-name glob such as `*.py` when `target=files` |
| `target` | string | No | `content` searches inside files (default); `files` finds files by name |
| `path` | string | No | Where to start, defaults to the workspace root; relative paths are based on the workspace |
| `file_glob` | string | No | Limit which files are searched, e.g. `*.py`, `*.{ts,tsx}`; defaults to all (`target=content` only) |
| `output_mode` | string | No | `content` returns matching lines (default), `files` returns only file paths, `count` returns matches per file |
| `ignore_case` | boolean | No | Case-insensitive match, default false |
| `no_ignore` | boolean | No | Search content that is excluded by default, default false; see "Excluded directories" below |
| `max_results` | integer | No | Maximum results to return, default 50, capped at 500 |

## Searching contents

The default mode. Returns the file, line number and line text for each match:

```json theme={null}
{
  "matches": [
    { "file": "channel/wechat_channel.py", "line": 42, "match": "def handle_message(self, msg):" }
  ],
  "match_count": 1
}
```

When you only need to know which files matched, `output_mode=files` cuts the output down substantially.

## Finding files

With `target=files`, `pattern` is matched against the **file name**, and results are ordered **most-recently-modified first** - when several files match, the one just worked on is usually the one wanted:

```json theme={null}
{
  "files": ["websites/ai-news-report.md", "archive/ai-news-report.md"],
  "match_count": 2
}
```

A bare word (no `*` or `?`) is treated as a contains-match, so `ai-news` is equivalent to `*ai-news*` and you do not need to recall the full name.

> [!NOTE]
>
> Finding a file by name requires `target=files`. A content search for `report.md` only finds files that **mention** that name, not the file itself.

## Excluded directories

These directories are always skipped so results are not drowned out by dependencies and build output:

`.git`, `node_modules`, `__pycache__`, `.venv`, `venv`, `.mypy_cache`, `.pytest_cache`, `dist`, `build`, `.next`, `target`, `vendor`, `.tox`, `coverage`, `.idea`.

In addition, files ignored by `.gitignore` are skipped when ripgrep is installed.

When you do need to search them (inspecting third-party sources, for example), `no_ignore=true` lifts both kinds of exclusion at once. If a search returns nothing and such a directory happened to be skipped, the result carries a `notice` naming which ones.

## Use Cases

* Locate a function, config key or error message in the codebase
* Find a document, report or web page generated earlier, by name
* Count how many times a pattern occurs in the project


# send - File Send
Source: https://docs.cowagent.ai/tools/send

The send tool delivers files such as images, video, audio and documents to the user, for sharing generated code, reports, screenshots and charts directly in the current conversation.

Send files to the user (images, videos, audio, documents, etc.), used when the user explicitly requests to send/share a file.

## Dependencies

No extra dependencies, available by default.

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `path` | string | Yes | File path, can be absolute or relative to workspace |
| `message` | string | No | Accompanying message |

## Use Cases

* Send generated code or documents to the user
* Send screenshots, charts
* Share downloaded files


# subagent - Sub-Agent
Source: https://docs.cowagent.ai/tools/subagent

How the subagent tool works: pick a built-in type or define your own in subagents/ as Markdown, restrict its tools, and let sub-agents run tasks in their own context and return only the result.

`subagent` lets the lead Agent create temporary execution units during a conversation, hand an independent task to one, and get the result back after it completes the task in its own context. For the functional effect and use cases, see [Sub-Agent](/multi-agent/subagent); this page covers the tool's types, configuration, and implementation details.

## Built-in Types

A type is chosen at creation time, and it determines the system prompt and the range of available tools:

| Type | Use case | Tool range |
| - | - | - |
| `general-purpose` | Multi-step tasks that need both investigation and action: search, read, run commands, write files | All of the lead Agent's tools (except the disabled ones) |
| `explore` | Read-only investigation: find files, search code or documents, gather information from the web | `read`, `ls`, `search_files`, `web_search`, `web_fetch`, `vision`, `memory_search`, `memory_get` |

## Custom Types

Add a type by placing a `.md` file in the workspace's `subagents/` directory, in the same format as a skill:

```markdown theme={null}
---
name: research-report
description: Reads a large amount of web material on a topic and returns a short, sourced report. Use it when you need to open many pages but only need the conclusion.
tools: web_search, web_fetch, read, write
---
You are a research assistant. You receive one topic at a time and return a report.

How to work:
1. Search broadly first, then dig into the two or three most valuable sources.
2. Prefer primary sources (official docs, vendor pricing pages, original announcements) over secondhand articles.
3. Cross-check numbers, dates, and prices against a second source.

Keep the report under 400 words, containing, in order:
- Conclusion: two or three sentences answering the question
- Findings: as a list, each item ending with a source URL
- Unverified: anything that cannot be confirmed from a primary source

Write "not found" for anything you cannot find; do not fill gaps with guesses.
```

Field reference:

| Field | Description |
| - | - |
| `name` | The type name |
| `description` | The lead Agent selects a type based on this, so it should describe "when to use it" rather than "what it is" |
| `tools` | The available tools; omit it to inherit all of the lead Agent's tools |
| Body | The sub-Agent's system prompt, describing how to work and what to return |

Restricting `tools` is the most reliable constraint: a type that only has `read, ls, search_files` cannot modify any file. A type that specifies `tools` does not inherit skills; omit the field when skills are needed, and scope the work in the body instead.

The first time a workspace starts, `README.md` and `example.md.template` are generated under `subagents/`; copy the latter to a `.md` file to enable it. Templates are re-read every turn, so a new file takes effect on the next message with no restart needed.

> [!TIP]
>
> Tool names are matched exactly, and the `tools` allowlist does not include MCP tools. Omit the field when MCP tools are needed.

## Disabled Tools

The following tools are unavailable to all sub-Agents:

| Tool | Reason |
| - | - |
| `send`, `scheduler` | Would send messages to a user channel or create tasks on behalf of the lead Agent, beyond the scope of a single task |
| `env_config`, `evolution_undo` | Would modify the Agent's own configuration |
| `subagent` | Prevents infinite recursion for types that expose all tools; the actual nesting depth is controlled by `max_depth` |

## Configuration

Sub-Agents are enabled by default. You can toggle them under "Config → Agent Config" in the Web console and desktop client, and a change takes effect on the next turn with no restart needed. Finer limits are adjusted in `config.json`:

```json theme={null}
"subagent": {
  "enabled": true,
  "max_depth": 1,
  "max_concurrent": 3,
  "timeout_seconds": 300
}
```

| Parameter | Description | Default |
| - | - | - |
| `enabled` | Whether sub-Agents are enabled | `true` |
| `max_depth` | The nesting depth; `1` means only the lead Agent can create sub-Agents | `1` |
| `max_concurrent` | The maximum number of sub-Agents running in parallel per call | `3` |
| `timeout_seconds` | The total time limit for a single call, including all parallel tasks within it | `300` |

## Implementation Design

* **Context isolation**: a sub-Agent starts with an empty message history, does not load persona files, and is not connected to the memory manager. Only a single call record and the final conclusion remain in the main conversation.
* **Parallel execution**: multiple tasks in a single call run in their own threads and share one time budget; multiple calls issued in the same turn also start at the same time.
* **Halved step budget**: a sub-Agent's maximum step count is half that of the lead Agent. Its task scope is already well defined and does not need the same budget as a full conversation; when it runs out, it is asked to summarize what it has completed.
* **Traceable timeouts**: a timed-out task is cancelled and marked as timed out, and the number of results always matches the number of tasks, so the lead Agent can tell "found nothing" apart from "did not finish".
* **Presentation separate from context**: what is returned to the model is structured data, while what is shown to the user is a formatted report; both are generated from the same result, and the displayed content does not enter the model's context.


# vision - Image Understanding
Source: https://docs.cowagent.ai/tools/vision

The vision tool analyzes local images or image URLs for descriptions, OCR and object recognition, using a multimodal main model first and falling back to other configured vision models automatically.

Analyze local images or image URLs using Vision API. Supports content description, text extraction (OCR), object recognition, and more.

## Model Selection

The vision tool uses a multi-level auto-selection strategy with automatic fallback — no manual configuration required:

1. **Main model** — uses the currently configured main model for image recognition (must be a multimodal model)
2. **Other configured models** — auto-discovers other multimodal models with configured API keys as alternatives

If the current provider fails, the tool automatically tries the next one until it succeeds or all fail.

### Supported Models

| Provider | Vision Model | Notes |
| - | - | - |
| OpenAI / Compatible | Main model | All OpenAI-protocol-compatible multimodal models |
| Qwen (DashScope) | Main model | e.g. qwen3.8-flash, qwen3.7-plus, etc. |
| Claude | Main model | Anthropic native image format |
| Gemini | Main model | inlineData format |
| Doubao | Main model | doubao-seed-2-1 series natively supported |
| Kimi (Moonshot) | Main model | kimi-k2.6, kimi-k2.5 natively supported |
| ERNIE | Main model | Defaults to the multimodal main model (e.g. `ernie-5.1`); falls back to `ernie-4.5-turbo-vl` when the main model is not multimodal |
| ZhipuAI | Main model / glm-5v-turbo | glm-5.3-flash is used directly; text-only chat models fall back to glm-5v-turbo |
| MiniMax | MiniMax-M3 | Uses the selected native multimodal model |

> [!NOTE]
>
> ZhipuAI and MiniMax text-only models do not support image understanding; MiniMax-M3 is selected automatically for native multimodal input.

> When `use_linkai=true`, LinkAI's multimodal model is used by default.

## Custom Configuration

To specify the model used by Vision, configure it in `config.json`, for example:

```json theme={null}
{
    "tools": {
        "vision": {
            "model": "gpt-4.1"
        }
    }
}
```

The specified model is **used first**, and the tool automatically routes to the corresponding provider based on the model name; on failure, it falls back to other configured providers.

In most cases no configuration is needed — the tool works automatically as long as the main model supports multimodal input or any vision-capable API key is configured.

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `image` | string | Yes | Local file path or HTTP(S) image URL |
| `question` | string | Yes | Question to ask about the image |

Supported image formats: jpg, jpeg, png, gif, webp

## Use Cases

* Describe image content
* Extract text from images (OCR)
* Identify objects, colors, scenes
* Analyze screenshots and scanned documents

> [!NOTE]
>
> Images larger than 1MB are automatically compressed before upload. All images (including remote URLs) are converted to base64 for transmission to ensure compatibility with all model backends.


# web_fetch - Web Fetch
Source: https://docs.cowagent.ai/tools/web-fetch

The web_fetch tool retrieves HTTP and HTTPS URLs, extracting readable text from web pages and downloading and parsing PDF, Word and Excel files. Use the browser tool for JavaScript-rendered pages.

Fetch the content of an HTTP/HTTPS URL. Web pages are extracted as readable text; document files (PDF, Word, Excel, etc.) are downloaded and parsed automatically.

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `url` | string | Yes | HTTP/HTTPS URL (web page or document) |

## Supported file types

| Type | Formats |
| - | - |
| PDF | `.pdf` |
| Word | `.docx` |
| Text | `.txt`, `.md`, `.csv`, `.log` |
| Spreadsheet | `.xls`, `.xlsx` |
| Presentation | `.ppt`, `.pptx` |

## Use cases

* Extract readable text from a web page
* Download and parse remote documents
* Inspect API response bodies

## DeepSeek Fetch backend (opt-in)

By default `web_fetch` retrieves pages directly. Set `tools.web_fetch.provider`
to `"deepseek"` to fetch through [DeepSeek's official Fetch API](https://api-docs.deepseek.com/guides/search)
instead, which returns the page as Markdown — handy for pages the direct
backend cannot render (e.g. JavaScript-heavy sites).

```json theme={null}
{
  "tools": {
    "web_fetch": {
      "provider": "deepseek"
    }
  }
}
```

The backend uses the `deepseek_api_key` model credential (or the
`DEEPSEEK_API_KEY` environment variable). Calls are billed per
successful request (\$0.75 per 1,000), so the backend stays opt-in; `"direct"`
(the default) is free. The SSRF guard still applies: private, loopback, and
cloud-metadata URLs are rejected before any request is issued. Document
URLs (PDF, Word, etc.) are always downloaded and parsed locally.

> [!NOTE]
>
> `web_fetch` only retrieves static HTML. For pages that require JavaScript rendering (such as SPAs), use the `browser` tool instead.


# web_search - Web Search
Source: https://docs.cowagent.ai/tools/web-search

The web_search tool finds real-time information, news and research through multiple backends including Bocha, Baidu Qianfan, Zhipu, Tavily, Serply and SearXNG, configurable in the web console.

Search the internet for real-time information, news, research, and more. Supports ten backends: Bocha, ERNIE, GLM, LinkAI, DeepSeek, AnySearch, Serply, Tavily, SearXNG, and Keenable. Keenable also has a keyless anonymous mode that you turn on explicitly; each backend is used once its credentials (or that opt-in) are configured.

> [!TIP]
>
> It is recommended to configure providers and routing strategy visually from the "Model Management → Search" panel in the [Web console](/channels/web), without manually editing the configuration file.

## Providers

| Provider | Credential | Apply |
| - | - | - |
| Bocha | `tools.web_search.bocha_api_key` | [Bocha Open Platform](https://open.bochaai.com/) |
| ERNIE | Reuses `qianfan_api_key` | [Qianfan Console](https://cloud.baidu.com/doc/qianfan/s/2mh4su4uy) |
| Zhipu | Reuses `zhipu_ai_api_key` | [Zhipu Open Platform](https://docs.bigmodel.cn/cn/guide/tools/web-search) |
| LinkAI | Reuses `linkai_api_key` | [LinkAI Console](https://link-ai.tech/console/interface?utm_source=cowagent\&utm_medium=docs\&utm_campaign=tools-web-search) |
| DeepSeek | Reuses `deepseek_api_key` | [DeepSeek API Docs](https://api-docs.deepseek.com/guides/search) |
| AnySearch | Optional `tools.web_search.anysearch_api_key`, or `anysearch_anonymous: true` for keyless use | [AnySearch Console](https://anysearch.com/) |
| Serply | `tools.web_search.serply_api_key` | [Serply](https://serply.io) ([docs](https://serply.io/docs)) |
| Tavily | `tools.web_search.tavily_api_key` | [Tavily](https://tavily.com) |
| SearXNG | `tools.web_search.searxng_url` (self-hosted instance URL, no API key needed) | [SearXNG](https://docs.searxng.org/) |
| Keenable | Optional `tools.web_search.keenable_api_key`, or `keenable_anonymous: true` for keyless use | [Keenable](https://keenable.ai) |

Bocha, Serply, and Tavily require dedicated keys; Zhipu, ERNIE, LinkAI, and DeepSeek reuse the corresponding model's API key — configuring the model automatically grants search capability. SearXNG is self-hosted and only requires an instance URL. AnySearch is opt-in for keyless use: set `tools.web_search.anysearch_anonymous` to `true` (or save it with an empty key in the console's Search panel) to call it anonymously; configuring `tools.web_search.anysearch_api_key` (falling back to the `ANYSEARCH_API_KEY` environment variable when unset) needs no opt-in, and quota and permissions follow the AnySearch server. Keenable is opt-in: set `tools.web_search.keenable_anonymous` to `true` (or save it with an empty key in the console's Search panel) and it calls a public endpoint with per-IP rate limits (10 requests/s, 1000/hour); an optional `keenable_api_key` (or `KEENABLE_API_KEY`) lifts them and needs no opt-in.

## Routing Strategy

```json theme={null}
{
  "tools": {
    "web_search": {
      "strategy": "auto",
      "provider": ""
    }
  }
}
```

* `auto` (default): the Agent intelligently picks among configured providers and may call multiple providers in a single task to gather more comprehensive results; when none is specified, falls back through `deepseek → bocha → qianfan → zhipu → linkai → anysearch → serply → tavily → searxng → keenable`.

* `fixed`: always use the provider specified in `provider`; falls back to the auto order if that provider's credentials are missing.

## Tool Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `query` | string | Yes | Search keywords |
| `count` | integer | No | Number of results (1–50, default 10) |
| `freshness` | string | No | Time range: `noLimit` (default), `oneDay`, `oneWeek`, `oneMonth`, `oneYear`, or date range like `2025-01-01..2025-02-01` |
| `summary` | boolean | No | Whether to return page summaries (default false) |
| `provider` | string | No | Available when multiple providers are configured under the `auto` strategy; used to switch provider for a single call |

> [!NOTE]
>
> If none of the ten providers is configured (no key, no instance URL, and no anonymous opt-in), this tool is not registered with the Agent.


# write - File Write
Source: https://docs.cowagent.ai/tools/write

The write tool creates or overwrites files and their parent folders. It warns about external changes and rejects invalid JSON, YAML or TOML before writing; use edit for changes to existing files.

Write content to a file. Creates the file if it doesn't exist, overwrites the whole file if it does. Automatically creates parent directories.

Prefer `edit` when modifying an existing file - it only sends the text being changed. Use `write` for new files and complete rewrites.

## Dependencies

No extra dependencies, available by default.

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `path` | string | Yes | File path |
| `content` | string | Yes | Content to write |

## Safety checks

A few checks run before writing, and report back in the result:

* **Modified elsewhere**: if the file changed after the Agent last read it, the result carries a warning so another program's changes are not silently overwritten.
* **Syntax check**: if the content is JSON / YAML / TOML and fails to parse, the write is **refused** and the file is left untouched - these formats are corrupt when half-written, and this also catches truncated model output. Source files (`.py`, for example) only warn, and only when this write introduced a new syntax error.
* **Credential protection**: `~/.cow/.env`, which holds API keys, cannot be written through this tool. Use the `env_config` tool instead.

## Use Cases

* Create new code files or scripts
* Generate configuration files
* Save processing results


# v2.0.0
Source: https://docs.cowagent.ai/releases/v2.0.0

CowAgent 2.0: the jump from chatbot to super AI assistant, with autonomous task planning, long-term memory with hybrid search, 10+ built-in tools, a skill engine and one-step install scripts.

CowAgent 2.0 is a comprehensive upgrade from a chatbot to an **AI super assistant** — capable of autonomous thinking and task planning, long-term memory, operating computers, and creating and executing skills.

**Release Date**: 2026.02.03 | [GitHub Release](https://github.com/zhayujie/CowAgent/releases/tag/2.0.0)

## Key Updates

### Agent Core

* **Complex Task Planning**: Autonomous planning with multi-turn reasoning
* **Long-term Memory**: Persistent memory with keyword and vector search
* **Built-in Tools**: 10+ tools including file ops, Bash, browser, scheduler
* **Web search**: Built-in `web_search` tool, supports multiple search engines, configure corresponding API key to use
* **Skills System**: Skill engine with built-in and custom skill support
* **Security & Cost**: Secret management, prompt controls, token limits

### Other

* **Channels**: Feishu/DingTalk WebSocket support, image/file messages
* **Models**: claude-sonnet-4-5, gemini-3-pro-preview, glm-4.7, MiniMax-M2.1, qwen3-max
* **Deployment**: One-click install, configure, run, and management script

## Long-term Memory

![](https://cdn.link-ai.tech/doc/20260203000455.png)

## Task Planning & Tools

![](https://cdn.link-ai.tech/doc/20260202181130.png)

![](https://cdn.link-ai.tech/doc/20260203121008.png)

![](https://cdn.link-ai.tech/doc/20260202195402.png)

## Skills System

![](https://cdn.link-ai.tech/doc/20260202202247.png)

![](https://cdn.link-ai.tech/doc/20260202213219.png)

![](https://cdn.link-ai.tech/doc/20260202234350.png)

## Contributing

Welcome to [submit feedback](https://github.com/zhayujie/CowAgent/issues) and [contribute code](https://github.com/zhayujie/CowAgent/pulls).