mirror of
https://github.com/zhayujie/chatgpt-on-wechat.git
synced 2026-07-19 21:07:28 +08:00
docs: add CLI system docs
This commit is contained in:
zhayujie
@@ -20,13 +20,14 @@
|
||||
|
||||
> CowAgent is both an out-of-the-box AI super assistant and a highly extensible Agent framework. You can extend it with new model interfaces, channels, built-in tools, and the Skills system to flexibly implement various customization needs.
|
||||
|
||||
- ✅ **Autonomous Task Planning**: Understands complex tasks and autonomously plans execution, continuously thinking and invoking tools until goals are achieved. Supports accessing files, terminal, browser, schedulers, and other system resources via tools.
|
||||
- ✅ **Autonomous Task Planning**: Understands complex tasks and autonomously plans execution, continuously thinking and invoking tools until goals are achieved.
|
||||
- ✅ **Long-term Memory**: Automatically persists conversation memory to local files and databases, including core memory and daily memory, with keyword and vector retrieval support.
|
||||
- ✅ **Skills System**: Implements a Skills creation and execution engine with multiple built-in skills, and supports custom Skills development through natural language conversation.
|
||||
- ✅ **Skills System**: Implements a Skills creation and execution engine, supports installing skills from [Skill Hub](https://skills.cowagent.ai), GitHub, etc., or creating custom Skills through conversation.
|
||||
- ✅ **Tool System**: Built-in tools for file I/O, terminal execution, browser automation, scheduled tasks, messaging, and more — autonomously invoked by the Agent.
|
||||
- ✅ **CLI System**: Provides terminal commands and in-chat commands for process management, skill installation, configuration, and more.
|
||||
- ✅ **Multimodal Messages**: Supports parsing, processing, generating, and sending text, images, voice, files, and other message types.
|
||||
- ✅ **Multiple Model Support**: Supports OpenAI, Claude, Gemini, DeepSeek, MiniMax, GLM, Qwen, Kimi, Doubao, and other mainstream model providers.
|
||||
- ✅ **Multi-platform Deployment**: Runs on local computers or servers, integrable into WeChat, Web, Feishu, DingTalk, WeChat Official Account, and WeCom applications.
|
||||
- ✅ **Knowledge Base**: Integrates enterprise knowledge base capabilities via the [LinkAI](https://link-ai.tech) platform.
|
||||
|
||||
## Disclaimer
|
||||
|
||||
@@ -66,7 +67,7 @@ bash <(curl -fsSL https://cdn.link-ai.tech/code/cow/run.sh)
|
||||
|
||||
After running, the Web service starts by default. Access `http://localhost:9899/chat` to chat.
|
||||
|
||||
Script usage: [One-click Install](https://docs.cowagent.ai/en/guide/quick-start)
|
||||
Script usage: [One-click Install](https://docs.cowagent.ai/en/guide/quick-start). After installation, you can also use `cow start`, `cow stop`, and other [CLI commands](https://docs.cowagent.ai/en/commands/index) to manage the service.
|
||||
|
||||
### Manual Installation
|
||||
|
||||
@@ -84,7 +85,25 @@ pip3 install -r requirements.txt
|
||||
pip3 install -r requirements-optional.txt # optional but recommended
|
||||
```
|
||||
|
||||
**3. Configure**
|
||||
**3. Install Cow CLI (recommended)**
|
||||
|
||||
```bash
|
||||
pip3 install -e .
|
||||
```
|
||||
|
||||
After installation, use `cow` commands to manage the service (start, stop, update, etc.) and skills. See [Command Docs](https://docs.cowagent.ai/en/commands/index).
|
||||
|
||||
**4. Install browser (optional)**
|
||||
|
||||
If you need the Agent to operate a browser (visit web pages, fill forms, etc.):
|
||||
|
||||
```bash
|
||||
cow install-browser
|
||||
```
|
||||
|
||||
This auto-installs `playwright` and Chromium. See [Browser Tool Docs](https://docs.cowagent.ai/en/tools/browser).
|
||||
|
||||
**5. Configure**
|
||||
|
||||
```bash
|
||||
cp config-template.json config.json
|
||||
@@ -92,13 +111,25 @@ cp config-template.json config.json
|
||||
|
||||
Fill in your model API key and channel type in `config.json`. See the [configuration docs](https://docs.cowagent.ai/en/guide/manual-install) for details.
|
||||
|
||||
**4. Run**
|
||||
**6. Run**
|
||||
|
||||
```bash
|
||||
python3 app.py
|
||||
cow start # recommended, requires Cow CLI
|
||||
python3 app.py # or run directly
|
||||
```
|
||||
|
||||
For server background run:
|
||||
For server deployment, use `cow` commands to manage the service:
|
||||
|
||||
```bash
|
||||
cow start # start in background
|
||||
cow stop # stop service
|
||||
cow restart # restart service
|
||||
cow status # check running status
|
||||
cow logs # view logs
|
||||
cow update # pull latest code and restart
|
||||
```
|
||||
|
||||
Or use the traditional way:
|
||||
|
||||
```bash
|
||||
nohup python3 app.py & tail -f nohup.out
|
||||
@@ -195,7 +226,7 @@ FAQs: <https://github.com/zhayujie/chatgpt-on-wechat/wiki/FAQs>
|
||||
|
||||
## 🛠️ Contributing
|
||||
|
||||
Welcome to add new channels, referring to the [Feishu channel](https://github.com/zhayujie/chatgpt-on-wechat/blob/master/channel/feishu/feishu_channel.py) as an example. Also welcome to contribute new Skills, referring to the [Skill Creator docs](https://github.com/zhayujie/chatgpt-on-wechat/blob/master/skills/skill-creator/SKILL.md).
|
||||
Welcome to add new channels, referring to the [Feishu channel](https://github.com/zhayujie/chatgpt-on-wechat/blob/master/channel/feishu/feishu_channel.py) as an example. Also welcome to contribute new Skills, see the [Skill Creation docs](https://docs.cowagent.ai/en/skills/create).
|
||||
|
||||
## ✉ Contact
|
||||
|
||||
|
||||
101
docs/en/commands/general.mdx
Normal file
101
docs/en/commands/general.mdx
Normal file
@@ -0,0 +1,101 @@
|
||||
---
|
||||
title: General Commands
|
||||
description: 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).
|
||||
|
||||
<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
|
||||
```
|
||||
|
||||
## 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-chat
|
||||
```
|
||||
|
||||
**Configurable items:**
|
||||
|
||||
| Item | Description | Example |
|
||||
| --- | --- | --- |
|
||||
| `model` | AI model name | `deepseek-chat` |
|
||||
| `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` |
|
||||
|
||||
<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
|
||||
/context clear
|
||||
```
|
||||
|
||||
<Tip>
|
||||
Clearing context makes the Agent "forget" previous conversation, useful for switching topics or freeing context space.
|
||||
</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
|
||||
```
|
||||
84
docs/en/commands/index.mdx
Normal file
84
docs/en/commands/index.mdx
Normal file
@@ -0,0 +1,84 @@
|
||||
---
|
||||
title: Commands Overview
|
||||
description: CowAgent command system — Terminal CLI and chat commands
|
||||
---
|
||||
|
||||
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 ...)
|
||||
|
||||
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 |
|
||||
| `/config` | View or modify runtime configuration |
|
||||
| `/skill` | Manage skills (install, uninstall, enable, disable, etc.) |
|
||||
| `/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 | ✓ | ✓ |
|
||||
| config | ✗ | ✓ |
|
||||
| context | — | ✓ |
|
||||
| skill (subcommands) | ✓ | ✓ |
|
||||
| start / stop / restart | ✓ | ✗ |
|
||||
| update | ✓ | ✗ |
|
||||
| install-browser | ✓ | ✗ |
|
||||
|
||||
<Note>
|
||||
`context` only shows a hint in the terminal to use it in chat. `config` is only available in chat.
|
||||
</Note>
|
||||
123
docs/en/commands/process.mdx
Normal file
123
docs/en/commands/process.mdx
Normal file
@@ -0,0 +1,123 @@
|
||||
---
|
||||
title: Process Management
|
||||
description: 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
|
||||
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
|
||||
cow stop
|
||||
```
|
||||
|
||||
## restart
|
||||
|
||||
Restart the CowAgent service (stop then start).
|
||||
|
||||
```bash
|
||||
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
|
||||
cow update
|
||||
```
|
||||
|
||||
<Warning>
|
||||
If `git pull` fails (e.g., uncommitted local changes), the update aborts and the service remains unaffected.
|
||||
</Warning>
|
||||
|
||||
## status
|
||||
|
||||
Check CowAgent service status, including process info, version, and current model/channel configuration.
|
||||
|
||||
```bash
|
||||
cow status
|
||||
```
|
||||
|
||||
## logs
|
||||
|
||||
View service logs.
|
||||
|
||||
```bash
|
||||
cow logs
|
||||
```
|
||||
|
||||
**Options:**
|
||||
|
||||
| Option | Description | Default |
|
||||
| --- | --- | --- |
|
||||
| `-f`, `--follow` | Continuously tail log output | No |
|
||||
| `-n`, `--lines` | Show last N lines | 50 |
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
# 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](/en/tools/browser).
|
||||
|
||||
```bash
|
||||
cow install-browser
|
||||
```
|
||||
|
||||
<Tip>
|
||||
Only needed when using browser tools (web browsing, screenshots, etc.).
|
||||
</Tip>
|
||||
|
||||
## run.sh Compatibility
|
||||
|
||||
If Cow CLI is not installed, you can use `run.sh` to manage the service:
|
||||
|
||||
| cow command | run.sh equivalent |
|
||||
| --- | --- |
|
||||
| `cow start` | `./run.sh start` |
|
||||
| `cow stop` | `./run.sh stop` |
|
||||
| `cow restart` | `./run.sh restart` |
|
||||
| `cow update` | `./run.sh update` |
|
||||
| `cow status` | `./run.sh status` |
|
||||
| `cow logs` | `./run.sh logs` |
|
||||
|
||||
<Note>
|
||||
The `cow` command is recommended — it provides cleaner syntax and richer features. It is automatically installed via the one-click install script.
|
||||
</Note>
|
||||
192
docs/en/commands/skill.mdx
Normal file
192
docs/en/commands/skill.mdx
Normal file
@@ -0,0 +1,192 @@
|
||||
---
|
||||
title: Skill Management
|
||||
description: Install, uninstall, enable, disable, and manage skills via commands
|
||||
---
|
||||
|
||||
Skill management commands are used to install, query, and manage CowAgent skills. Use `/skill <subcommand>` in chat or `cow skill <subcommand>` in the terminal.
|
||||
|
||||
## list
|
||||
|
||||
List installed skills and their status.
|
||||
|
||||
<CodeGroup>
|
||||
```text Chat
|
||||
/skill list
|
||||
```
|
||||
|
||||
```bash Terminal
|
||||
cow skill list
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
**Browse the Skill Hub** (view all available skills):
|
||||
|
||||
<CodeGroup>
|
||||
```text Chat
|
||||
/skill list --remote
|
||||
```
|
||||
|
||||
```bash Terminal
|
||||
cow skill list --remote
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
**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.
|
||||
|
||||
<CodeGroup>
|
||||
```text Chat
|
||||
/skill search pptx
|
||||
```
|
||||
|
||||
```bash Terminal
|
||||
cow skill search pptx
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
## 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):**
|
||||
|
||||
<CodeGroup>
|
||||
```text Chat
|
||||
/skill install pptx
|
||||
```
|
||||
|
||||
```bash Terminal
|
||||
cow skill install pptx
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
**From GitHub:**
|
||||
|
||||
<CodeGroup>
|
||||
```text Chat
|
||||
# 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
|
||||
# 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
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
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:**
|
||||
|
||||
<CodeGroup>
|
||||
```text Chat
|
||||
/skill install clawhub:baidu-search
|
||||
```
|
||||
|
||||
```bash Terminal
|
||||
cow skill install clawhub:baidu-search
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
**From URL:**
|
||||
|
||||
<CodeGroup>
|
||||
```text Chat
|
||||
# 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
|
||||
# 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
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
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.
|
||||
|
||||
<CodeGroup>
|
||||
```text Chat
|
||||
/skill uninstall pptx
|
||||
```
|
||||
|
||||
```bash Terminal
|
||||
cow skill uninstall pptx
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Warning>
|
||||
Uninstalling deletes all files in the skill directory. This action cannot be undone.
|
||||
</Warning>
|
||||
|
||||
## enable / disable
|
||||
|
||||
Enable or disable a skill. Disabled skills will not be invoked by the Agent.
|
||||
|
||||
<CodeGroup>
|
||||
```text Chat
|
||||
/skill enable pptx
|
||||
/skill disable pptx
|
||||
```
|
||||
|
||||
```bash Terminal
|
||||
cow skill enable pptx
|
||||
cow skill disable pptx
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
## info
|
||||
|
||||
View details of an installed skill, including a preview of its `SKILL.md`.
|
||||
|
||||
<CodeGroup>
|
||||
```text Chat
|
||||
/skill info pptx
|
||||
```
|
||||
|
||||
```bash Terminal
|
||||
cow skill info pptx
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
## 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 |
|
||||
@@ -30,7 +30,25 @@ Optional dependencies (recommended):
|
||||
pip3 install -r requirements-optional.txt
|
||||
```
|
||||
|
||||
### 3. Configure
|
||||
### 3. Install Cow CLI
|
||||
|
||||
Install the command-line tool for managing services and skills:
|
||||
|
||||
```bash
|
||||
pip3 install -e .
|
||||
```
|
||||
|
||||
Then use the `cow` command:
|
||||
|
||||
```bash
|
||||
cow help
|
||||
```
|
||||
|
||||
<Note>
|
||||
This step is recommended. After installation you can use `cow start`, `cow stop`, `cow update` to manage the service, and `cow skill` to manage skills. Without the CLI, you can use `./run.sh` or `python3 app.py` to run.
|
||||
</Note>
|
||||
|
||||
### 4. Configure
|
||||
|
||||
Copy the config template and edit:
|
||||
|
||||
@@ -40,22 +58,32 @@ cp config-template.json config.json
|
||||
|
||||
Fill in model API keys, channel type, and other settings in `config.json`. See the [model docs](/en/models/index) for details.
|
||||
|
||||
### 4. Run
|
||||
### 5. Run
|
||||
|
||||
**Local run:**
|
||||
**Using Cow CLI (recommended):**
|
||||
|
||||
```bash
|
||||
cow start
|
||||
```
|
||||
|
||||
**Or run locally in foreground:**
|
||||
|
||||
```bash
|
||||
python3 app.py
|
||||
```
|
||||
|
||||
By default, the Web service starts. Access `http://localhost:9899/chat` to chat.
|
||||
By default, the Web console starts. Access `http://localhost:9899` to chat.
|
||||
|
||||
**Background run on server:**
|
||||
**Background run on server (without CLI):**
|
||||
|
||||
```bash
|
||||
nohup python3 app.py & tail -f nohup.out
|
||||
```
|
||||
|
||||
<Tip>
|
||||
If deploying on a server, open port `9899` in your firewall or security group to access the Web console. It's recommended to restrict access to specific IPs for security.
|
||||
</Tip>
|
||||
|
||||
## Docker Deployment
|
||||
|
||||
Docker deployment does not require cloning source code or installing dependencies. For Agent mode, source deployment is recommended for broader system access.
|
||||
@@ -84,6 +112,10 @@ sudo docker compose up -d
|
||||
sudo docker logs -f chatgpt-on-wechat
|
||||
```
|
||||
|
||||
<Tip>
|
||||
If deploying on a server, open port `9899` in your firewall or security group to access the Web console. It's recommended to restrict access to specific IPs for security.
|
||||
</Tip>
|
||||
|
||||
## Core Configuration
|
||||
|
||||
```json
|
||||
|
||||
@@ -18,22 +18,27 @@ 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 `~/chatgpt-on-wechat`
|
||||
4. Install Python dependencies
|
||||
4. Install Python dependencies and Cow CLI
|
||||
5. Guided configuration for AI model and channel
|
||||
6. Start service
|
||||
|
||||
By default, the Web service starts after installation. Access `http://localhost:9899/chat` to begin chatting.
|
||||
By default, the Web console starts after installation. Access `http://localhost:9899` to begin chatting.
|
||||
|
||||
## Management Commands
|
||||
|
||||
After installation, use these commands to manage the service:
|
||||
After installation, use the `cow` command to manage the service:
|
||||
|
||||
| Command | Description |
|
||||
| --- | --- |
|
||||
| `./run.sh start` | Start service |
|
||||
| `./run.sh stop` | Stop service |
|
||||
| `./run.sh restart` | Restart service |
|
||||
| `./run.sh status` | Check run status |
|
||||
| `./run.sh logs` | View real-time logs |
|
||||
| `./run.sh config` | Reconfigure |
|
||||
| `./run.sh update` | Update project code |
|
||||
| `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 |
|
||||
|
||||
See the [Commands documentation](/en/commands/index) for more details.
|
||||
|
||||
<Note>
|
||||
If the `cow` command is not available, you can use `./run.sh <command>` as a fallback (e.g., `./run.sh start`, `./run.sh stop`). Both are functionally equivalent.
|
||||
</Note>
|
||||
|
||||
@@ -28,6 +28,12 @@ CowAgent can proactively think and plan tasks, operate computers and external re
|
||||
<Card title="Multimodal Messages" icon="image" href="/en/channels/web">
|
||||
Supports parsing, processing, generating, and sending text, images, voice, files, and other message types.
|
||||
</Card>
|
||||
<Card title="Tool System" icon="wrench" href="/en/tools/index">
|
||||
Built-in tools for file I/O, terminal execution, browser automation, scheduled tasks, messaging, and more. The Agent autonomously invokes tools to accomplish complex tasks.
|
||||
</Card>
|
||||
<Card title="Command System" icon="terminal" href="/en/commands/index">
|
||||
Provides terminal CLI and in-chat commands for process management, skill installation, configuration, context inspection, and other common operations.
|
||||
</Card>
|
||||
<Card title="Multiple Model Support" icon="microchip" href="/en/models/index">
|
||||
Supports mainstream model providers including OpenAI, Claude, Gemini, DeepSeek, MiniMax, GLM, Qwen, Kimi, Doubao, and more.
|
||||
</Card>
|
||||
|
||||
80
docs/en/memory/context.mdx
Normal file
80
docs/en/memory/context.mdx
Normal file
@@ -0,0 +1,80 @@
|
||||
---
|
||||
title: Short-term Memory
|
||||
description: 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 | `50000` |
|
||||
| `agent_max_context_turns` | Maximum conversation turns in context | `20` |
|
||||
| `agent_max_steps` | Maximum decision steps per turn (tool call count) | `15` |
|
||||
|
||||
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**
|
||||
- Remaining turns stay intact
|
||||
|
||||
### 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 also written to memory
|
||||
|
||||
### 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
|
||||
|
||||
## 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) |
|
||||
| `/context clear` | Clear current session context |
|
||||
| `/config agent_max_context_tokens 80000` | Adjust context token budget |
|
||||
| `/config agent_max_context_turns 30` | Adjust context turn limit |
|
||||
|
||||
<Tip>
|
||||
After clearing context, the Agent "forgets" previous conversation content. Content that was already written to long-term memory can still be retrieved via memory search.
|
||||
</Tip>
|
||||
@@ -1,30 +1,39 @@
|
||||
---
|
||||
title: Memory
|
||||
description: CowAgent long-term memory system
|
||||
title: Long-term Memory
|
||||
description: CowAgent long-term memory system — file persistence, automatic writing, and hybrid retrieval
|
||||
---
|
||||
|
||||
The memory system enables the Agent to remember important information over time, continuously accumulating experience, understanding user preferences, and truly achieving autonomous thinking and continuous growth.
|
||||
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. Automatically injected into the system prompt on every conversation turn as background knowledge.
|
||||
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.
|
||||
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.
|
||||
|
||||
## Memory Writing
|
||||
## Automatic Writing
|
||||
|
||||
The Agent automatically persists conversation content to daily memory through the following mechanisms:
|
||||
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 in batch, and the discarded content is summarized by LLM into key information and written to the daily memory file
|
||||
- **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
|
||||
- **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)
|
||||
- **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.
|
||||
|
||||
## First Launch
|
||||
|
||||
On first launch, the Agent will proactively ask the user for key information and save it to the workspace (default `~/cow`):
|
||||
@@ -40,27 +49,10 @@ On first launch, the Agent will proactively ask the user for key information and
|
||||
<img src="https://cdn.link-ai.tech/doc/20260203000455.png" width="800" />
|
||||
</Frame>
|
||||
|
||||
## Memory Retrieval
|
||||
|
||||
The memory system supports hybrid retrieval modes:
|
||||
|
||||
- **Keyword retrieval** — Match historical memory based on keywords
|
||||
- **Vector retrieval** — 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. Core memory (`MEMORY.md`) is always injected into the system prompt, while daily memory is loaded on demand via retrieval.
|
||||
|
||||
## Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"agent_workspace": "~/cow",
|
||||
"agent_max_context_tokens": 40000,
|
||||
"agent_max_context_turns": 20
|
||||
}
|
||||
```
|
||||
|
||||
| Parameter | Description | Default |
|
||||
| --- | --- | --- |
|
||||
| `agent_workspace` | Workspace path, memory files stored under this directory | `~/cow` |
|
||||
| `agent_max_context_tokens` | Max context tokens; when exceeded, half is trimmed and summarized into memory | `40000` |
|
||||
| `agent_max_context_turns` | Max context turns; when exceeded, half is trimmed and summarized into memory | `20` |
|
||||
| `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` |
|
||||
58
docs/en/skills/create.mdx
Normal file
58
docs/en/skills/create.mdx
Normal file
@@ -0,0 +1,58 @@
|
||||
---
|
||||
title: Create Skills
|
||||
description: 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
|
||||
|
||||
<Frame>
|
||||
<img src="https://cdn.link-ai.tech/doc/20260202202247.png" width="800" />
|
||||
</Frame>
|
||||
|
||||
## SKILL.md Format
|
||||
|
||||
Created skills follow the standard SKILL.md format:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-skill
|
||||
description: Brief description of the skill
|
||||
metadata:
|
||||
emoji: 🔧
|
||||
requires:
|
||||
bins: ["curl"]
|
||||
env: ["MY_API_KEY"]
|
||||
primaryEnv: "MY_API_KEY"
|
||||
---
|
||||
|
||||
# My Skill
|
||||
|
||||
Detailed instructions...
|
||||
```
|
||||
|
||||
| Field | Description |
|
||||
| --- | --- |
|
||||
| `name` | Skill name, must match directory name |
|
||||
| `description` | Skill description, Agent decides whether to invoke based on this |
|
||||
| `metadata.requires.bins` | Required system commands |
|
||||
| `metadata.requires.env` | Required environment variables |
|
||||
| `metadata.always` | Always load (default false) |
|
||||
|
||||
<Tip>
|
||||
See the [Skill Creator documentation](https://github.com/zhayujie/chatgpt-on-wechat/blob/master/skills/skill-creator/SKILL.md) for details.
|
||||
</Tip>
|
||||
@@ -1,31 +0,0 @@
|
||||
---
|
||||
title: Image Vision
|
||||
description: Recognize images using OpenAI vision models
|
||||
---
|
||||
|
||||
Analyze image content using OpenAI's GPT-4 Vision API, understanding objects, text, colors, and other elements in images.
|
||||
|
||||
## Dependencies
|
||||
|
||||
| Dependency | Description |
|
||||
| --- | --- |
|
||||
| `OPENAI_API_KEY` | OpenAI API key |
|
||||
| `curl`, `base64` | System commands (usually pre-installed) |
|
||||
|
||||
Configuration:
|
||||
|
||||
- Configure `OPENAI_API_KEY` via the `env_config` tool
|
||||
- Or set `open_ai_api_key` in `config.json`
|
||||
|
||||
## Supported Models
|
||||
|
||||
- `gpt-4.1-mini` (recommended, cost-effective)
|
||||
- `gpt-4.1`
|
||||
|
||||
## Usage
|
||||
|
||||
Once configured, send an image to the Agent to automatically trigger image recognition.
|
||||
|
||||
<Frame>
|
||||
<img src="https://cdn.link-ai.tech/doc/20260202213219.png" width="800" />
|
||||
</Frame>
|
||||
@@ -7,20 +7,17 @@ Skills provide infinite extensibility for the Agent. Each Skill consists of a de
|
||||
|
||||
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.
|
||||
|
||||
## Built-in Skills
|
||||
## Getting Skills
|
||||
|
||||
Located in the project `skills/` directory, automatically enabled based on dependency conditions:
|
||||
CowAgent offers multiple ways to acquire skills:
|
||||
|
||||
| Skill | Description | Dependencies |
|
||||
| --- | --- | --- |
|
||||
| [`skill-creator`](/en/skills/skill-creator) | Create custom skills through conversation | None |
|
||||
| [`openai-image-vision`](/en/skills/image-vision) | Recognize images using OpenAI vision models | `OPENAI_API_KEY` |
|
||||
| [`linkai-agent`](/en/skills/linkai-agent) | Integrate LinkAI platform agents | `LINKAI_API_KEY` |
|
||||
| [`web-fetch`](/en/skills/web-fetch) | Fetch web page text content | `curl` (enabled by default) |
|
||||
- **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
|
||||
|
||||
## Custom Skills
|
||||
|
||||
Created by users through conversation, stored in workspace (`~/cow/skills/`), can implement any complex business process and third-party system integration.
|
||||
See [Install Skills](/en/skills/install) and [Skill Management Commands](/en/commands/skill) for details. You can also [create skills](/en/skills/create) through conversation.
|
||||
|
||||
## Skill Loading Priority
|
||||
|
||||
|
||||
53
docs/en/skills/install.mdx
Normal file
53
docs/en/skills/install.mdx
Normal file
@@ -0,0 +1,53 @@
|
||||
---
|
||||
title: Install Skills
|
||||
description: Install skills from multiple sources with a single command
|
||||
---
|
||||
|
||||
CowAgent supports installing skills from **Cow Skill Hub, GitHub, ClawHub**, and any URL with a unified `install` command. Use `/skill install` in chat or `cow skill install` in the terminal.
|
||||
|
||||
## From Skill Hub
|
||||
|
||||
Browse the Skill Hub and install:
|
||||
|
||||
```text
|
||||
/skill list --remote
|
||||
/skill install pptx
|
||||
```
|
||||
|
||||
## From GitHub
|
||||
|
||||
Supports batch install from repositories and single skill from subdirectories:
|
||||
|
||||
```text
|
||||
/skill install larksuite/cli
|
||||
/skill install https://github.com/larksuite/cli/tree/main/skills/lark-im
|
||||
```
|
||||
|
||||
## From ClawHub
|
||||
|
||||
```text
|
||||
/skill install clawhub:baidu-search
|
||||
```
|
||||
|
||||
## From URL
|
||||
|
||||
Supports zip archives and SKILL.md file links:
|
||||
|
||||
```text
|
||||
/skill install https://cdn.link-ai.tech/skills/pptx.zip
|
||||
/skill install https://example.com/path/to/SKILL.md
|
||||
```
|
||||
|
||||
## Manage Skills
|
||||
|
||||
```text
|
||||
/skill list # View installed skills
|
||||
/skill info pptx # View skill details
|
||||
/skill enable pptx # Enable a skill
|
||||
/skill disable pptx # Disable a skill
|
||||
/skill uninstall pptx # Uninstall a skill
|
||||
```
|
||||
|
||||
<Tip>
|
||||
All commands above work in the terminal by replacing `/skill` with `cow skill`. See [Skill Management Commands](/en/commands/skill) for full documentation.
|
||||
</Tip>
|
||||
@@ -1,47 +0,0 @@
|
||||
---
|
||||
title: LinkAI Agent
|
||||
description: Integrate LinkAI platform multi-agent skill
|
||||
---
|
||||
|
||||
Use agents from the [LinkAI](https://link-ai.tech/) platform as Skills for multi-agent decision-making. The Agent intelligently selects based on agent names and descriptions, calling the corresponding application or workflow via `app_code`.
|
||||
|
||||
## Dependencies
|
||||
|
||||
| Dependency | Description |
|
||||
| --- | --- |
|
||||
| `LINKAI_API_KEY` | LinkAI platform API key, created in [Console](https://link-ai.tech/console/interface) |
|
||||
| `curl` | System command (usually pre-installed) |
|
||||
|
||||
Configuration:
|
||||
|
||||
- Configure `LINKAI_API_KEY` via the `env_config` tool
|
||||
- Or set `linkai_api_key` in `config.json`
|
||||
|
||||
## Configure Agents
|
||||
|
||||
Add available agents in `skills/linkai-agent/config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"apps": [
|
||||
{
|
||||
"app_code": "G7z6vKwp",
|
||||
"app_name": "LinkAI Customer Support",
|
||||
"app_description": "Select this assistant only when the user needs help with LinkAI platform questions"
|
||||
},
|
||||
{
|
||||
"app_code": "SFY5x7JR",
|
||||
"app_name": "Content Creator",
|
||||
"app_description": "Use this assistant only when the user needs to create images or videos"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
Once configured, the Agent will automatically select the appropriate LinkAI agent based on the user's question.
|
||||
|
||||
<Frame>
|
||||
<img src="https://cdn.link-ai.tech/doc/20260202234350.png" width="750" />
|
||||
</Frame>
|
||||
@@ -1,31 +0,0 @@
|
||||
---
|
||||
title: Skill Creator
|
||||
description: Create custom skills through conversation
|
||||
---
|
||||
|
||||
Quickly create, install, or update skills through natural language conversation.
|
||||
|
||||
## Dependencies
|
||||
|
||||
No extra dependencies, always available.
|
||||
|
||||
## Usage
|
||||
|
||||
- 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
|
||||
|
||||
<Frame>
|
||||
<img src="https://cdn.link-ai.tech/doc/20260202202247.png" width="800" />
|
||||
</Frame>
|
||||
|
||||
<Tip>
|
||||
See the [Skill Creator documentation](https://github.com/zhayujie/chatgpt-on-wechat/blob/master/skills/skill-creator/SKILL.md) for details.
|
||||
</Tip>
|
||||
@@ -1,31 +0,0 @@
|
||||
---
|
||||
title: Web Fetch
|
||||
description: Fetch web page text content
|
||||
---
|
||||
|
||||
Use curl to fetch web pages and extract readable text content. A lightweight web access method without browser automation.
|
||||
|
||||
## Dependencies
|
||||
|
||||
| Dependency | Description |
|
||||
| --- | --- |
|
||||
| `curl` | System command (usually pre-installed) |
|
||||
|
||||
This skill has `always: true` set, enabled by default as long as the system has the `curl` command.
|
||||
|
||||
## Usage
|
||||
|
||||
Automatically invoked when the Agent needs to fetch content from a URL, no extra configuration needed.
|
||||
|
||||
## Comparison with browser Tool
|
||||
|
||||
| Feature | web-fetch (skill) | browser (tool) |
|
||||
| --- | --- | --- |
|
||||
| Dependencies | curl only | browser-use + playwright |
|
||||
| JS rendering | Not supported | Supported |
|
||||
| Page interaction | Not supported | Supports click, type, etc. |
|
||||
| Best for | Static page text | Dynamic web pages |
|
||||
|
||||
<Tip>
|
||||
For most web content retrieval scenarios, web-fetch is sufficient. Only use the browser tool when you need JS rendering or page interaction.
|
||||
</Tip>
|
||||
Reference in New Issue
Block a user