# DingTalk
Source: https://docs.cowagent.ai/channels/dingtalk
Integrate CowAgent into DingTalk application
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:
2. Click **Add App Capability**, select **Robot** capability and click **Add**:
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:
4. Click **Version Management & Release**, create a new version and publish:
## 2. Project Configuration
1. Click **Credentials & Basic Info**, get the `Client ID` and `Client Secret`:
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
```
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:
## 3. Usage
Chat privately with the robot or add it to an enterprise group to start a conversation:
# Discord
Source: https://docs.cowagent.ai/channels/discord
Integrate CowAgent with a Discord Bot
> 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).
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.
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.
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
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.
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.) |
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
Integrate CowAgent into Feishu via a custom enterprise app
> 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.
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.
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**:
2. In **Add App Capabilities**, add the **Bot** capability:
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
```
4. Get `App ID` and `App Secret` from **Credentials & Basic Info**:
**Step 2: Connect to CowAgent**
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.
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:
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:
## 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 |
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
Channels supported by CowAgent and their capability matrix
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
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 QQ Bot (WebSocket long connection)
> 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.
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**:
2.Fill in the bot name, avatar, and other basic information to complete the creation:
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)
## 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.
### 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:
Chat example:
## 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
Integrate CowAgent with a Slack App
> 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-`.
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
```
`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
```
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-`.
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
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.
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 |
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
Integrate CowAgent with Telegram via the Bot API
> 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.
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`
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
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.
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 `) |
| `/logs` | View recent logs |
| `/version` | Show version |
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
Use CowAgent through the Web Console
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_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_token` | Independent Bearer token for the OpenAI-compatible API. Leave empty to disable the API | `""` |
| `web_session_expire_days` | Login session validity in days | `30` |
| `web_file_serve_root` | Root directory the web console can directly read/send files from. Defaults to the user home dir and agent workspace only; set to `/` to allow the whole filesystem | `"~"` |
| `enable_thinking` | Whether to enable deep thinking mode | `false` |
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://:9899`
Ensure the server firewall and security group allow the corresponding port.
## OpenAI-Compatible API
Set `external_api_token` to enable `POST /v1/chat/completions`. This token is
independent from `web_password` and Web Console login sessions.
The first release accepts text messages and uses CowAgent's configured Agent and
model. The request `model` is required for OpenAI client compatibility and is
echoed in the response; it does not select a CowAgent model. The latest non-empty
user message is submitted to the Agent. Set `conversation_id`, or `user` as a
fallback, to reuse a stable CowAgent session across requests. Requests without
either field use an isolated session.
Non-streaming request:
```bash theme={null}
curl http://localhost:9899/v1/chat/completions \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "cowagent",
"conversation_id": "example-conversation",
"messages": [{"role": "user", "content": "Summarize this workspace."}]
}'
```
The standard response is returned in `choices[0].message.content`. CowAgent adds
`reasoning_content` and `tool_trace` to the message when those traces are
available.
Streaming request:
```bash theme={null}
curl -N http://localhost:9899/v1/chat/completions \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "cowagent",
"stream": true,
"user": "example-user",
"messages": [{"role": "user", "content": "Inspect the workspace."}]
}'
```
Streaming content uses standard `chat.completion.chunk` objects and
`choices[0].delta.content`. Reasoning uses the additive
`choices[0].delta.reasoning_content` field. Reasoning and tool-process chunks
also include a top-level `cow_event` object. The stream ends with `data: [DONE]`.
OpenAI Python clients can use the endpoint by setting the base URL:
```python theme={null}
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:9899/v1",
api_key="your-external-api-token",
)
response = client.chat.completions.create(
model="cowagent",
messages=[{"role": "user", "content": "Hello from Python."}],
extra_body={"conversation_id": "python-example"},
)
print(response.choices[0].message.content)
```
The API returns `400` for invalid requests, `401` for invalid credentials, and
`503` when `external_api_token` is not configured. Non-streaming Agent failures
return a structured JSON `500` response.
For streaming requests, CowAgent waits up to 30 seconds for the Agent to produce
the first event. An Agent failure before the first event returns a structured
JSON `500` response because the SSE response has not started. If no first event
arrives within 30 seconds, the API cancels only that request's in-flight Agent and
returns the same JSON `500` shape with error code `timeout`.
After the SSE response has started, its HTTP status can no longer change.
A later Agent failure is therefore emitted as a `cow_event.type=error` chunk,
followed by a terminal chunk with `finish_reason=error` and then
`data: [DONE]`.
## 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.
#### 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)
#### 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.
### Model Management
Manage text, image, voice, and embedding model configurations for different providers online — no need to edit config files manually:
### Skill Management
View and manage Agent skills (Skills) online:
### Memory Management
View and manage Agent memory online:
### Channel Management
Manage connected channels online with real-time connect/disconnect operations:
### Scheduled Tasks
View and manage scheduled tasks online, including one-time tasks, fixed intervals, and Cron expressions:
### Logs
View Agent runtime logs in real time for monitoring and troubleshooting:
# WeChat Customer Service
Source: https://docs.cowagent.ai/channels/wechat-kf
Integrate CowAgent into WeChat Customer Service
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.
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
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**:
2. Click **My Enterprise** and find the **Corp ID** at the bottom of the page (it goes into `wechat_kf_corp_id`):
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:
4. Open the app's **Receive Messages → Set API Reception** page, click **"Random Generate"** to generate the **Token** and **EncodingAESKey**, and save them:
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):
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.
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://: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:
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:
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:
## 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:
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:
## 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
Integrate CowAgent with WeChat Official Accounts
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 |
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:
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:
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.
**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
Integrate CowAgent into WeCom enterprise app
Integrate CowAgent into WeCom through a custom enterprise app, supporting one-on-one chat for internal employees.
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:
3. On the application creation page, record the `AgentId` and `Secret`:
4. Click **Set API Reception** to configure the application interface:
* 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
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:
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:
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:
## 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 WeCom AI Bot (WebSocket long connection)
> 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.
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.
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**:
2. Click **Create Bot → Manual Creation**:
3. Scroll to the bottom of the right panel and select **API Mode**:
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**
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.
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.
A **webhook (HTTP callback) mode** is also supported: when creating the bot, choose **Use URL callback**, set the receive-message URL to `http(s)://: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.
# WeChat
Source: https://docs.cowagent.ai/channels/weixin
Connect CowAgent to personal WeChat (via the official API)
> Connect CowAgent to your personal WeChat — scan to log in, no public IP required. Supports text, image, voice, file, and video messages in 1-on-1 chats. Backed by WeChat's official API; safe to use. After connecting, a bot assistant is added to your conversation list without affecting normal account usage.
## 1. Setup and run
### 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.
### 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.
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.
## 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 agent workspace data
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.
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
`/agents/`, 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
View status, manage config, and control context with commonly used commands
The following commands can be used in chat with the `/` prefix or in the terminal with the `cow` prefix (some are chat-only).
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, and loaded skills.
```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-v4-flash
```
**Configurable items:**
| Item | Description | Example |
| -------------------------- | --------------------------- | ------------------- |
| `model` | AI model name | `deepseek-v4-flash` |
| `agent_max_context_tokens` | Max context tokens | `40000` |
| `agent_max_context_turns` | Max context memory turns | `30` |
| `agent_max_steps` | Max decision steps per task | `15` |
| `enable_thinking` | Enable deep thinking mode | `true` / `false` |
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
```
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
```
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
CowAgent command system — Terminal CLI and chat commands
CowAgent provides two ways to interact via commands:
* **Terminal CLI** — Run `cow ` in your system terminal for service management, skill management, and other operations
* **Chat Commands** — Type `/` or `cow ` 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
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 ` | 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 |
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 | ✓ | ✗ |
`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 distillation and knowledge base management commands
## 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.
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
```
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 CowAgent process lifecycle with cow commands
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
```
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
```
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` |
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
Install, uninstall, enable, disable, and manage skills via commands
Skill management commands are used to install, query, and manage CowAgent skills. Use `/skill ` in chat or `cow skill ` 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
```
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 |
# Desktop Client
Source: https://docs.cowagent.ai/guide/desktop
Download and use the CowAgent desktop client (macOS / Windows)
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.
## Download & Install
Download the macOS / Windows installer
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.
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.
# Manual Install
Source: https://docs.cowagent.ai/guide/manual-install
Deploy CowAgent manually (source code / Docker)
## Source Code Deployment
### 1. Clone the project
```bash theme={null}
git clone https://github.com/zhayujie/CowAgent
cd CowAgent/
```
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
```
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
```
**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.
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
```
**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.
**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-v4-flash",
"deepseek_api_key": "",
"agent": true,
"agent_workspace": "~/cow",
"agent_max_context_tokens": 40000,
"agent_max_context_turns": 30,
"agent_max_steps": 15,
"cow_lang": "auto"
}
```
| Parameter | Description | Default |
| -------------------------- | ------------------------------------------------------------------------------------------ | ------------------- |
| `channel_type` | Channel type | `web` |
| `model` | Model name | `deepseek-v4-flash` |
| `agent` | Enable Agent mode | `true` |
| `agent_workspace` | Agent workspace path | `~/cow` |
| `agent_max_context_tokens` | Max context tokens | `40000` |
| `agent_max_context_turns` | Max context turns | `30` |
| `agent_max_steps` | Max decision steps per task | `15` |
| `cow_lang` | Language for the UI, command text and system prompts; `auto` to detect, or set `zh` / `en` | `auto` |
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
One-click install and manage CowAgent with scripts
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
```bash theme={null}
bash <(curl -fsSL https://cdn.link-ai.tech/code/cow/run.sh)
```
```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.
**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.
If the `cow` command is not available, you can use `./run.sh ` (Linux/macOS) or `.\scripts\run.ps1 ` (Windows) as a fallback. Both are functionally equivalent.
# Upgrade
Source: https://docs.cowagent.ai/guide/upgrade
How to upgrade CowAgent
## 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
If the Cow CLI is not installed, `./run.sh update` performs the same operations.
## 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
```
Back up `config.json` before upgrading. For Docker deployments, mount the workspace directory as a volume to persist data across upgrades.
## 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
CowAgent 2.0 system architecture and core design
CowAgent 2.0 has evolved from a simple chatbot into a super intelligent assistant with Agent architecture, featuring autonomous thinking, task planning, long-term memory, and skill extensibility.
## System Architecture
CowAgent's architecture consists of the following core modules:
| 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 |
| **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
│ └── / # Topic-based pages
└── skills/ # Custom skills
├── skill-1/
└── skill-2/
```
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.
### 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": 50000,
"agent_max_context_turns": 20,
"agent_max_steps": 20,
"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 | `50000` |
| `agent_max_context_turns` | Max context turns | `20` |
| `agent_max_steps` | Max decision steps per task | `20` |
| `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
CowAgent long-term memory, task planning, skills system, CLI commands, and browser tool in detail
## 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.
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.
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`
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:
### 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:
### 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:
### 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:
### 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:
## 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 ` or `cow skill install `, 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:
### 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`.
### 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 # Search skills
/skill install # Install with one command
```
Also supports installing skills from GitHub, ClawHub, LinkAI, and other third-party platforms. See [Install Skills](/skills/install) for details.
## 5. CLI Command System
CowAgent provides two command interaction methods, covering service management, skill installation, configuration, and more:
* **Terminal CLI:** Run `cow ` in the system terminal, supporting `start`, `stop`, `restart`, `update`, `status`, `logs`, `skill`, etc.
* **Chat commands:** Type `/` 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.
# Introduction
Source: https://docs.cowagent.ai/intro/index
CowAgent - Open-source super AI assistant and Agent Harness
**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, run it across Web and major IM platforms, 24/7 on a personal computer or server.
Open-source repository — Star and contribute
No setup required — experience CowAgent instantly
## Core Capabilities
Decomposes complex tasks and executes them step by step, looping over tools and skills until the goal is reached.
Three-tier architecture (context → daily → core), automatic Deep Dream distillation, hybrid keyword + vector retrieval.
Auto-curates structured knowledge into a Markdown wiki, builds an evolving knowledge graph with visual browsing.
Reviews conversations automatically to improve skills, follow up on unfinished tasks, and consolidate memory and knowledge, growing through everyday use.
A complete skill creation and execution engine. Install from Skill Hub or generate custom skills via natural-language conversation.
First-class support for text, images, voice, and files — recognition, generation, and delivery.
Built-in file I/O, terminal, browser, scheduler, memory retrieval, web search, and more — with native MCP integration.
Terminal CLI and in-chat commands for process management, skill installation, configuration, and context inspection.
Claude, GPT, Gemini, DeepSeek, Qwen, GLM, Kimi, MiniMax, Doubao, and more — swap providers from the Web console with one click.
A single Agent simultaneously serves Web, WeChat, Feishu, DingTalk, WeCom, QQ, and Official Accounts.
## Quick Start
Run one of the commands below to install, configure, and start CowAgent in a single step:
```bash theme={null}
bash <(curl -fsSL https://cdn.link-ai.tech/code/cow/run.sh)
```
```powershell theme={null}
irm https://cdn.link-ai.tech/code/cow/run.ps1 | iex
```
Once started, open `http://localhost:9899` to access the **Web console** — the unified place to chat, configure providers, connect channels, and install skills.
Complete installation and run guide
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
Ask questions, share skills, and follow development
Or scan the WeChat QR code to join the open-source community group:
# Personal Knowledge Base
Source: https://docs.cowagent.ai/knowledge/index
CowAgent personal knowledge base — structured knowledge accumulation, automatic organization, and knowledge graph
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.
## 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.
## 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
## 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
Conversation context — message management, compression strategies, and context operations
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 | `64000` |
| `agent_max_context_turns` | Maximum conversation turns in context | `30` |
| `agent_max_steps` | Maximum decision steps per turn (tool call count) | `30` |
| 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 |
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 — automatic distillation from conversations to permanent memory
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.
## 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
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 long-term memory system — file persistence, automatic writing, and hybrid retrieval
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 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 a combined score (default: 0.7 vector weight + 0.3 keyword weight). Daily memory scores decay over time (30-day half-life), while core memory does not decay.
## 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:
## 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 | `50000` |
| `agent_max_context_turns` | Max context turns; when exceeded, content is trimmed and summarized into memory | `20` |
# Self-Evolution
Source: https://docs.cowagent.ai/memory/self-evolution
Self-Evolution — review a conversation after it goes idle to consolidate memory, improve skills, and follow up on unfinished tasks
## 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.
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.
### 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` |
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.
### 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
Anthropic Claude model configuration (Text Chat + Image Understanding)
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.
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",
"claude_api_key": "YOUR_API_KEY"
}
```
| Parameter | Description |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model` | Supports `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` | Latest flagship; default recommendation, best on complex reasoning and long-running Agent tasks |
| `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` | Previous Opus flagship |
| `claude-opus-4-7` | Earlier Opus flagship |
| `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
Coding Plan model configuration
> 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.
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:
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
Custom provider configuration for third-party API proxies and local models
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.
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:"` 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:"` 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 |
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
DeepSeek model configuration (Text Chat + Thinking Mode)
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-v4-flash",
"deepseek_api_key": "YOUR_API_KEY"
}
```
| Parameter | Description |
| ------------------- | ------------------------------------------------------------------------------------------ |
| `model` | Supports `deepseek-v4-flash` (Default), `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-v4-flash` | Default recommended; fast and low cost |
| `deepseek-v4-pro` | Smarter; better for complex tasks |
## Thinking Mode
The V4 series (`deepseek-v4-flash` / `deepseek-v4-pro`) supports 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.
`deepseek-v4-flash` 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
Doubao (Volcengine Ark) model configuration (Text / Image Understanding / Image Generation / Embedding)
Doubao (Volcengine Ark) supports text chat, image understanding, image generation (Seedream), and embedding. A single `ark_api_key` enables all capabilities.
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
Google Gemini model configuration (Text Chat + Image Understanding + Image Generation)
Google Gemini supports text chat, image understanding, and image generation (Nano Banana series). A single `gemini_api_key` enables all capabilities.
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.7-flash",
"gemini_api_key": "YOUR_API_KEY"
}
```
| Parameter | Description |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model` | Recommended: `gemini-3.7-flash`; also supports `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
Zhipu AI GLM model configuration (Text / Image Understanding / Speech-to-Text / Embedding)
Zhipu AI supports text chat, image understanding, speech-to-text (ASR), and embedding. A single `zhipu_ai_api_key` enables all capabilities.
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 supported by CowAgent and their capability matrix
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-v4-flash / pro | ✅ | | | | | |
| [Claude](/models/claude) | claude-opus-5 / sonnet-5 | ✅ | ✅ | | | | |
| [OpenAI](/models/openai) | gpt-5.6 series | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| [Gemini](/models/gemini) | gemini-3.7-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.5-pro / v2.5 | ✅ | ✅ | | | ✅ | |
| [LinkAI](/models/linkai) | 100+ models from multiple providers | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| [Custom](/models/custom) | Local models / third-party proxies | ✅ | | | | | |
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:
**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
Kimi (Moonshot) model configuration (Text Chat + Image Understanding)
Kimi is provided by Moonshot and supports both text chat and image understanding. The `kimi-k3` and `kimi-k2.x` series natively support vision.
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
Access text, vision, image, speech, and embedding capabilities through the LinkAI platform
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.
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) |
| `model` | Can be any code from the [model list](https://link-ai.tech/console/models) |
See [Model Service](https://link-ai.tech/console/models) 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"
}
}
}
```
| Model ID | Alias |
| -------------------------------- | ------------------------- |
| `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
Xiaomi MiMo model configuration (Text Chat + Image Understanding + Text-to-Speech)
Xiaomi MiMo is a native omni-modal large model. A single `mimo_api_key` enables text chat, image understanding, and text-to-speech all at once.
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.5-pro",
"mimo_api_key": "YOUR_API_KEY",
"mimo_api_base": "https://api.xiaomimimo.com/v1"
}
```
| Parameter | Description |
| --------------- | ---------------------------------------------------------------------------------------- |
| `model` | Default recommendation: `mimo-v2.5-pro`; `mimo-v2.5` 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.5-pro` | Flagship: native omni-modal + Agent capability, up to 1M tokens context |
| `mimo-v2.5` | General-purpose, native omni-modal (text / image / video / audio) |
## Thinking Mode
The MiMo V2.5 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.5-pro` / `mimo-v2.5`), 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.5-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.5-pro"
}
}
}
```
## 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.
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
MiniMax model configuration (Text / Image Understanding / Image Generation / Text-to-Speech)
MiniMax supports text chat, image understanding, image generation, and text-to-speech. A single `minimax_api_key` enables all capabilities.
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's M2.x chat models do not support vision natively; vision calls are uniformly routed to `MiniMax-Text-01`. Once `minimax_api_key` is configured, the Agent's Vision tool automatically uses this model, with no need to specify it explicitly in the configuration file.
## 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
OpenAI model configuration (Text / Vision / Image / Speech / Embedding)
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.
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-5.6-luna",
"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-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-5.6-luna`; 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 |
| `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"
}
}
}
```
Supported image generation models: `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
ERNIE model configuration (Baidu Qianfan)
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"
}
```
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
Qwen model configuration (Text / Image Understanding / Image Generation / Speech-to-Text / Text-to-Speech / Embedding)
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`.
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.
# Delegation
Source: https://docs.cowagent.ai/multi-agent/delegation
Hand a task to a teammate in the conversation and wait for the answer
Delegation lets one Agent ask another for help. Unlike a [sub agent](/multi-agent/subagent), the target is not created for the occasion: it is a standing peer with its own workspace, memory, skills, sessions and scheduler. It answers from its own environment, and the answer comes back to the Agent that asked, never to the user.
The `agent_delegate` tool only appears in a team conversation — two or more enabled Agents with teammates in the room. A single-Agent install never sees it.
## Sub Agent or Peer
| | Sub agent | Delegation |
| --------- | ------------------------------- | ------------------------------------------- |
| Lifetime | Created for one task, then gone | Standing Agent, configured up front |
| Workspace | Shares the caller's | Its own |
| Memory | None of its own | Its own |
| Identity | Anonymous | Appears in the Agent list, can own channels |
| Result | Returned inline | Returned inline |
Use a sub agent to parallelise your own work. Delegate when the task belongs to somebody else — the Agent that owns the codebase, the knowledge base or the customer relationship.
## Delegation Is Synchronous
Delegating hands a task over and waits for the teammate's answer, then returns it. The call blocks until the teammate is done (or the time budget runs out), so there is nothing to poll and no handle to track:
```
agent_delegate(agent_id="research", task="...")
-> { status: "done", content: "..." }
```
Under the hood the run is still recorded in the target's workspace, with the asking run as its parent, so a chain of delegations stays walkable from either end.
## The Teammates You Can Reach
The Agents you may delegate to are the teammates in the current conversation — exactly the roster the **team conversation** section of your context lists, IDs and all. Delegation stays inside the team the user set up; it can never hand work to an Agent outside the room, even one the allowlist would otherwise permit. Aim at someone who is not a teammate and the tool refuses, naming the teammates you can actually reach.
## Parameters
`agent_id` — the teammate's ID (the `@id` shown for them in the team conversation section). `task` — a self-contained brief the teammate can act on without seeing this conversation.
## Guards
Delegation is between full Agents, so it is fenced in:
* **Membership** — the target must be a teammate in this conversation
* **Allowlist** — who may ask whom. Unset means any Agent may delegate to any other
* **Cycles** — an Agent already in the chain cannot be delegated to again
* **Depth** — how many hops one chain may take
* **Size** — the largest task text accepted
* **Time budget** — the longest a delegated run may take before it is given up on
## 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 the whole block to `false`, to withhold the tool |
| `allowed_targets` | unset | Maps a source Agent ID to the IDs it may reach; `"*"` allows any. Unset allows every pair. Targets are further bounded to the current conversation's teammates |
| `max_depth` | `3` | Delegation hops in one chain (1-8) |
| `timeout_seconds` | `600` | Budget for one delegated run (0.01-600) |
| `max_message_chars` | `8000` | Size limit for one delegated task |
An Agent listed with an empty array, like `"research"` above, can be delegated to but cannot delegate onward.
# Sub Agent
Source: https://docs.cowagent.ai/multi-agent/subagent
Delegate self-contained tasks to sub agents, run them in parallel, and get back only the conclusion
A sub agent is a temporary worker the main Agent creates during a conversation. The main Agent hands it one independent task, it completes that task in its own context, and it returns the result. The pages it opened, the files it read and the commands it ran never enter the main conversation.
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 run at the same time, so the total time is that of the slowest one
## Inherited and Isolated
A sub agent inherits part of the main 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) | Message-writing to memory (it can read the shared memory / knowledge base, but never persists) |
A sub agent therefore knows only what the main Agent passes to it. It cannot see the conversation and cannot ask the user anything, so every path, identifier, constraint and settled decision it needs must be stated when the task is created.
## When It Is Used
The main Agent decides on its own. There is nothing to configure and no command to run.
**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 main Agent needs the intermediate results to continue (reading a few files or running a few searches is ordinary work)
* The task depends on earlier parts of the conversation, or needs the user to confirm something along the way
* The task should run beyond this conversation, which is what [scheduled tasks](/tools/scheduler) are for
To force delegation, just say so, for example "use sub agents to research these two directions separately".
## What You See
Each sub agent gets its own card in the web console and the desktop app. Expand it to see the tool it is calling and the steps it has taken; once it finishes, the card holds its full report. Sub agents start and finish independently, so it is clear which one is still running.
## Built-in Types
Each sub agent is created with a type, which determines its system prompt and the tools it may use:
| Type | Use case | Tools |
| ----------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `general-purpose` | Multi-step work that involves both investigation and action: searching, reading, running commands, writing files | All tools of the main Agent, except the blocked ones |
| `explore` | Read-only investigation: finding files, searching code or documents, gathering facts from the web | `read`, `ls`, `search_files`, `web_search`, `web_fetch`, `vision`, `memory_search`, `memory_get` |
## Custom Types
Add a `.md` file under `subagents/` in the workspace to define a new type. The format is the same as skills:
```markdown theme={null}
---
name: research-report
description: Research one topic across many web sources and return a short report with citations. Use when answering would mean opening a lot of pages and only the conclusion matters.
tools: web_search, web_fetch, read, write
---
You are a research assistant. You receive one topic and return one report.
How to work:
1. Search broadly first, then follow the two or three most promising sources.
2. Prefer primary sources (official docs, the vendor's pricing page, the original announcement) over articles describing them.
3. Cross-check every number, date and price against a second source.
Keep the report under 400 words, containing in this order:
- Answer: two or three sentences that settle the question
- Findings: bullets, each ending with the source URL
- Unconfirmed: anything you could not verify from a primary source
Write "not found" where you came up empty. Never fill a gap with a guess.
```
Fields:
| Field | Description |
| ------------- | --------------------------------------------------------------------------------------------- |
| `name` | Type name |
| `description` | What the main Agent selects on, so it should say when to use this type rather than what it is |
| `tools` | Allowed tools. Omit to inherit all tools of the main Agent |
| Body | The sub agent's system prompt: how to work and what to return |
Restricting `tools` is the most reliable constraint: a type with only `read, ls, search_files` cannot modify anything. A type that lists `tools` does not inherit skills, so omit the field when the type needs them and scope the work in the body instead.
On first start, `README.md` and `example.md.template` are created under `subagents/`. Copy the template 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.
Tool names are matched exactly, so the `tools` allowlist does not cover MCP tools. Omit the field if the type needs them.
## Blocked Tools
The following tools are unavailable to every sub agent:
| Tool | Reason |
| ------------------------------ | ------------------------------------------------------------------------------------------ |
| `send`, `scheduler` | Act on the user's channel in the main Agent's name, which is outside the scope of one task |
| `env_config`, `evolution_undo` | Modify the Agent's own configuration |
| `subagent` | Prevents a type with all tools from recursing. Actual nesting is governed by `max_depth` |
## Configuration
Sub agents are enabled by default. The switch is in "Config → Agent" in the web console and the desktop app, and takes effect on the next turn with no restart. Finer limits are set 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` | Nesting depth. `1` means only the main Agent may create sub agents | `1` |
| `max_concurrent` | Maximum sub agents running in parallel per call | `3` |
| `timeout_seconds` | Time budget for one call, covering all its parallel tasks | `300` |
## Design
* **Context isolation**: a sub agent starts with an empty message history, loads no persona files and has no memory manager. The main conversation keeps only the call and the final conclusion.
* **Parallel execution**: tasks within one call run on their own threads and share one time budget. Several calls issued in the same turn also start together.
* **Half the step budget**: a sub agent gets half the main Agent's maximum steps. Its task is already bounded, so it does not need the budget of a whole conversation. When it runs out, it is asked to summarize what it completed.
* **Traceable timeouts**: a task that times out is cancelled and reported as such. The number of results always matches the number of tasks, so the main Agent can tell "found nothing" from "never finished".
* **Display separated from context**: the model receives structured data and the user sees a formatted report. Both come from the same result, and the displayed form never enters the model's context.
# Changelog
Source: https://docs.cowagent.ai/releases/overview
CowAgent version history
| Version | Date | Description |
| ------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [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.0
Source: https://docs.cowagent.ai/releases/v2.0.0
CowAgent 2.0 - Full upgrade from chatbot to AI super assistant
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
## Task Planning & Tools
## Skills System
## Contributing
Welcome to [submit feedback](https://github.com/zhayujie/CowAgent/issues) and [contribute code](https://github.com/zhayujie/CowAgent/pulls).
# v2.0.1
Source: https://docs.cowagent.ai/releases/v2.0.1
CowAgent 2.0.1 - Built-in Web Search, smart context management, multiple fixes
**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 - Web Console upgrade, multi-channel concurrency, session persistence
**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:
#### Model Management
Manage model configurations online without manually editing config files:
#### Skill Management
View and manage Agent skills (Skills) online:
#### Memory Management
View and manage Agent memory online:
#### Channel Management
Manage connected channels online with real-time connect/disconnect operations:
#### Scheduled Tasks
View and manage scheduled tasks online, including one-time tasks, fixed intervals, and Cron expressions:
#### Logs
View Agent runtime logs in real-time for monitoring and troubleshooting:
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 - WeCom Smart Bot and QQ channels, Web Console file handling, memory system upgrade
## 🔌 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 - Personal WeChat channel, new model support, Japanese docs, script refactoring and bug fixes
## 🔌 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 - Cow CLI, Skill Hub open source, Browser tool, WeCom Bot QR scan, and more
## 🖥️ Cow CLI
New CLI command system for managing CowAgent from terminal and chat:
* **Terminal commands**: Run `cow ` for `start`, `stop`, `restart`, `update`, `status`, `logs`, etc.
* **Chat commands**: Type `/` 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)
## 🧩 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 ` in chat or `cow skill install ` 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)
## 🌐 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)
## 🤖 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
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)
## 🧠 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)
## 🧩 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**.
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: Desktop client for macOS / Windows, enhanced knowledge base document management, on-demand MCP tool retrieval, Traditional Chinese support, new models, plus security and experience improvements
🌐 [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/)
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.
## 🔧 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`.
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).
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.
## 🖥 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)
# Create Skills
Source: https://docs.cowagent.ai/skills/create
Create custom skills through conversation
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
## 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) |
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
Browse, search, and install AI Agent skills
[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)
## 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
```
```bash Terminal theme={null}
cow skill install
```
You can also browse the marketplace directly from chat:
```text theme={null}
/skill list --remote
/skill search
```
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
Skill file layout:
```
your-skill/
├── SKILL.md # required, in the root
├── scripts/ # optional, runtime scripts
└── resources/ # optional, additional assets
```
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
Text-to-image / image-to-image / multi-image fusion with automatic multi-provider routing and fallback
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`, `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
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` |
**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.)
- 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
CowAgent skills system introduction
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 from multiple sources with a single command
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.
## 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:
```
## From LinkAI
All public resources on [LinkAI](https://link-ai.tech/console) (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:
```
> 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).
## 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
```
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
Maintain a local structured knowledge base with automatic archiving, categorisation, and cross-referencing
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 subdirectories (grouped by content)
└── .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//.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:
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
```
* `> 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//.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
Create, install, and update skills — standardises SKILL.md format and directory structure
`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.
**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"]` |
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 |
**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 `/skills//`.
| 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 `/skills//`
4. If the archive contains an `INSTALL.md` or similar setup script, run it — but the final result must still reside under `/skills//`
## 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 --path /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 /skills/
```
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
Execute system commands
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
# browser - Browser
Source: https://docs.cowagent.ai/tools/browser
Control a browser to access and interact with web pages
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
```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
```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
```
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.
**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:
```bash theme={null}
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
--remote-debugging-port=9222 \
--user-data-dir="$HOME/.cow/chrome-cdp"
```
```bash theme={null}
google-chrome \
--remote-debugging-port=9222 \
--user-data-dir="$HOME/.cow/chrome-cdp"
```
```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"
}
}
}
```
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.
# edit - File Edit
Source: https://docs.cowagent.ai/tools/edit
Edit files via precise text replacement
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.
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
Manage API keys and secrets
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.
# Tools Overview
Source: https://docs.cowagent.ai/tools/index
CowAgent built-in tools system
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 content, supports text, images, PDF
Create or overwrite files
Edit files via precise text replacement
List directory contents
Search file contents, or find files by name
Execute system commands
Send files or images to user
Search and read long-term memory
## Optional Tools
The following tools require additional dependencies or API key configuration:
Manage API keys and secrets
Create and manage scheduled tasks
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:
Supports standard stdio / SSE transports. Hot-reload, zero code changes.
# ls - Directory List
Source: https://docs.cowagent.ai/tools/ls
List directory contents
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.
`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
Integrate external tool ecosystems via the Model Context Protocol
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.
## 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": {
"": {
"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": ""
}
}
}
}
```
* **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.
## 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
## 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
Search and read long-term memory and knowledge base files
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
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
Read file content
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())
```
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
Create and manage scheduled tasks
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.
## 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 `20`, so each scheduled run keeps the most recent **4 turns** of history by default. Increase `agent_max_context_turns` if you need longer memory.
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
Search inside files by regex, or find files by name
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.
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
Send files to user
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
# vision - Image Understanding
Source: https://docs.cowagent.ai/tools/vision
Analyze image content (recognition, description, OCR, etc.)
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-Text-01 | Always uses the dedicated vision model |
ZhipuAI and MiniMax text models do not support image understanding, so their dedicated vision models are always used automatically.
> 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
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
Fetch web pages and document content
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
`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
Search the internet for real-time information, with support for multiple search providers
Search the internet for real-time information, news, research, and more. Supports six backends — Bocha, ERNIE, GLM, LinkAI, AnySearch, and Serply — and works once any one of them is configured.
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) |
| AnySearch | Reuses `anysearch_api_key` | [AnySearch Console](https://anysearch.com/) |
| Serply | `tools.web_search.serply_api_key` | [Serply](https://serply.io) ([docs](https://serply.io/docs)) |
Except for Bocha, AnySearch, and Serply which require dedicated keys (bocha\_api\_key / anysearch\_api\_key / serply\_api\_key), the other three reuse the corresponding model's API key — configuring the model automatically grants search capability.
## 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 `bocha → qianfan → zhipu → linkai → anysearch → serply`.
* `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 |
If none of the six credentials are configured, this tool is not registered with the Agent.
# write - File Write
Source: https://docs.cowagent.ai/tools/write
Create or overwrite 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