# CowAgent User Guide

**CowAgent** is an open-source "super AI assistant" and Agent harness. You give it a goal in plain language — through a web chat window or your favorite messaging app — and it plans the work, runs tools and skills, remembers what matters across days, and reports back. A single running instance can serve you on the Web console, WeChat, Feishu, DingTalk, WeCom, QQ, Telegram, Slack, and Discord at the same time, all backed by the language model of your choice.

CowAgent is the Agent-era evolution of the long-running `chatgpt-on-wechat` project. Where the original was a chatbot that answered messages, CowAgent **acts**: it reads and writes files, runs terminal commands, drives a real browser, schedules recurring jobs, builds a personal knowledge base, and grows a long-term memory of you and your work — 24/7 on a personal computer or a server.

> [!NOTE]
> CowAgent runs entirely on **your** machine. By default it never connects to any remote control plane — your conversations, files, and API keys stay local. The optional LinkAI cloud console is opt-in and off until you configure it.

> [!CAUTION]
> **The Agent has direct access to your operating system** — it can run shell commands, edit files, and install software. Run CowAgent only in an environment you trust, and read the [Security & Safety](#13-security--safety-for-users) section before pointing it at anything sensitive.

---

## Table of Contents

1. [Quick Start](#1-quick-start)
2. [Installation](#2-installation)
3. [The Web Console](#3-the-web-console)
4. [Choosing and Configuring a Model](#4-choosing-and-configuring-a-model)
5. [Agent Mode: How CowAgent Thinks and Acts](#5-agent-mode-how-cowagent-thinks-and-acts)
6. [Skills](#6-skills)
7. [Memory and the Knowledge Base](#7-memory-and-the-knowledge-base)
8. [Scheduled Tasks](#8-scheduled-tasks)
9. [Connecting Messaging Channels](#9-connecting-messaging-channels)
10. [Voice: Speech-to-Text and Text-to-Speech](#10-voice-speech-to-text-and-text-to-speech)
11. [Command Reference: Terminal CLI and Chat Commands](#11-command-reference-terminal-cli-and-chat-commands)
12. [Plugins (Classic Chat Mode)](#12-plugins-classic-chat-mode)
13. [Security & Safety for Users](#13-security--safety-for-users)
14. [Troubleshooting](#14-troubleshooting)
15. [Frequently Asked Questions](#15-frequently-asked-questions)
16. [Quick Reference](#16-quick-reference)

---

## 1. Quick Start

The fastest way to get CowAgent running is the one-line installer. It detects your Python, downloads the project, installs dependencies, walks you through picking a model and a channel, writes a `config.json`, and starts the service — all in a single step.

=== "Linux / macOS"

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

=== "Windows (PowerShell)"

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

The installer is interactive. It will ask you, in order:

1. **Language** — English or 中文 (controls install prompts and the assistant's default reply language).
2. **AI model** — pick a provider (DeepSeek, Claude, Gemini, OpenAI, MiniMax, GLM, Qwen, Doubao, Kimi, MiMo, or LinkAI). You can also choose **Skip** and configure it later in the web console.
3. **Channel** — pick where you want to talk to the Agent. **Web Console** is the recommended default and works out of the box.

When it finishes you will see a banner like this:

```text
✅ CowAgent is now running in background!
✅ Process will continue after closing terminal.
Web console : http://localhost:9899/chat
```

Open **http://localhost:9899** in your browser and start chatting.

> [!TIP]
> If you chose **Skip** for the model, just open the web console and set your API key there — the console has a one-click model picker. Nothing else needs to change.

### Your first conversation

Type a goal, not just a question. CowAgent is an agent, so it can do multi-step work:

```text
You: Find the 3 most-starred Python web frameworks on GitHub this month,
     put them in a table with stars and a one-line description, and save it
     to a file called frameworks.md in my home directory.
```

CowAgent will search the web, format a table, write the file with its file tool, and reply with a summary — possibly attaching the file. The first time you talk to it, it will also ask a few questions about you so it can build its long-term memory.

---

## 2. Installation

### 2.1 Requirements

| Requirement | Detail |
|---|---|
| **Operating system** | Linux, macOS, or Windows |
| **Python** | 3.7 – 3.12 (3.12 recommended) |
| **Disk** | ~500 MB for the project and dependencies; more if you install the browser tool |
| **Network** | Outbound HTTPS to your chosen model provider |
| **An LLM API key** | From any supported provider (or a single LinkAI key for all of them) |

> [!WARNING]
> **Python 3.13+ is not supported.** CowAgent depends on `web.py`, which relies on the standard-library `cgi` module that was removed in Python 3.13. The installer will detect 3.13+ and ask you to install Python 3.7–3.12 (3.12 is the recommended version).

### 2.2 Installation methods

=== "One-line installer (recommended)"

    Runs the full guided setup described in [Quick Start](#1-quick-start):

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

    The installer clones from GitHub, automatically falling back to the **Gitee mirror** if GitHub is unreachable, and uses the **Tsinghua PyPI mirror** for faster installs in mainland China.

=== "Manual clone"

    ```bash
    git clone https://github.com/zhayujie/CowAgent.git
    cd CowAgent
    pip install -r requirements.txt
    pip install -e .          # registers the `cow` command
    cp config-template.json config.json
    # edit config.json: set your model and API key
    python app.py
    ```

=== "Try online (no install)"

    Visit **https://link-ai.tech/cowagent/create** to experience CowAgent instantly with no setup.

### 2.3 What the installer does

Under the hood, `run.sh` performs these steps so you don't have to:

- [x] Detects a compatible Python (`python3`, `python3.12`, … down to `python3.7`)
- [x] Clones the project (GitHub → Gitee fallback) or downloads a zip if `git` is missing
- [x] Installs `requirements.txt` (with mirror selection and system-package conflict handling)
- [x] Runs `pip install -e .` to register the `cow` command on your `PATH`
- [x] Asks you to pick a model and channel
- [x] Writes `config.json`
- [x] Starts the service in the background and tails the log

> [!NOTE]
> If the `cow` command isn't found on your `PATH` after install, you can always run the equivalent with `python -m cli.cli <command>`, or use the bundled `./run.sh <command>` management script.

### 2.4 Starting, stopping, and updating

Once installed, manage the service with the `cow` command (or `./run.sh`):

```bash
cow start        # start the service in the background
cow stop         # stop it
cow restart      # restart it
cow status       # show running status, model, and channel
cow logs         # tail the live log (Ctrl+C to detach; the agent keeps running)
cow update       # pull the latest code, reinstall deps, and restart
```

```text
$ cow status
=========================================
   🐄 CowAgent Status
=========================================
Status: ✅ Running
PID:    48213
Model:  deepseek-v4-flash
Channel: web
=========================================
```

> [!TIP]
> Stopping the log tail with `Ctrl+C` does **not** stop CowAgent — the service runs in the background and survives closing your terminal. Use `cow stop` to actually stop it.

---

## 3. The Web Console

The Web console is CowAgent's home base and the recommended way to use it. It auto-starts on **http://localhost:9899** whenever the service is running (even when you've also connected an IM channel), unless you explicitly disable it.

From the console you can:

- **Chat** with the Agent in a rich interface that renders Markdown, images, and video inline, and streams replies as they're generated.
- **Switch models** with one click and paste API keys for any provider.
- **Connect channels** (WeChat, Feishu, DingTalk, and more) without editing files.
- **Browse and install skills** from the Skill Hub.
- **View your knowledge base** as browsable pages and an interactive knowledge graph.
- **Manage scheduled tasks.**

### 3.1 Slash commands in chat

Type `/` in the console's chat box and a command menu appears. These **chat commands** operate on the live Agent (unlike the terminal `cow` commands, which manage the service). The most useful ones:

| Command | What it does |
|---|---|
| `/context` | Show information about the current conversation context |
| `/context clear` | Clear the conversation history for this session |
| `/cancel` | Stop the Agent's current run immediately |
| `/install-browser` | Install the browser tool (Playwright + Chromium) |
| `/knowledge` | Show knowledge-base stats and directory |
| `/knowledge on` / `/knowledge off` | Toggle the knowledge base |
| `/skill list` | List installed skills |
| `/skill install <name>` | Install a skill from the Skill Hub |

See the full list in [Command Reference](#11-command-reference-terminal-cli-and-chat-commands).

### 3.2 Protecting the console

By default the web console has **no password** — anyone who can reach `http://localhost:9899` can use your Agent (and therefore your machine). This is fine on a personal laptop, but if you expose the console to a network you must set a password. See [Security & Safety](#13-security--safety-for-users).

---

## 4. Choosing and Configuring a Model

CowAgent talks to one model at a time, selected by the `model` field in `config.json` (or the web console's model picker). Switching providers is a matter of changing the model name and supplying that provider's API key — the Agent layer adapts automatically.

### 4.1 Supported providers and recommended models

CowAgent ships adapters for every major LLM provider. The table below lists each provider, its recommended "Agent" model (the ones the project tunes for tool-calling), and the API-key field you set in `config.json`.

| Provider | Recommended model (`model` value) | API-key field |
|---|---|---|
| **DeepSeek** (default) | `deepseek-v4-flash`, `deepseek-v4-pro` | `deepseek_api_key` |
| **Claude** (Anthropic) | `claude-opus-4-8`, `claude-sonnet-4-6` | `claude_api_key` |
| **Gemini** (Google) | `gemini-3.5-flash`, `gemini-3.1-pro-preview` | `gemini_api_key` |
| **OpenAI** | `gpt-5.4`, `gpt-5.5` | `open_ai_api_key` |
| **GLM / Zhipu** | `glm-5.1`, `glm-4.7` | `zhipu_ai_api_key` |
| **Qwen** (Alibaba DashScope) | `qwen3.7-max`, `qwen3.7-plus` | `dashscope_api_key` |
| **Kimi** (Moonshot) | `kimi-k2.6` | `moonshot_api_key` |
| **MiniMax** | `MiniMax-M3` | `minimax_api_key` |
| **Doubao** (Volcengine Ark) | `doubao-seed-2-0-pro-260215` | `ark_api_key` |
| **MiMo** (Xiaomi) | `mimo-v2.5-pro` | `mimo_api_key` |
| **ERNIE / Qianfan** (Baidu) | `ernie-5.1`, `ernie-x1.1` | `qianfan_api_key` |
| **ModelScope** | `Qwen/Qwen3.5-27B`, etc. | `modelscope_api_key` |
| **Xunfei Spark** | `xunfei` | `xunfei_api_key` (+ app id/secret) |
| **LinkAI** | any model name (one key, all models) | `linkai_api_key` |

> [!TIP]
> **DeepSeek V4 Flash is the default** because it balances strong tool-calling with low cost. For the most capable agent runs, the project recommends `claude-opus-4-8`, `gpt-5.4`, `gemini-3.1-pro-preview`, or `glm-5.1`.

> [!NOTE]
> CowAgent infers the right provider adapter from the **model name** — e.g. any name starting with `claude` routes to Claude, `gemini` to Gemini, `qwen` to DashScope, `glm` to Zhipu, `deepseek` to DeepSeek. You usually only need to set `model` plus the matching API key.

### 4.2 One key for everything: LinkAI

If you'd rather not sign up with every provider, **LinkAI** is a gateway that exposes all of the above through a single key:

```json
{
  "use_linkai": true,
  "linkai_api_key": "your-linkai-key",
  "model": "deepseek-v4-flash"
}
```

Get a LinkAI key at https://link-ai.tech/console/interface.

### 4.3 Custom OpenAI-compatible endpoints

To point CowAgent at any OpenAI-compatible API (a self-hosted gateway, a proxy, or a niche provider), set `bot_type` to `custom` and supply the base URL and key:

```json
{
  "model": "your-model-name",
  "bot_type": "custom",
  "custom_api_key": "sk-...",
  "custom_api_base": "https://your-endpoint/v1"
}
```

### 4.4 Thinking mode

Models that support extended reasoning can be asked to "think" before answering, trading latency and tokens for higher answer quality:

```json
{
  "enable_thinking": true,
  "reasoning_effort": "high"
}
```

`reasoning_effort` accepts `"high"` or `"max"`. Thinking is a global toggle; IM channels won't render the reasoning trace but still benefit from the improved answers.

---

## 5. Agent Mode: How CowAgent Thinks and Acts

Agent mode is what makes CowAgent more than a chatbot. It is **on by default** (`"agent": true`). When you send a message, the Agent runs a loop:

1. **Receive** your message through a channel.
2. **Understand** the intent and gather relevant context (memory, knowledge, attached files).
3. **Plan** — break a complex goal into steps.
4. **Act** — call tools (run a command, edit a file, search the web, drive the browser…) and observe the results.
5. **Update** its long-term memory and knowledge base with anything worth keeping.
6. **Reply** with the result.

It repeats steps 3–4 until the task is done or it hits the step limit (`agent_max_steps`, default 20).

> [!NOTE]
> Prefer **goals** over **questions**. "What's the weather API for my city?" gets you a chat answer. "Check the weather every morning at 8am and message me if it'll rain" gets you a scheduled, tool-using agent task.

### 5.1 The built-in tools

Tools are how the Agent reaches your operating system and the internet. CowAgent ships 10+ built-in tools (in the project's `agent/tools/` directory):

| Tool | What the Agent can do with it |
|---|---|
| **Read / Write / Edit** | Read, create, and modify files in your workspace |
| **Bash** | Run shell commands on your machine |
| **Browser** | Drive a real Chromium browser — visit pages, fill forms, click, screenshot, handle JS-rendered sites |
| **Web Search** | Search the web (needs `BOCHA_API_KEY` or `LINKAI_API_KEY`) |
| **Web Fetch** | Fetch and read the contents of a URL |
| **Send** | Send a file (image, video, document) back to you |
| **Scheduler** | Create one-time, interval, or cron-based scheduled tasks |
| **Memory** | Search the Agent's long-term memory |
| **Vision** | Analyze images you send |
| **Env Config** | Read and update the secret keys skills need (with masking) |
| **LS** | List files and directories |
| **MCP** | Call tools exposed by external Model Context Protocol servers |

> [!TIP]
> The Agent picks tools automatically based on your request — you never call them by name. Combined with the Bash and file tools, it can run a complete "vibecoding" workflow from your phone: research → generate assets → write code → test → deploy → configure Nginx → publish.

### 5.2 Installing the browser tool

The browser tool needs Playwright and Chromium, which aren't installed by default (they're large). Install them with one command:

```bash
cow install-browser
```

…or from chat with `/install-browser`. The installer adapts automatically to desktop and headless-server environments, installs the right Playwright version for your system's glibc, and (on Linux) adds a lightweight CJK font for rendering Chinese pages.

```text
🔧 Installing browser tool dependencies (a few minutes, please wait)…
📦 [1/3] Installing Playwright Python package…
✅ [1/3] Playwright package installed (1.52.0).
🔧 [2/3] Installing Linux system deps and a lightweight CJK font…
🌐 [3/3] Installing Chromium…
✅ Browser tool ready.
```

### 5.3 Tuning Agent behavior

| Setting | Meaning | Default |
|---|---|---|
| `agent` | Master switch for Agent mode | `true` |
| `agent_workspace` | Where the Agent stores skills, memory, and files | `~/cow` |
| `agent_max_context_tokens` | Max tokens of context kept in a run | `50000` |
| `agent_max_context_turns` | Max conversation turns remembered | `20` |
| `agent_max_steps` | Max tool/decision steps per task | `20` |
| `enable_thinking` | Use the model's extended-reasoning mode | `false` |
| `knowledge` | Enable the personal knowledge base | `true` |

> [!IMPORTANT]
> Agent mode consumes substantially more tokens than plain chat, because each task may involve many model calls (one per step). Choose a model that balances quality and cost — `deepseek-v4-flash` is the default for exactly this reason.

### 5.4 Classic chat mode

If you only want a conversational bot — no tools, no file access — set `"agent": false`. CowAgent then behaves like a traditional chat assistant with simple session memory, governed by `character_desc` (the persona) and `conversation_max_tokens`. This is lighter and cheaper, and it's the mode the classic [plugins](#12-plugins-classic-chat-mode) target.

---

## 6. Skills

A **skill** is a packaged capability — a Markdown instruction file (`SKILL.md`) with optional scripts and resources — that teaches the Agent how to perform a specific kind of task: generate an image, build a knowledge wiki, integrate a third-party API, and so on. Skills give the Agent essentially unlimited extensibility.

CowAgent follows the open **Agent Skills** standard: each skill declares what it does and what it needs (binaries, API keys, OS), and CowAgent **auto-enables** a skill whenever its requirements are met.

### 6.1 Where skills come from

| Source | How to use it |
|---|---|
| **Built-in** | Ship in the project's `skills/` directory (skill creator, image recognition, knowledge wiki, LinkAI agent…). Auto-enabled when their dependencies are present. |
| **Skill Hub** | The official marketplace at [skills.cowagent.ai](https://skills.cowagent.ai/). Install with one command. |
| **Third-party** | GitHub, ClawHub, LinkAI, or a direct URL. |
| **Custom** | Created by *you*, through conversation, using the `skill-creator` skill. Stored in `~/cow/skills/`. |

### 6.2 Managing skills

From the terminal or from chat (`cow skill …` ≡ `/skill …`):

```bash
cow skill list                 # list installed skills
cow skill list --remote        # browse the Skill Hub
cow skill search pdf           # search the hub for "pdf"
cow skill install pptx         # install the "pptx" skill
cow skill info pptx            # show details about a skill
cow skill enable pptx          # enable a skill
cow skill disable pptx         # disable a skill
cow skill uninstall pptx -y    # remove a skill (no confirmation prompt)
```

### 6.3 Creating your own skill by talking to the Agent

The `skill-creator` skill turns a conversation into a reusable skill. You don't write code — you describe the workflow, or paste an API's documentation, and the Agent builds the skill for you:

```text
You: I want a skill that, given a city name, fetches the 5-day forecast from
     the OpenWeatherMap API and formats it as a table. Here are the API docs: …
Agent: I'll create a "weather-forecast" skill. It needs an OPENWEATHER_API_KEY —
       I've added it to your skill config. Try: "5-day forecast for Tokyo".
```

The new skill lives in `~/cow/skills/` and is enabled automatically once its required key is set.

> [!TIP]
> Two especially useful built-in skills: **`openai-image-vision`** (image recognition — needs `OPENAI_API_KEY`) and the **image-generation** skill. The `web_search` tool is enabled by setting `BOCHA_API_KEY` or `LINKAI_API_KEY`.

---

## 7. Memory and the Knowledge Base

In Agent mode, CowAgent remembers. Two complementary systems work together: **memory** (organized along a timeline) and the **knowledge base** (organized by topic). Both live in the Agent workspace (`~/cow` by default).

### 7.1 Long-term memory

Memory flows through three tiers:

```text
conversation context  →  daily memory  →  MEMORY.md (core)
   (short-term)           (mid-term)        (long-term)
```

- On first launch, the Agent proactively asks who you are and what matters to you, and records it.
- During conversations it stores or retrieves memories as needed, updating its own settings, your preferences, and its memory files.
- A daily **Deep Dream** process distills scattered daily notes into refined long-term memory and writes a narrative "dream diary."
- Retrieval is hybrid — keyword **and** vector search — so the Agent recalls relevant context across sessions.

Workspace layout:

```text
~/cow/
├── SYSTEM.md          # the Agent's system prompt
├── USER.md            # your profile
├── MEMORY.md          # core (long-term) memory
├── memory/
│   └── YYYY-MM-DD.md  # daily memory
├── knowledge/         # personal knowledge base (see below)
└── skills/            # your custom skills
```

> [!NOTE]
> Secret keys used by skills are stored **separately** from the workspace, in `~/.cow/.env`, so they aren't mixed in with memory and knowledge content.

### 7.2 The personal knowledge base

The knowledge base turns articles, conversation insights, and learning material into an interconnected set of Markdown pages — a personal wiki that grows over time. It's controlled by the `knowledge` config flag (on by default) and stored in `~/cow/knowledge/`.

- **Auto-organization** — the Agent extracts structured knowledge from conversations and files it by topic, maintaining an index and cross-references.
- **Knowledge graph** — cross-references between pages build a graph you can browse interactively in the web console.
- **Clickable links** — knowledge links in the Agent's replies open the page directly in the console.

Manage it from chat:

```text
/knowledge           # show stats and the directory
/knowledge on        # enable the knowledge base
/knowledge off       # disable it
```

You can also browse the directory from the terminal with `cow knowledge list`.

---

## 8. Scheduled Tasks

The `scheduler` tool lets the Agent run things on a timer. You create schedules by simply asking — there's no cron file to edit.

Three timing modes are supported:

| Mode | Example request |
|---|---|
| **One-time** | "Remind me to call the dentist tomorrow at 3pm." |
| **Fixed interval** | "Every 30 minutes, check if my website is up." |
| **Cron expression** | "At 8am on weekdays, send me today's calendar." |

Each scheduled job runs as one of two kinds:

- **Fixed message** — sends a predetermined message at the scheduled time.
- **Agent task** — runs a full Agent execution (planning + tools) at the scheduled time, so it can fetch fresh data, make decisions, and act.

```text
You: Every morning at 8:00, search for the top AI news and send me a 3-bullet summary.
Agent: Scheduled. Daily at 08:00 I'll run a web search and message you a 3-bullet AI digest.
```

> [!NOTE]
> Scheduled Agent tasks can push messages to you proactively on any connected channel. The Agent keeps its scheduled-task history compact so recurring jobs don't bloat over time.

---

## 9. Connecting Messaging Channels

A single CowAgent instance can serve many channels at once. The active channels are set by `channel_type` in `config.json` — a single name, a comma-separated string, or a list:

```json
{ "channel_type": "feishu" }
{ "channel_type": "feishu, dingtalk" }
{ "channel_type": ["feishu", "dingtalk", "telegram"] }
```

The Web console (`web`) is started automatically alongside whatever else you configure, unless you set `"web_console": false`.

### 9.1 Available channels

| Channel | `channel_type` value | Notes |
|---|---|---|
| Web console | `web` | Default; always available |
| Terminal | `terminal` | Run `python app.py --cmd` for a local console |
| WeChat (personal) | `weixin` | Scan a QR code to log in |
| WeChat Official Account | `wechatmp`, `wechatmp_service` | Subscription / service accounts |
| WeCom self-built app | `wechatcom_app` | Enterprise WeChat application |
| WeCom smart bot | `wecom_bot` | Long-connection bot |
| WeChat Customer Service | `wechat_kf` | Kefu accounts |
| Feishu / Lark | `feishu` | WebSocket or webhook mode |
| DingTalk | `dingtalk` | Stream (long-connection) mode |
| QQ | `qq` | Official QQ bot |
| Telegram | `telegram` | Bot API |
| Slack | `slack` | Socket Mode (no public IP needed) |
| Discord | `discord` | Gateway connection |

> [!TIP]
> The easiest way to connect a channel is through the **web console** — it has guided forms for credentials. The interactive installer can also configure the most common channels for you. The settings below are for editing `config.json` directly.

### 9.2 Common channel setups

=== "Feishu (Lark)"

    ```json
    {
      "channel_type": "feishu",
      "feishu_app_id": "cli_xxx",
      "feishu_app_secret": "xxx",
      "feishu_event_mode": "websocket"
    }
    ```

    WebSocket mode needs no public IP. Streaming "typewriter" replies are on by
    default (`feishu_stream_reply`).

=== "DingTalk"

    ```json
    {
      "channel_type": "dingtalk",
      "dingtalk_client_id": "xxx",
      "dingtalk_client_secret": "xxx"
    }
    ```

=== "Telegram"

    ```json
    {
      "channel_type": "telegram",
      "telegram_token": "123456:ABC-DEF...",
      "telegram_group_trigger": "mention_or_reply"
    }
    ```

    Get the token from [@BotFather](https://t.me/botfather). Set `telegram_proxy`
    if you need a proxy.

=== "Slack"

    ```json
    {
      "channel_type": "slack",
      "slack_bot_token": "xoxb-...",
      "slack_app_token": "xapp-..."
    }
    ```

    Uses Socket Mode — no public IP required.

=== "Discord"

    ```json
    {
      "channel_type": "discord",
      "discord_token": "xxx",
      "discord_group_trigger": "mention_or_reply"
    }
    ```

=== "WeChat Official Account"

    ```json
    {
      "channel_type": "wechatmp",
      "wechatmp_token": "your-token",
      "wechatmp_app_id": "wx...",
      "wechatmp_app_secret": "xxx",
      "wechatmp_port": 8080
    }
    ```

### 9.3 When does the bot reply? (triggers)

In **single (1-on-1) chat**, by default a message must start with a trigger prefix to get a reply — `single_chat_prefix` defaults to `["bot", "@bot"]`. Set it to `[""]` to make the bot reply to *every* message.

In **group chat**, the bot replies when it's @-mentioned (`group_chat_prefix` defaults to `["@bot"]`) and the group is on the whitelist (`group_name_white_list`). For IM platforms like Telegram, Slack, and Discord, the `*_group_trigger` setting controls this with three modes:

| Mode | Behavior |
|---|---|
| `mention_or_reply` | Reply when @-mentioned or when someone replies to the bot (recommended) |
| `mention_only` | Reply only when explicitly @-mentioned |
| `all` | Reply to every message in the channel |

> [!WARNING]
> Setting a group trigger to `all` makes the bot respond to **every** message, which can be noisy and expensive. Use `mention_or_reply` unless you have a reason not to.

---

## 10. Voice: Speech-to-Text and Text-to-Speech

CowAgent can transcribe voice messages you send and reply with synthesized speech. Two settings pick the engines:

```json
{
  "voice_to_text": "openai",     // speech recognition (STT)
  "text_to_voice": "openai",     // speech synthesis (TTS)
  "speech_recognition": true,     // transcribe incoming voice
  "voice_reply_voice": false      // reply to a voice message with voice
}
```

### 10.1 Available voice engines

| Engine (`voice_to_text` / `text_to_voice`) | Notes |
|---|---|
| `openai` | OpenAI Whisper (STT) + TTS |
| `baidu` | Baidu speech (needs `baidu_app_id`/`baidu_api_key`/`baidu_secret_key`) |
| `google` | Google speech |
| `azure` | Azure speech (needs `azure_voice_api_key`/`azure_voice_region`) |
| `xunfei` | iFlytek Spark voice |
| `ali` / `dashscope` | Alibaba voice |
| `tencent` | Tencent cloud voice |
| `minimax` | MiniMax voice |
| `zhipu` | Zhipu voice |
| `mimo` | Xiaomi MiMo voice |
| `elevenlabs` | ElevenLabs TTS (needs `xi_api_key`) |
| `edge` | Microsoft Edge online TTS (free, no key) |
| `pytts` | Offline TTS (no network) |
| `linkai` | Voice via LinkAI |

### 10.2 Voice reply behavior

| Setting | Effect |
|---|---|
| `speech_recognition` | Transcribe incoming voice messages to text (default on) |
| `group_speech_recognition` | Also transcribe voice in group chats (default off) |
| `voice_reply_voice` | Reply with voice **when the user sent voice** |
| `always_reply_voice` | Always reply with voice, even to text |

> [!TIP]
> `edge` is a good zero-cost choice for text-to-speech — it's free and needs no API key. For fully offline operation, use `pytts`.

---

## 11. Command Reference: Terminal CLI and Chat Commands

CowAgent has **two** command surfaces. Don't confuse them:

- **Terminal CLI** (`cow …`) — manages the *service* (start/stop/update) and installs skills/tools. Run these in your shell.
- **Chat commands** (`/…`) — operate on the *running Agent's* live state (context, knowledge). Type these into a conversation.

### 11.1 Terminal CLI (`cow`)

| Command | Description |
|---|---|
| `cow start` | Start the service. `-f`/`--foreground` runs without daemonizing; `--no-logs` skips tailing logs |
| `cow stop` | Stop the service |
| `cow restart` | Restart the service (`--no-logs` to skip log tail) |
| `cow update` | Pull latest code, reinstall dependencies, restart |
| `cow status` | Show running status, model, and channel |
| `cow logs` | Tail the log. `-f`/`--follow` to follow; `-n`/`--lines N` to set line count (default 50) |
| `cow version` | Show the version |
| `cow help` | Show help |
| `cow install-browser` | Install the browser tool (Playwright + Chromium) |
| `cow knowledge list` | List the knowledge-base directory |
| `cow skill list` | List installed skills (`--remote` to browse the hub, `--page N`) |
| `cow skill search <query>` | Search the Skill Hub |
| `cow skill install <name>` | Install a skill |
| `cow skill uninstall <name>` | Remove a skill (`-y`/`--yes` to skip confirmation) |
| `cow skill enable <name>` | Enable a skill |
| `cow skill disable <name>` | Disable a skill |
| `cow skill info <name>` | Show skill details |

The `./run.sh` management script offers the same lifecycle verbs (`start`, `stop`, `restart`, `status`, `logs`, `config`, `update`) for setups where the `cow` command isn't on your `PATH`. `./run.sh config` re-runs the interactive model/channel configuration.

### 11.2 Chat commands (`/`)

Type these into any conversation (the web console shows a menu when you type `/`):

| Command | Description |
|---|---|
| `/context` | Show current conversation context info |
| `/context clear` | Clear conversation history for this session |
| `/cancel` | Immediately stop the Agent's current run |
| `/install-browser` | Install the browser tool from chat |
| `/knowledge` | Show knowledge-base stats and directory |
| `/knowledge on` / `/knowledge off` | Toggle the knowledge base |
| `/skill list` / `/skill list --remote` | List installed skills / browse the hub |
| `/skill search <keyword>` | Search the Skill Hub |
| `/skill install <name>` | Install a skill |

> [!TIP]
> Use `/cancel` (not "stop") to halt a long-running agent task mid-stream — it's processed immediately and won't get stuck behind the very task you're trying to cancel.

---

## 12. Plugins (Classic Chat Mode)

Separately from skills (which extend the *Agent*), CowAgent inherits a **plugin** system from its `chatgpt-on-wechat` lineage. Plugins hook into the message pipeline and are most relevant in classic chat mode. By default they're triggered with the `$` prefix (`plugin_trigger_prefix`), while admin commands use `#`.

### 12.1 Built-in plugins

| Plugin | Purpose |
|---|---|
| `godcmd` | Admin command center (authentication, model/config control) |
| `role` | Role-play personas ("act as …") |
| `keyword` | Keyword-triggered canned replies |
| `banwords` | Filter banned words from input and output |
| `finish` | Session-end handling |
| `hello` | Welcome new group members / greetings |
| `dungeon` | Text-adventure game mode |
| `linkai` | LinkAI platform integration (knowledge apps, Midjourney) |
| `tool` | Tool-calling plugin (classic) |

### 12.2 Installing third-party plugins

Admins can install community plugins from a Git repository. CowAgent ships a small catalog (in `plugins/source.json`) of known plugins — image generation (`sdwebui`, `midjourney`, `replicate`), chat summary (`summary`), utility info lookups (`Apilot`), group task boards, and more.

Use the admin chat commands (sent with the `#` prefix) to install and scan plugins:

```text
#installp <name-or-git-url>    # install a plugin
#scanp                          # scan and load newly installed plugins
```

After installing, check whether the plugin needs configuration before enabling it.

> [!NOTE]
> Preset plugins (`hello`, `godcmd`, `role`, `tool`, `banwords`, `finish`, `dungeon`) ship with the project and update when you update CowAgent itself — they can't be updated individually.

---

## 13. Security & Safety for Users

CowAgent is powerful precisely because it can touch your system and the internet. Treat it accordingly.

> [!CAUTION]
> **The Agent can run arbitrary commands and edit files on the machine it runs on.** Deploy it only in environments you trust and control. Do not run it as `root`/Administrator if you can avoid it, and prefer a dedicated user account.

Key safeguards to set up:

- **Password-protect the web console.** It has no password by default. If the console is reachable beyond `localhost`, set one:

  ```json
  { "web_password": "a-strong-password", "web_session_expire_days": 30 }
  ```

- **Limit file serving.** The console's file endpoint serves files under `web_file_serve_root` (default `~`). **Never** set it to `/` on a shared or networked machine — that exposes your entire filesystem.

  ```json
  { "web_file_serve_root": "~/cow" }
  ```

- **Keep API keys out of shared configs.** Keys live in plaintext in `config.json`. CowAgent can read them from environment variables instead (set an env var with the same name as the config key, uppercased) — useful for platforms like Railway where you don't want secrets in a file. Logs automatically mask anything that looks like a key or secret.

- **Be careful what you install.** Installing a skill or a plugin can pull and run third-party code. Only install from sources you trust (the official Skill Hub, reputable GitHub repos).

> [!IMPORTANT]
> **WeChat Official Account users:** there is a known issue (#2860) where webhook signature verification is bypassed if `wechatmp_token` is left empty. Always set a non-empty `wechatmp_token` for any public-facing Official Account channel.

---

## 14. Troubleshooting

### Error: `Found Python 3.13, but this project requires Python 3.7-3.12`

**Cause:** Python 3.13 removed the standard-library `cgi` module that `web.py` depends on.
**Solution:** Install Python 3.7–3.12 (3.12 recommended) and re-run the installer. On systems with multiple Pythons, the installer auto-selects a compatible one if it exists.
**Prevention:** Don't upgrade the project's Python to 3.13+ until upstream support lands.

### Error: `config.json not found`

**Cause:** You ran `cow start` before configuring.
**Solution:** Run the installer (`./run.sh`) or copy the template: `cp config-template.json config.json`, then set your `model` and API key.
**Prevention:** The one-line installer creates `config.json` for you.

### Problem: The bot doesn't reply in 1-on-1 chat

**Cause:** `single_chat_prefix` requires your message to start with a trigger word (default `bot` or `@bot`).
**Solution:** Either prefix your message with `bot`, or set `"single_chat_prefix": [""]` to reply to everything.
**Prevention:** Decide your preferred trigger up front.

### Problem: The bot doesn't reply in a group

**Cause:** The group isn't whitelisted, or the trigger mode is too strict.
**Solution:** Add the group name to `group_name_white_list` (or use `"ALL_GROUP"`), and @-mention the bot. For Telegram/Slack/Discord, set `*_group_trigger` to `mention_or_reply`.
**Prevention:** Configure the whitelist when you connect the channel.

### Error: Browser tool fails or "playwright not found"

**Cause:** The browser tool's dependencies aren't installed (they're optional and large).
**Solution:** Run `cow install-browser` (or `/install-browser`). On Linux servers, system deps may need `sudo`; the installer prints the exact command if it can't do it automatically.
**Prevention:** Install the browser tool before asking the Agent to browse the web.

### Problem: WeChat QR-code login won't complete

**Cause:** Some device/OS combinations (e.g. HarmonyOS, issue #2856) have trouble with QR scan-login.
**Solution:** Retry the login; ensure the account is permitted to log in via the protocol. Deleting the cached credentials file (`~/.weixin_cow_credentials.json`) forces a fresh QR login.
**Prevention:** Use a supported device for the initial login.

### Problem: Replies are slow or token costs are high

**Cause:** Agent mode makes many model calls per task, especially with thinking enabled.
**Solution:** Switch to a faster/cheaper model like `deepseek-v4-flash`, turn off `enable_thinking`, or lower `agent_max_steps`. For purely conversational use, set `"agent": false`.
**Prevention:** Match the model and step budget to the task.

### Problem: A scheduled task isn't firing

**Cause:** The task wasn't created successfully, or the service was restarted.
**Solution:** Ask the Agent to list your scheduled tasks; recreate it if missing. The scheduler starts automatically at boot, so a running service should fire jobs.
**Prevention:** Confirm the schedule with the Agent after creating it.

### Problem: How do I stop a runaway agent task?

**Solution:** Send `/cancel` in the conversation — it stops the current run immediately. To stop the whole service, run `cow stop`.

---

## 15. Frequently Asked Questions

**Q: What is CowAgent, in one sentence?**
An open-source, self-hosted AI assistant that plans and executes real tasks on your computer — using tools, skills, memory, and a knowledge base — and talks to you through a web console or any of a dozen messaging apps.

**Q: Is it free?**
The software is open-source under the MIT License. You pay only for the LLM API usage of whichever provider you choose (or a single LinkAI subscription).

**Q: How is this different from `chatgpt-on-wechat`?**
CowAgent is the Agent-era successor. The original answered messages; CowAgent plans multi-step tasks, runs tools, edits files, and maintains long-term memory and knowledge.

**Q: Does my data go to the cloud?**
No, not by default. CowAgent runs entirely locally; your messages, files, and keys stay on your machine. Only your chosen LLM provider receives the prompts you send. The optional LinkAI cloud console is off unless you explicitly enable it.

**Q: Can I use it without any coding?**
Yes. The interactive installer and the web console cover setup, model selection, channel connection, and skill installation without editing files.

**Q: Can one instance serve WeChat and Telegram at the same time?**
Yes. Set `"channel_type": ["weixin", "telegram"]` (or a comma-separated string). The web console runs alongside them automatically.

**Q: Which model should I use?**
Start with the default `deepseek-v4-flash` (fast, cheap, good at tool use). For maximum capability, try `claude-opus-4-8`, `gpt-5.4`, `gemini-3.1-pro-preview`, or `glm-5.1`.

**Q: Do I need a public IP or open ports?**
Not for most channels. The web console is local; Feishu (WebSocket), DingTalk, Slack (Socket Mode), Discord, and Telegram all work without a public IP. WeChat Official Account and WeCom self-built app channels do need an inbound webhook.

**Q: How do I give the Agent web-search ability?**
Set `BOCHA_API_KEY` or `LINKAI_API_KEY` (e.g. as a skill secret via `env_config`, or in your environment). The `web_search` tool enables automatically.

**Q: Where does the Agent keep its memory and skills?**
In the workspace directory, `~/cow` by default (configurable with `agent_workspace`). Secrets live in `~/.cow/.env`.

**Q: Can I run it on a server 24/7?**
Yes — that's a primary use case. Install with the one-liner, use `cow start`/`cow status`/`cow logs` to manage it, and connect a remote channel so you can reach it from your phone. See the **Admin Guide** for hardened deployment.

**Q: How do I update?**
`cow update` pulls the latest code, reinstalls dependencies, and restarts.

**Q: The Agent is doing something I didn't intend — how do I stop it?**
Send `/cancel` in chat to abort the current task, or `cow stop` to stop the service.

---

## 16. Quick Reference

**Install & run**

```bash
bash <(curl -fsSL https://cdn.link-ai.tech/code/cow/run.sh)   # install + configure + start
cow start | stop | restart | status | logs | update           # manage the service
cow install-browser                                           # add the browser tool
```

**Minimal `config.json`**

```json
{
  "model": "deepseek-v4-flash",
  "deepseek_api_key": "your-key",
  "channel_type": "web",
  "agent": true
}
```

**Most-used settings**

| Setting | Purpose | Default |
|---|---|---|
| `model` | Which LLM to use | `gpt-3.5-turbo` (template ships `deepseek-v4-flash`) |
| `channel_type` | Where to chat (one or many) | `web` |
| `agent` | Agent mode on/off | `true` |
| `enable_thinking` | Extended reasoning | `false` |
| `web_port` | Web console port | `9899` |
| `web_password` | Web console password | empty (no auth) |
| `single_chat_prefix` | 1-on-1 trigger words | `["bot", "@bot"]` |

**Key chat commands:** `/context clear` · `/cancel` · `/knowledge` · `/skill list` · `/install-browser`
**Key terminal commands:** `cow start` · `cow logs` · `cow update` · `cow skill install <name>`
**Web console:** http://localhost:9899 · **Skill Hub:** https://skills.cowagent.ai

---

_Generated June 2026 from zhayujie/CowAgent at 2b670e7. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._