CowAgent Documentation

bash <(curl -fsSL https://cdn.link-ai.tech/code/cow/run.sh)

irm https://cdn.link-ai.tech/code/cow/run.ps1 | iex

curl -O https://cdn.link-ai.tech/code/cow/docker-compose.yml
docker compose up -d

cow start | stop | restart        # service control
cow status | logs                  # status and logs
cow update                         # pull latest code and restart
cow skill install <name>           # install a skill
cow install-browser                # install browser automation

/skill list                   # list installed skills
/skill search <keyword>        # search the marketplace
/skill install <name>          # one-click install

pip install croniter>=2.0.0

用户: 每天早上9点提醒我开会
Agent: [调用 scheduler 工具]
      action: create
      name: 每日开会提醒
      message: 该开会了！
      schedule_type: cron
      schedule_value: 0 9 * * *

用户: 每天早上8点帮我读取一下今日日程
Agent: [调用 scheduler 工具]
      action: create
      name: 每日日程
      tool_call:
        tool_name: read
        tool_params:
          file_path: ~/cow/schedule.txt
        result_prefix: 📅 今日日程
      schedule_type: cron
      schedule_value: 0 8 * * *

0 9 * * *      # 每天 9:00
0 */2 * * *    # 每 2 小时
30 8 * * 1-5   # 工作日 8:30
0 0 1 * *      # 每月 1 号

3600           # 每小时
86400          # 每天
1800           # 每 30 分钟

2024-12-25T09:00:00
2024-12-31T23:59:59

用户: 查看我的定时任务
Agent: [调用 scheduler 工具]
      action: list

用户: 查看任务 abc123 的详情
Agent: [调用 scheduler 工具]
      action: get
      task_id: abc123

用户: 删除任务 abc123
Agent: [调用 scheduler 工具]
      action: delete
      task_id: abc123

用户: 暂停任务 abc123
Agent: [调用 scheduler 工具]
      action: disable
      task_id: abc123

用户: 恢复任务 abc123
Agent: [调用 scheduler 工具]
      action: enable
      task_id: abc123

~/cow/scheduler/tasks.json

{
  "id": "abc123",
  "name": "每日提醒",
  "enabled": true,
  "created_at": "2024-01-01T10:00:00",
  "updated_at": "2024-01-01T10:00:00",
  "schedule": {
    "type": "cron",
    "expression": "0 9 * * *"
  },
  "action": {
    "type": "send_message",
    "content": "该开会了！",
    "receiver": "wxid_xxx",
    "receiver_name": "张三",
    "is_group": false,
    "channel_type": "wechat"
  },
  "next_run_at": "2024-01-02T09:00:00",
  "last_run_at": "2024-01-01T09:00:00"
}

{
  "id": "def456",
  "name": "每日日程",
  "enabled": true,
  "created_at": "2024-01-01T10:00:00",
  "updated_at": "2024-01-01T10:00:00",
  "schedule": {
    "type": "cron",
    "expression": "0 8 * * *"
  },
  "action": {
    "type": "tool_call",
    "tool_name": "read",
    "tool_params": {
      "file_path": "~/cow/schedule.txt"
    },
    "result_prefix": "📅 今日日程",
    "receiver": "wxid_xxx",
    "receiver_name": "张三",
    "is_group": false,
    "channel_type": "wechat"
  },
  "next_run_at": "2024-01-02T08:00:00"
}

用户: 每天早上8点提醒我吃药
Agent: ✅ 定时任务创建成功
       任务ID: a1b2c3d4
       调度: 每天 8:00
       消息: 该吃药了！

用户: 工作日下午6点提醒我下班
Agent: [创建 cron: 0 18 * * 1-5]
       消息: 该下班了！

用户: 1小时后提醒我
Agent: [创建 interval: 3600]

用户: 每天早上8点帮我读取今日日程
Agent: ✅ 定时任务创建成功
       任务ID: schedule001
       调度: 每天 8:00
       工具: read(file_path='~/cow/schedule.txt')
       前缀: 📅 今日日程

用户: 每天晚上11点备份工作文件
Agent: [创建 cron: 0 23 * * *]
       工具: bash(command='cp ~/cow/work.txt ~/cow/backup/work_$(date +%Y%m%d).txt')
       前缀: ✅ 文件已备份

用户: 每周五下午5点提醒我写周报
Agent: [创建 cron: 0 17 * * 5]
       消息: 📊 该写周报了！

用户: 12月25日早上9点提醒我圣诞快乐
Agent: [创建 once: 2024-12-25T09:00:00]

{
  "channel_type": "feishu",
  "feishu_app_id": "cli_xxxxx",
  "feishu_app_secret": "your_app_secret",
  "feishu_token": "your_verification_token",
  "feishu_bot_name": "你的机器人名称",
  "feishu_event_mode": "webhook",
  "feishu_port": 9891
}

{
  "feishu_event_mode": "webhook",
  "feishu_port": 9891
}

python3 app.py

pip install lark-oapi

{
  "feishu_event_mode": "websocket"
}

python3 app.py

[FeiShu] lark_oapi not installed

[Lark][ERROR] connect failed, err:[SSL:CERTIFICATE_VERIFY_FAILED] certificate verify failed: self signed certificate in certificate chain

[FeiShu] SSL certificate verification disabled due to certificate error. This may happen when using corporate proxy or self-signed certificates.

Address already in use

┌─────────────────────┐    ┌─────────────────────┐    ┌──────────────────┐
│ 1. 企业微信后台      │ →  │ 2. CoW 配置回调      │ →  │ 3. 绑定微信客服   │
│   创建一个自建应用   │    │   端口 9888          │    │   账号           │
└─────────────────────┘    └─────────────────────┘    └──────────────────┘
                                                              ↓
                                                   外部微信用户通过
                                                   链接/二维码 →
                                                   消息 → CoW Bot

{
  "channel_type": "wechat_kf",

  "wechat_kf_corp_id": "ww1234567890abcdef",
  "wechat_kf_secret": "<企微应用的 Secret>",
  "wechat_kf_token": "<接收消息 Token>",
  "wechat_kf_aes_key": "<EncodingAESKey>",
  "wechat_kf_port": 9888
}

python app.py

[wechat_kf] WeCom customer-service channel started
[wechat_kf] Listening on http://0.0.0.0:9888/wxkf/

apt-get install libavcodec-extra

"channel_type": "wechatcom_app",
    "wechatcom_corp_id": "",  # 企业微信公司的corpID
    "wechatcomapp_token": "",  # 企业微信app的token
    "wechatcomapp_port": 9898,  # 企业微信app的服务端口, 不需要端口转发
    "wechatcomapp_secret": "",  # 企业微信app的secret
    "wechatcomapp_agent_id": "",  # 企业微信app的agent_id
    "wechatcomapp_aes_key": "",  # 企业微信app的aes_key

Error code: 60020, message: "not allow to access from your ip, ...from ip: xx.xx.xx.xx"

---

## File: channel/wechatmp/README.md

# 微信公众号channel

微信公众号channel，提供稳定的服务。
目前支持订阅号和服务号两种类型的公众号，它们都支持文本交互，语音和图片输入。其中个人主体的微信订阅号由于无法通过微信认证，存在回复时间限制，每天的图片和声音回复次数也有限制。

## 使用方法（订阅号，服务号类似）

在开始部署前，你需要一个拥有公网IP的服务器，以提供微信服务器和我们自己服务器的连接。或者你需要进行内网穿透，否则微信服务器无法将消息发送给我们的服务器。

此外，需要在我们的服务器上安装python的web框架web.py和wechatpy。
以ubuntu为例(在ubuntu 22.04上测试):
```
pip3 install web.py
pip3 install wechatpy
```

然后在[微信公众平台](https://mp.weixin.qq.com)注册一个自己的公众号，类型选择订阅号，主体为个人即可。

然后根据[接入指南](https://developers.weixin.qq.com/doc/offiaccount/Basic_Information/Access_Overview.html)的说明，在[微信公众平台](https://mp.weixin.qq.com)的“设置与开发”-“基本配置”-“服务器配置”中填写服务器地址`URL`和令牌`Token`。`URL`填写格式为`http://url/wx`，可使用IP（成功几率看脸），`Token`是你自己编的一个特定的令牌。消息加解密方式如果选择了需要加密的模式，需要在配置中填写`wechatmp_aes_key`。

相关的服务器验证代码已经写好，你不需要再添加任何代码。你只需要在本项目根目录的`config.json`中添加
```
"channel_type": "wechatmp",     # 如果通过了微信认证，将"wechatmp"替换为"wechatmp_service"，可极大的优化使用体验
"wechatmp_token": "xxxx",       # 微信公众平台的Token
"wechatmp_port": 8080,          # 微信公众平台的端口,需要端口转发到80或443
"wechatmp_app_id": "xxxx",      # 微信公众平台的appID
"wechatmp_app_secret": "xxxx",  # 微信公众平台的appsecret
"wechatmp_aes_key": "",         # 微信公众平台的EncodingAESKey，加密模式需要
"single_chat_prefix": [""],     # 推荐设置，任意对话都可以触发回复，不添加前缀
"single_chat_reply_prefix": "", # 推荐设置，回复不设置前缀
"plugin_trigger_prefix": "&",   # 推荐设置，在手机微信客户端中，$%^等符号与中文连在一起时会自动显示一段较大的间隔，用户体验不好。请不要使用管理员指令前缀"#"，这会造成未知问题。
```
然后运行`python3 app.py`启动web服务器。这里会默认监听8080端口，但是微信公众号的服务器配置只支持80/443端口，有两种方法来解决这个问题。第一个是推荐的方法，使用端口转发命令将80端口转发到8080端口：
```
sudo iptables -t nat -A PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 8080
sudo iptables-save > /etc/iptables/rules.v4
```
第二个方法是让python程序直接监听80端口，在配置文件中设置`"wechatmp_port": 80` ，在linux上需要使用`sudo python3 app.py`启动程序。然而这会导致一系列环境和权限问题，因此不是推荐的方法。

443端口同理，注意需要支持SSL，也就是https的访问，在`wechatmp_channel.py`中需要修改相应的证书路径。

程序启动并监听端口后，在刚才的“服务器配置”中点击`提交`即可验证你的服务器。
随后在[微信公众平台](https://mp.weixin.qq.com)启用服务器，关闭手动填写规则的自动回复，即可实现ChatGPT的自动回复。

之后需要在公众号开发信息下将本机IP加入到IP白名单。

不然在启用后，发送语音、图片等消息可能会遇到如下报错：
```
'errcode': 40164, 'errmsg': 'invalid ip xx.xx.xx.xx not in whitelist rid
```


## 个人微信公众号的限制
由于人微信公众号不能通过微信认证，所以没有客服接口，因此公众号无法主动发出消息，只能被动回复。而微信官方对被动回复有5秒的时间限制，最多重试2次，因此最多只有15秒的自动回复时间窗口。因此如果问题比较复杂或者我们的服务器比较忙，ChatGPT的回答就没办法及时回复给用户。为了解决这个问题，这里做了回答缓存，它需要你在回复超时后，再次主动发送任意文字（例如1）来尝试拿到回答缓存。为了优化使用体验，目前设置了两分钟（120秒）的timeout，用户在至多两分钟后即可得到查询到回复或者错误原因。

另外，由于微信官方的限制，自动回复有长度限制。因此这里将ChatGPT的回答进行了拆分，以满足限制。

## 私有api_key
公共api有访问频率限制（免费账号每分钟最多3次ChatGPT的API调用），这在服务多人的时候会遇到问题。因此这里多加了一个设置私有api_key的功能。目前通过godcmd插件的命令来设置私有api_key。

## 语音输入
利用微信自带的语音识别功能，提供语音输入能力。需要在公众号管理页面的“设置与开发”->“接口权限”页面开启“接收语音识别结果”。

## 语音回复
请在配置文件中添加以下词条：
```
  "voice_reply_voice": true,
```
这样公众号将会用语音回复语音消息，实现语音对话。

默认的语音合成引擎是`google`，它是免费使用的。

如果要选择其他的语音合成引擎，请添加以下配置项：
```
"text_to_voice": "pytts"
```

pytts是本地的语音合成引擎。还支持baidu,azure，这些你需要自行配置相关的依赖和key。

如果使用pytts，在ubuntu上需要安装如下依赖：
```
sudo apt update
sudo apt install espeak
sudo apt install ffmpeg
python3 -m pip install pyttsx3
```
不是很建议开启pytts语音回复，因为它是离线本地计算，算的慢会拖垮服务器，且声音不好听。

## 图片回复
现在认证公众号和非认证公众号都可以实现的图片和语音回复。但是非认证公众号使用了永久素材接口，每天有1000次的调用上限（每个月有10次重置机会，程序中已设定遇到上限会自动重置），且永久素材库存也有上限。因此对于非认证公众号，我们会在回复图片或者语音消息后的10秒内从永久素材库存内删除该素材。

## 测试
目前在`RoboStyle`这个公众号上进行了测试（基于[wechatmp分支](https://github.com/JS00000/chatgpt-on-wechat/tree/wechatmp)），感兴趣的可以关注并体验。开启了godcmd, Banwords, role, dungeon, finish这五个插件，其他的插件还没有详尽测试。百度的接口暂未测试。[wechatmp-stable分支](https://github.com/JS00000/chatgpt-on-wechat/tree/wechatmp-stable)是较稳定的上个版本，但也缺少最新的功能支持。

## TODO
 - [x] 语音输入
 - [x] 图片输入
 - [x] 使用临时素材接口提供认证公众号的图片和语音回复
 - [x] 使用永久素材接口提供未认证公众号的图片和语音回复
 - [ ] 高并发支持

---

## File: desktop/README.md

# CowAgent Desktop

Cross-platform desktop client for CowAgent, built with Electron + React + TypeScript.

## Development

### Prerequisites

- Node.js 18+
- npm or yarn
- Python 3.7+ (for the backend)

### Setup

```bash
cd desktop
npm install
```

### Run in Development

Start the renderer dev server and Electron together:

```bash
npm run dev
```

Or run them separately:

```bash
# Terminal 1: Start Vite dev server
npm run dev:renderer

# Terminal 2: Start Electron (after renderer is ready)
npm run dev:main
```

The app will automatically start the Python backend from the parent directory.

### Build

```bash
# Build for current platform
npm run dist

# Build for macOS only
npm run dist:mac

# Build for Windows only
npm run dist:win
```

Build outputs are placed in the `release/` directory.

## Architecture

```
desktop/
├── src/
│   ├── main/              # Electron main process
│   │   ├── index.ts       # Window management, IPC
│   │   ├── python-manager.ts  # Python backend lifecycle
│   │   └── preload.ts     # Context bridge for renderer
│   └── renderer/          # React UI (Vite)
│       └── src/
│           ├── api/       # HTTP client for backend APIs
│           ├── components/ # Reusable UI components
│           ├── hooks/     # React hooks
│           ├── pages/     # Page components
│           └── types.ts   # TypeScript types
├── resources/             # App icons
├── package.json           # Dependencies and build config
└── vite.config.ts         # Vite config
```

### How it Works

1. Electron main process starts and creates the app window
2. It spawns the Python backend (`app.py`) as a child process
3. The React UI communicates with the Python backend via HTTP APIs
4. SSE (Server-Sent Events) is used for streaming chat responses and live logs

---

## File: docs/cli/general.mdx

---
title: General Commands
---

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

<Tip>
  In the Web console, typing `/` brings up an autocomplete menu with keyboard navigation and Tab completion.
</Tip>

## help

Show help information for all available commands.

```text
/help
```

## status

View current session and service status, including process info, model configuration, message count, and loaded skills.

```text
/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
/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
/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
/config
```

**View a single item:**

```text
/config model
```

**Modify a config item:**

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

<Note>
  When changing `model`, the system automatically matches the corresponding model API. Configuration is persisted to `config.json`.
</Note>

## context

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

```text
/context
```

**Clear current session context:**

```text
/clear
```

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

## 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
/compact
```

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

## logs

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

```text
/logs
```

**Specify line count:**

```text
/logs 50
```

## version

Show the current CowAgent version.

```text
/version
```

---

## File: docs/cli/index.mdx

---
title: Commands Overview
---

CowAgent provides two ways to interact via commands:

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

## Cow CLI

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

```bash
pip install -e .
```

Then use the `cow` command from anywhere:

```bash
cow help
```

Example output:

```
🐮 CowAgent CLI

Usage: cow <command>

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

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

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

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

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

## Chat Commands

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

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

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

## Command Availability

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

<Note>
  `context` only shows a hint in the terminal to use it in chat. `config` is only available in chat.
</Note>