CoPaw 安装与使用完全指南

CoPaw 是阿里开源的桌面级 AI Agent 工具...

CoPaw 是阿里开源的桌面级 AI Agent 工具，由 AgentScope 团队打造。它既能当你的「搭档小爪子」，也是一个协同个人智能体工作台。支持钉钉、飞书、QQ、Discord 等多平台接入，数据全在本地。

⚠️ 前置提醒：安装完成后，先在控制台（浏览器访问 http://127.0.0.1:8088/）配置模型，再去配置频道。

一、安装

CoPaw 提供六种安装方式，本文重点讲最常用的两种：脚本安装和 pip 安装。另有桌面应用（适合不想敲命令的用户）、Docker、魔搭创空间、阿里云 ECS 等方式可选。

方式一：脚本安装（推荐）

脚本安装无需手动配置 Python 环境，一条命令自动搞定。

macOS / Linux：

curl -fsSL https://copaw.agentscope.io/install.sh | bash

安装完成后，打开新终端（或执行 source ~/.zshrc / source ~/.bashrc）。

Windows（CMD）：

curl -fsSL https://copaw.agentscope.io/install.bat -o install.bat && install.bat

Windows（PowerShell）：

irm https://copaw.agentscope.io/install.ps1 | iex

💡 提示：安装脚本通过 uv 自动管理 Python 环境。升级只需重新运行安装命令；卸载运行 copaw uninstall。

方式二：pip 安装

适合自行管理 Python 环境的用户（需 Python >= 3.10, < 3.14）：

pip install copaw

建议先创建虚拟环境：

python -m venv .venv
# Linux/macOS
source .venv/bin/activate
# Windows
.venv\Scripts\Activate.ps1

可选——本地模型支持

如果想用本地模型，额外安装对应后端：

pip install 'copaw[llamacpp]'   # llama.cpp（跨平台）
pip install 'copaw[mlx]'        # MLX（Apple Silicon）
pip install 'copaw[ollama]'     # Ollama

二、初始化

安装完成后，需要在工作目录（默认 ~/.copaw）生成配置文件。有两种方式：

# 快速默认配置（不交互）
copaw init --defaults

# 交互式初始化
copaw init

按提示填写心跳间隔、投递目标、活跃时段，可顺带配置频道与 Skills。

📌 注意：初始化后若尚未启用频道，接入钉钉、飞书、QQ 等需在频道配置中按文档填写。

三、启动服务

copaw app

服务默认监听 127.0.0.1:8088。启动成功后，浏览器访问 http://127.0.0.1:8088/ 即可进入控制台。

四、配置模型

在和 CoPaw 对话前，必须先配置模型。进入 控制台 → 设置 → 模型。

云提供商（推荐先试）

CoPaw 支持 ModelScope、DashScope、OpenAI、Azure OpenAI 等。以 DashScope 为例：

1. 找到 DashScope 卡片，点击「设置」
2. 输入你的 API Key，点击保存
3. 在上方 LLM 配置中，选择「DashScope」提供商和目标模型（如 qwen3.5-plus）
4. 点击保存

本地提供商

无需 API Key，数据不出本机。需先安装后端，然后在控制台下载模型。

Ollama / LM Studio

已安装 Ollama 或 LM Studio 的用户，可在控制台对接本地模型服务。

五、使用方法

控制台对话

服务启动后，直接在浏览器控制台和 CoPaw 对话，可测试各项功能、配置 Agent。

接入频道

想让 CoPaw 在钉钉、飞书、QQ、Discord 等平台回复消息？去 频道配置 按文档操作：

1. 在对应平台创建应用（如钉钉企业自建应用）
2. 获取 App Key、App Secret 等信息
3. 填入 CoPaw 配置文件
4. 保存后重启服务

定时任务与心跳

心跳：按固定间隔用你写好的问题问 CoPaw，可把回答发到上次对话的频道。编辑 HEARTBEAT.md 并在 config 里设间隔和 target。

定时任务：通过 CLI 或 API 管理多条独立配置时间的任务。

六、验证安装（可选）

服务启动后，可用 curl 测试接口：

curl -N -X POST "http://localhost:8088/api/agent/process