CoPaw 全平台安装与部署教程（含 Windows/macOS/Linux/Docker）

skypiea

CoPaw（Co Personal Agent Workstation）是阿里云通义实验室基于 AgentScope 框架开发的开源个人 AI 智能体工作站，主打本地 / 云端双部署、多平台原生接入与零代码扩展，可作为你的专属 AI 助理处理文件、执行定时任务、跨平台协作。以下从一键脚本、pip 手动、桌面应用、Docker四种主流方式，提供完整安装、配置与验证流程，覆盖全场景需求。
一、安装前准备
系统与环境要求
Windows：Windows 10/11 64 位，PowerShell 5.1 及以上，建议预留 4GB 以上内存copaw.agentscope.io。
macOS：macOS 10.15 及以上，支持 Intel 与 Apple Silicon 芯片。
Linux：主流发行版（Ubuntu、CentOS、Debian 等），x86_64/ARM 架构兼容。
Python 环境：pip 安装需 Python 3.10–3.14，一键脚本会自动配置 Python 与 uv 环境。
网络与权限
确保网络可访问 GitHub、官方镜像源，Windows 安装需以管理员身份运行终端copaw.agentscope.io。
本地部署无需云端账号，云端部署可对接通义千问、Ollama 等模型。
二、一键脚本安装（推荐，零配置）
一键脚本自动处理 Python 环境、依赖安装与 PATH 配置，适合新手快速上手copaw.agentscope.io。
1. Windows 系统（CMD/PowerShell）
CMD 命令：
cmd
curl -fsSL https://copaw.agentscope.io/install.bat -o install.bat && install.bat
PowerShell 命令（推荐，管理员身份运行）：
powershell
irm https://copaw.agentscope.io/install.ps1 | iex
安装完成后，重启终端或执行source $PROFILE加载环境变量，输入copaw --version验证，输出版本号即成功copaw.agentscope.io。
企业版 LTSC 特殊处理：若脚本无法写入 PATH，手动将安装目录（默认C:\Users\用户名\.copaw\bin）添加到系统环境变量 Pathcopaw.agentscope.io。
2. macOS/Linux 系统
bash
运行
curl -fsSL https://copaw.agentscope.io/install.sh | bash
# 加载环境变量
source ~/.zshrc  # zsh终端
source ~/.bashrc  # bash终端
# 验证安装
copaw --version
三、pip 手动安装（适合开发者，灵活可控）
1. 配置 Python 环境
下载 Python 3.10–3.14 安装包，安装时勾选Add Python to PATH。
验证：终端输入python --version，显示对应版本即成功。
创建虚拟环境（避免依赖冲突，推荐）：
bash
运行
# Windows
python -m venv copaw-env
copaw-env\Scripts\activate
# macOS/Linux
python3 -m venv copaw-env
source copaw-env/bin/activate
2. 安装 CoPaw
bash
运行
# 基础安装
pip install copaw
# 国内镜像加速（解决下载慢）
pip install copaw -i https://mirrors.aliyun.com/pypi/simple/
# 验证
copaw --version
3. 初始化配置
bash
运行
# 生成默认配置（生成~/.copaw目录，含配置文件与数据目录）
copaw init --defaults
# 查看配置路径
copaw config show
四、桌面应用安装（可视化操作，适合普通用户）
1. Windows 桌面版
下载：从 GitHub Release 页面下载CoPaw-Setup-<版本>.exe安装包。
安装：双击运行，按向导完成，默认安装路径C:\Users\用户名\AppData\Local\CoPaw，自动创建桌面与开始菜单快捷方式。
启动：双击桌面图标，首次启动会自动初始化配置，等待加载完成即可使用。
2. macOS 桌面版
下载：从 GitHub Release 页面下载CoPaw-<版本>-macOS.zip。
解压：双击压缩包，得到CoPaw.app，可拖入/Applications文件夹。
信任应用：macOS 会阻止未公证应用，前往系统设置→隐私与安全性，点击仍要打开，完成信任后启动。
五、Docker 部署（服务器 / 云端首选，隔离性强）
1. 安装 Docker（已安装可跳过）
bash
运行
# Linux一键安装Docker（支持13种发行版）
bash <(wget -qO- https://xuanyuan.cloud/docker.sh)
# 验证
docker -v
2. 拉取镜像并启动
bash
运行
# 拉取指定版本镜像（避免latest标签不可复现）
docker pull agentscope/copaw:v0.0.7
# 启动服务（映射端口8088，挂载数据目录）
docker run -d \
  -p 127.0.0.1:8088:8088 \
  -v copaw-data:/app/working \
  -v copaw-secrets:/app/working.secret \
  --name copaw \
  agentscope/copaw:v0.0.7
# 验证：浏览器访问http://127.0.0.1:8088，进入Web控制台
六、基础配置与功能验证
1. 模型配置（核心步骤）
本地模型（Ollama）：安装 Ollama 并拉取模型（如ollama pull qwen:7b），在 CoPaw 配置文件~/.copaw/config.yaml中添加：
yaml
model:
  provider: ollama
  model_name: qwen:7b
  base_url: http://localhost:11434
云端模型（通义千问）：注册通义千问账号获取 API Key，配置：
yaml
model:
  provider: dashscope
  api_key: 你的API Key
  model_name: qwen-turbo
2. 多频道接入（钉钉 / 飞书 / QQ）
以钉钉为例：在钉钉开放平台创建机器人，获取 Webhook 地址，在 CoPaw 配置中添加：
yaml
channels:
  - type: dingtalk
    webhook: 你的钉钉机器人Webhook
    name: 钉钉助理
重启 CoPaw（copaw restart），即可在钉钉中 @CoPaw 下达任务。
3. 功能测试
bash
运行
# 测试对话
copaw chat "你好，介绍一下CoPaw"
# 测试文件处理
copaw file summary "D:/test.docx"  # 生成文档摘要
# 测试定时任务
copaw schedule add "每天9点提醒待办" "9:00"
七、常见问题与解决方案
安装失败 / 命令不存在：检查 PATH 是否配置正确，重启终端；Windows 企业版手动添加安装目录到环境变量copaw.agentscope.io。
模型连接失败：验证 API Key / 本地模型地址是否正确，关闭防火墙 / 代理后重试。
桌面应用无法启动：macOS 信任应用；Windows 检查.NET Framework 是否安装，以管理员身份运行。
Docker 端口冲突：修改-p参数的端口号（如-p 8089:8088）。
八、生产环境优化建议
本地部署：关闭公网端口映射，仅允许内网访问；定期备份~/.copaw数据目录。
云端部署：使用阿里云 ECS+Docker，配置安全组仅开放必要端口；对接云监控实现告警。
性能优化：根据内存调整 JVM / 模型参数，避免内存溢出；定期清理日志与缓存。
CoPaw 凭借极简安装、多端适配与隐私可控的特性，成为个人与中小企业搭建专属 AI 助理的优选方案。无论你是新手还是开发者，均可通过以上方式快速部署，解锁 AI 主动协作能力，提升工作与生活效率。