一、安装方式

方式一：一键安装（推荐）

无需预装 Python，安装脚本通过 uv 自动管理所有依赖，不同系统操作如下：

系统	基础安装命令	说明
macOS / Linux	`curl -fsSL https://copaw.agentscope.io/install.sh	bash`
Windows (PS)	`irm https://copaw.agentscope.io/install.ps1	iex`

可选安装参数（进阶）

需求场景	macOS / Linux 命令示例	Windows (PS) 命令示例
安装指定版本	`curl -fsSL https://copaw.agentscope.io/install.sh	bash -s – --version 0.0.2`
从源码安装（开发）	`curl -fsSL https://copaw.agentscope.io/install.sh	bash -s – --from-source`
安装本地模型支持	bash install.sh --extras llamacpp（跨平台） bash install.sh --extras mlx（Apple Silicon）	.\install.ps1 -Extras llamacpp（跨平台） .\install.ps1 -Extras mlx

版本管理

• 升级：重新运行对应系统的基础安装命令即可；
• 卸载：执行 copaw uninstall。

方式二：pip 安装（自定义 Python 环境）

适合习惯自行管理 Python 环境的用户，前提条件：Python 版本需满足 >= 3.10 且 < 3.14。

步骤

1. （可选，推荐）创建并激活虚拟环境：

   # 创建虚拟环境
   python -m venv .venv
   # 激活环境（macOS/Linux）
   source .venv/bin/activate
   # 激活环境（Windows PowerShell）
   .venv\Scripts\Activate.ps1
   

2. 安装 CoPaw：

   pip install copaw
   

3. 验证：安装完成后终端会新增 copaw 命令，可直接调用。

二、初始化配置

安装完成后，需初始化生成配置文件（默认路径 ~/.copaw，包含 config.json 和 HEARTBEAT.md），提供两种初始化方式：

初始化方式	命令	适用场景
快速默认配置	copaw init --defaults	无交互流程，快速生成默认配置，适合先启动再修改
交互式配置	copaw init	按提示填写心跳间隔、投递目标、活跃时段，可同步配置频道与 Skills

注意事项

• 若需覆盖已有配置：执行 copaw init --force（会弹出确认提示，确认后覆盖）；
• 初始化后若未配置频道（钉钉/飞书/QQ 等）：需后续在「频道配置」文档中按指引补充配置。

三、启动服务

完成初始化后，执行以下命令启动 CoPaw 服务：

copaw app

• 默认监听地址：127.0.0.1:8088；
• 功能说明：若已配置频道，CoPaw 会在对应应用内回复消息；若未配置频道，可先启动服务，再补充频道配置。

四、添加模型

五、整合飞书

步骤 1：飞书开放平台配置

1. 创建应用：登录飞书开放平台 → 开发者后台 → 创建「企业自建应用」（如 Bot_Mars）。
   

2. 添加能力：应用详情页 → 添加应用能力 → 选择「机器人」。
   

3. 获取凭证：

   • 凭证与基础信息：记录 App ID、App Secret；
   • 事件与回调：记录 Verification Token。
     

4. 开通权限：权限管理页，按需开通「应用身份权限」「用户身份权限」（详见文末权限清单）。

权限类型	具体权限（示例）
应用身份权限	接收单聊消息（im:message.p2p_msg:readonly）、接收群聊消息（im:message.group_at_msg:readonly）、以应用身份发消息（im:message:send_as_bot）、获取消息记录（im:message.p2p_msg:readonly/im:message.group_msg:readonly）
用户身份权限	获取用户基本信息（contact:user.base:readonly）、获取用户 ID（contact:user.employee_id:readonly）

6. 发布版本：版本管理与发布 → 创建并发布版本（仅发布后可配置事件回调）。
   

步骤 2：copaw通道配置

步骤 5：飞书事件订阅配置

回到飞书开放平台「事件与回调」页面：

1. 事件配置：
   • 订阅方式：选择「长连接」；
   • 添加事件：搜索并订阅 im.message.receive_v1（接收消息 v2.0）。
2. 回调配置：订阅方式选择「长连接」。