CoPaw Windows 安装及应用指南
1. 什么是 CoPaw？
CoPaw 是阿里云通义实验室推出的个人 AI 智能体，可以在电脑上帮你处理各种任务（如信息整理、定时提醒、文件处理等），并支持接入钉钉、飞书、QQ 等聊天软件，实现 24 小时在线办公助手。
2. 系统要求
- 操作系统：Windows 10 或 Windows 11（64 位）
- Python：3.9 或更高版本（推荐 3.10）
- 内存：建议 4GB 以上（运行时占用约 200~500MB）
- 磁盘空间：至少 500MB 可用空间
- 网络：需要能够访问外网（用于调用大模型 API）
3. 安装步骤
3.1 安装 Python
- 访问 Python 官网 下载 Windows 安装包（如 Python 3.10 或 3.11）。
- 运行安装程序，务必勾选'Add Python to PATH'，然后选择'Install Now'。
- 在命令行输入
python --version，如果显示版本号，说明安装成功。
3.2 创建虚拟环境（推荐）
为了避免与其他 Python 项目冲突，建议为 CoPaw 创建一个虚拟环境：
# 创建一个名为 copaw-env 的虚拟环境
python -m venv copaw-env
# 激活虚拟环境
copaw-env\Scripts\activate
激活后，命令行前面会出现 (copaw-env) 提示符。
3.3 使用 pip 安装 CoPaw
在虚拟环境中执行：
pip install copaw
如果下载速度慢，可以使用国内镜像源加速：
pip install copaw -i https://mirrors.aliyun.com/pypi/simple/
4. 初始化配置
安装完成后，运行以下命令生成默认配置文件：
copaw init --defaults
这会在当前用户目录下创建一个 .copaw 文件夹（Windows 路径通常为 C:\Users\你的用户名\.copaw），里面包含了工作区、配置文件和示例技能。
5. 启动服务
在虚拟环境中执行：
copaw app
启动成功后，你会看到类似如下的输出：
INFO: Started server process [12345]
INFO: Waiting for application startup.
INFO: Application startup complete.
INFO: Uvicorn running on http://127.0.0.1:8088 (Press CTRL+C to quit)
此时 CoPaw 的 Web 控制台已经运行在本地 8088 端口。
6. 访问 Web 控制台
打开浏览器，访问 http://127.0.0.1:8088，你将看到 CoPaw 的对话界面。
7. 配置大模型 API（必须步骤）
CoPaw 本身没有'大脑'，需要接入外部的大模型 API 才能理解和回复。目前支持多种 API 提供商：
7.1 进入模型配置页面
在 Web 控制台左侧菜单栏点击 'Models' 或 '模型'。
7.2 添加模型
点击 'Add Model'，选择你需要的提供商：
- ModelScope（魔搭）：注册后可能获得免费额度。
- DashScope（阿里云）：阿里云的模型服务，需开通并获取 API Key。
- Custom（自定义）：支持兼容 OpenAI 格式的 API，如硅基流动、DeepSeek 等。
7.3 填写 API Key
以 DashScope（阿里云） 为例：
- 访问 阿里云 DashScope 控制台 注册/登录。
- 在'API-KEY 管理'中创建一个新的 API Key，并复制。
- 在 CoPaw 配置页面中粘贴 API Key，选择模型（如
qwen-max、qwen-plus等），点击保存。
注意：API 调用会产生费用（通常很低），请留意阿里云的计费说明。
8. 设置人设（PROFILE.md）
人设文件 PROFILE.md 位于工作区目录（默认为 C:\Users\你的用户名\.copaw\PROFILE.md）。你可以用文本编辑器（如记事本、VS Code）打开它，用自然语言定义 CoPaw 的身份、性格和习惯。例如：
# CoPaw 的人设
你是我的私人 AI 助手，名字叫'小虾米'。你性格活泼，喜欢用表情符号，称呼我为'老板'。你擅长整理信息、设置提醒，并且总是主动提供帮助。
保存文件后，重启 copaw app 或刷新控制台即可生效。
9. 基础应用
9.1 直接对话
在 Web 控制台的输入框中输入消息，CoPaw 会调用配置好的模型进行回复，并执行内置的 Skills（如查新闻、读文件等）。
9.2 创建定时任务
你可以直接对 CoPaw 说：'每天早上 9 点提醒我带工牌' 或 '每天下午 5 点帮我总结今日热点'。CoPaw 会自动在后台创建定时任务，并在指定时间触发。
9.3 查看和管理任务
在控制台左侧菜单栏点击 'Tasks' 或 '任务'，可以查看所有已创建的定时任务，并支持编辑或删除。
10. 进阶玩法
10.1 接入聊天软件
CoPaw 支持接入钉钉、飞书、QQ、iMessage 等平台，让你在常用 App 里直接使用它。具体配置方法请参考官方文档（http://copaw.agentscope.io/），通常需要获取机器人的 Webhook 地址并在 CoPaw 中设置。
10.2 扩展自定义 Skills
如果你熟悉 Python，可以在工作区的 skills 文件夹（C:\Users\你的用户名\.copaw\skills\）下添加自己的脚本。CoPaw 会自动加载这些技能，你可以在对话中调用它们。例如，创建一个 weather.py 实现天气查询，然后对 CoPaw 说'调用 weather 查询北京天气'即可。
11. Windows 常见问题
Q1：运行 copaw 命令提示'不是内部或外部命令'
原因：Python Scripts 目录未添加到 PATH。
解决：重新运行 Python 安装程序，选择'Modify'，勾选'Add Python to environment variables'。或者手动将 C:\Users\你的用户名\AppData\Local\Programs\Python\Python310\Scripts 添加到系统环境变量 PATH 中。
Q2：启动 copaw app 后无法访问 http://127.0.0.1:8088/
原因：可能是防火墙阻止了端口，或者端口被其他程序占用。 解决：
- 检查防火墙设置，允许 Python 或
copaw通过。 - 更换端口：启动时指定其他端口，如
copaw app --port 8089。 - 确保服务启动成功（命令行未报错）。
Q3：虚拟环境激活失败
原因：PowerShell 执行策略限制。
解决：以管理员身份打开 PowerShell，执行 Set-ExecutionPolicy RemoteSigned，然后重新激活。
Q4：模型 API 调用失败
原因：API Key 错误、网络问题或模型名称填写错误。 解决：
- 确认 API Key 有效且余额充足。
- 检查网络是否能够访问 API 服务（可能需要科学上网）。
- 在 CoPaw 模型配置中确认模型名称是否正确（如
qwen-max等）。
12. 获取帮助
- 官方文档：http://copaw.agentscope.io/
- GitHub 仓库：https://github.com/agentscope-ai/CoPaw（可提 Issue）
- 魔搭社区：https://modelscope.cn/studios/fork?target=AgentScope/CoPaw（在线体验与交流）
