Skip to content

README_zh.md

Latest commit

 

History

History
420 lines (305 loc) · 23.8 KB

README_zh.md

File metadata and controls

420 lines (305 loc) · 23.8 KB

CoPaw

GitHub 仓库 PyPI 文档 Python 版本 最后提交 许可证 代码风格 GitHub Star GitHub Fork DeepWiki Discord 钉钉群

[文档] [English] [日本語]

CoPaw Logo

懂你所需，伴你左右。

你的AI个人助理；安装极简、本地与云上均可部署；支持多端接入、能力轻松扩展。

核心能力：

全域触达 — 钉钉、飞书、QQ、Discord、iMessage 等频道，一个 CoPaw 按需连接。

由你掌控 — 记忆与个性化由你掌控，本地或云端均可；定时与协作发往指定频道。

Skills 扩展 — 内置定时任务，自定义技能目录，CoPaw 自动加载，无绑定。

你可以用 CoPaw 做什么
  • 社交媒体：每日热帖摘要（小红书、知乎、Reddit），B 站/YouTube 新视频摘要。
  • 生产力：邮件与 Newsletter 精华推送到钉钉/飞书/QQ，邮件与日历整理联系人。
  • 创意与构建：睡前说明目标、自动执行，次日获得雏形；从选题到成片全流程。
  • 研究与学习：追踪科技与 AI 资讯，个人知识库检索复用。
  • 桌面与文件：整理与搜索本地文件、阅读与摘要文档，在会话中索要文件。
  • 探索更多：用 Skills 与定时任务组合成你自己的 agentic app。

新闻

[2026-03-06] 我们发布了 v0.0.5！完整更新说明见 v0.0.5 发布说明。

[2026-03-02] 我们发布了 v0.0.4！完整更新说明见 v0.0.4 发布说明。

  • [v0.0.4] FEAT： Telegram 频道；OpenAI 与 Azure OpenAI 作为内置模型提供商；Ollama SDK；coding-plan 提供商；模型连接测试；心跳监控面板；CORS 配置；钉钉与飞书支持音频文件。
  • [v0.0.4] FEAT： 基于 token 的记忆压缩；文件块处理；嵌入配置；tool_choice 行为统一。
  • [v0.0.4] BUGFIX： Windows 路径；空 tool call 处理；控制台工作区 UI；Ollama URL 与连通性；MCP 传输；浏览器资源占用；静态资源 MIME 类型；API 请求头；Playwright Docker；心跳解析；纯媒体消息排队。
  • [v0.0.4] RELS： 安装脚本（含 PowerShell）；Docker 指南；频道 CLI 文档；飞书 SOCKS 代理；MCP 与运行时文档；FAQ（中/英）；Skill 编写指南；CONTRIBUTING；控制台文档；网站优化。
  • [v0.0.4] COMM： 感谢新贡献者：@ekzhu、@fancyboi999、@zhaozhuang521、@hobostay、@dhbxs、@longway-code、@ydlstartx、@LudovicoYIN、@fenixc9、@dittotang、@forestxieCode、@yongtenglei、@kerwin612、@luixiao0、@gongpx20069。

目录

推荐阅读：

快速开始

pip 安装 (推荐)

如果你习惯自行管理 Python 环境：

pip install copaw
copaw init --defaults
copaw app

在浏览器打开 http://127.0.0.1:8088/ 即可使用控制台（与 CoPaw 对话、配置 Agent）。若要在钉钉、飞书、QQ 等 app 内对话，请在 文档 中接入频道。

Console

一键安装（beta，持续完善中）

无需预装 Python — 安装脚本自动处理一切：

macOS / Linux：

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

如需安装 Ollama 支持：

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

如需安装多个扩展（例如 Ollama + llama.cpp）：

curl -fsSL https://copaw.agentscope.io/install.sh | bash -s -- --extras ollama,llamacpp

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 -m pip install -U uv，然后重新运行安装程序。

⚠️ Windows 企业版 LTSC 用户特别提示

如果您使用的是 Windows LTSC 或受严格安全策略管控的企业环境，PowerShell 可能运行在 受限语言模式 下，可能会遇到以下问题：

  1. 如果你使用的是 CMD（.bat）：脚本执行成功但无法写入Path

    脚本已完成文件安装，由于 受限语言模式 ，脚本无法自动写入环境变量，此时只需手动配置：

    • 找到安装目录：
      • 检查 uv 是否可用：在 CMD 中输入 uv --version ，如果显示版本号，则只需配置 CoPaw 路径；如果提示 'uv' 不是内部或外部命令，也不是可运行的程序或批处理文件。，则需同时配置两者。
      • uv路径（任选其一，取决于安装位置，若uv不可用则填）：通常在%USERPROFILE%\.local\bin、%USERPROFILE%\AppData\Local\uv或 Python 安装目录下的 Scripts 文件夹
      • CoPaw路径：通常在 %USERPROFILE%\.copaw\bin 。
    • 手动添加到系统的 Path 环境变量：
      • 按 Win + R，输入 sysdm.cpl 并回车，打开“系统属性”。
      • 点击 “高级” -> “环境变量”。
      • 在 “系统变量” 中找到并选中 Path，点击 “编辑”。
      • 点击 “新建”，依次填入上述两个目录路径，点击确定保存。

  2. 如果你使用的是 PowerShell（.ps1）：脚本运行中断

由于 受限语言模式 ，脚本可能无法自动下载uv。

  • 手动安装uv：参考 GitHub Release下载并将uv.exe放至%USERPROFILE%\.local\bin或%USERPROFILE%\AppData\Local\uv；或者确保已安装 Python ，然后运行python -m pip install -U uv
  • 配置uv环境变量：将uv所在目录和 %USERPROFILE%\.copaw\bin 添加到系统的 Path 变量中。
  • 重新运行：打开新终端，再次执行安装脚本以完成 CoPaw 安装。
  • 配置CoPaw环境变量：将 %USERPROFILE%\.copaw\bin 添加到系统的 Path 变量中。

安装完成后，请打开新终端并运行：

copaw init --defaults   # 或：copaw init（交互式）
copaw app
安装选项

macOS / Linux：

# 安装指定版本
curl -fsSL ... | bash -s -- --version 0.0.2

# 从源码安装（开发/测试用）
curl -fsSL ... | bash -s -- --from-source

# 安装本地模型支持
bash install.sh --extras llamacpp    # llama.cpp（跨平台）
bash install.sh --extras mlx         # MLX（Apple Silicon）
bash install.sh --extras llamacpp,mlx

# 升级 — 重新运行安装命令即可
curl -fsSL ... | bash

# 卸载
copaw uninstall          # 保留配置和数据
copaw uninstall --purge  # 删除所有内容

Windows（PowerShell）：

# 安装指定版本
irm ... | iex; .\install.ps1 -Version 0.0.2

# 从源码安装（开发/测试用）
.\install.ps1 -FromSource

# 安装本地模型支持
.\install.ps1 -Extras llamacpp      # llama.cpp（跨平台）
.\install.ps1 -Extras mlx           # MLX
.\install.ps1 -Extras llamacpp,mlx

# 升级 — 重新运行安装命令即可
irm ... | iex

# 卸载
copaw uninstall          # 保留配置和数据
copaw uninstall --purge  # 删除所有内容

使用 Docker

镜像在 Docker Hub（agentscope/copaw）。镜像 tag：latest（稳定版）；pre（PyPI 预发布版）。

docker pull agentscope/copaw:latest
docker run -p 127.0.0.1:8088:8088 -v copaw-data:/app/working agentscope/copaw:latest

国内用户也可选用阿里云容器镜像服务 (ACR)：agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/copaw（tag 相同）。

然后在浏览器打开 http://127.0.0.1:8088/ 进入控制台。配置、记忆与 Skills 保存在 copaw-data 卷中。如需传入 API Key（如 DASHSCOPE_API_KEY），在 docker run 时添加 -e VAR=value 或 --env-file .env。

从容器内连接宿主机上的 Ollama 或其他模型服务

Docker 容器内的 localhost 指向容器自身，而非宿主机。如果 Ollama（或其他模型服务）运行在宿主机上，可通过以下方式让容器内的 CoPaw 访问：

方式 A — 显式绑定宿主机地址（全平台通用）：

docker run -p 127.0.0.1:8088:8088 \
  --add-host=host.docker.internal:host-gateway \
  -v copaw-data:/app/working agentscope/copaw:latest

然后在 CoPaw 设置 → 模型 → Ollama 中，将 Base URL 改为 http://host.docker.internal:11434/v1 或对应端口。

方式 B — 使用宿主机网络（仅限 Linux）：

docker run --network=host -v copaw-data:/app/working agentscope/copaw:latest

无需端口映射（-p），容器直接共享宿主机网络。注意这会将容器的所有端口暴露在宿主机上，可能与已占用的端口产生冲突。

镜像从零构建。若需自行构建镜像，请参阅 scripts/README.md 中的「Build Docker image」小节，构建后推送到你的镜像仓库。

使用魔搭创空间

不想本地安装？ 使用 魔搭创空间 一键云端配置。请将创空间设为 非公开，否则他人可能操纵你的 CoPaw。

部署到阿里云 ECS

若希望将 CoPaw 部署在阿里云上，可使用阿里云 ECS 一键部署：打开 CoPaw 阿里云 ECS 部署链接 按页面提示操作即可。详细步骤见 阿里云开发者社区：CoPaw 3 分钟部署你的 AI 助理。

API Key

若使用云端大模型（如 DashScope、ModelScope），在开始对话前必须配置 API Key。未配置有效 Key 前，CoPaw 无法正常工作。

配置方式：

  1. copaw init — 运行 copaw init 时，会引导你配置 LLM 提供商与 API Key。按提示选择提供商并填写 Key 即可。
  2. 控制台 — 运行 copaw app 后，打开 http://127.0.0.1:8088/ → 设置 → 模型。选择提供商、填写 API Key，并启用该提供商与模型。
  3. 环境变量 — 使用 DashScope 时，可在终端或工作目录下的 .env 文件中设置 DASHSCOPE_API_KEY。

其他工具所需密钥（如网页搜索的 TAVILY_API_KEY）可在控制台 设置 → 环境变量 中配置，详见 配置。

仅用本地模型？ 若使用 本地模型（llama.cpp 或 MLX），则无需任何 API Key。

本地模型

CoPaw 可在本机完全本地运行大模型，无需 API Key 或云端服务。

后端 适用场景 安装
llama.cpp 跨平台（macOS / Linux / Windows） pip install 'copaw[llamacpp]' 或 bash install.sh --extras llamacpp
MLX Apple Silicon（M1/M2/M3/M4） pip install 'copaw[mlx]' 或 bash install.sh --extras mlx
Ollama 跨平台（需要 Ollama 服务运行） pip install 'copaw[ollama]' 或 bash install.sh --extras ollama

安装后下载模型并开始对话：

copaw models download Qwen/Qwen3-4B-GGUF
copaw models # 选择已下载的模型
copaw app # 启动服务

也可在控制台界面中下载与管理本地模型。

文档

主题 说明
项目介绍 CoPaw 是什么、怎么用
快速开始 安装与运行（本地或魔搭创空间）
控制台 Web 界面：对话与 Agent 配置
频道配置 钉钉、飞书、QQ、Discord、iMessage 等
心跳 定时自检与摘要
本地模型 使用 llama.cpp 或 MLX 本地运行模型
CLI 初始化、定时任务、Skills、清理
Skills 扩展与自定义能力
FAQ 常见问题与报错排查
记忆 上下文管理与长期记忆
配置与工作目录 工作目录与配置文件

完整文档见本仓库 website/public/docs/。

常见问题

常见问题、排错指南与已知问题，请访问 FAQ 页面。

路线图

方向 事项 状态
横向拓展 更多频道、模型、Skills、MCP 等 — 欢迎社区贡献 征集中
已有功能扩展与完善 展示优化、下载提示、Windows 路径兼容等 — 欢迎社区贡献 征集中
兼容性与易用性 应用级打包（DMG、EXE） 进行中
一键部署：内置依赖、dev 扩展、安装/升级教程 进行中
版本发布与贡献规范 贡献文档与测试框架 进行中
对社区贡献的积极响应 进行中
Vibe Coding 等 Agent 的贡献引导 计划中
Bug 修复与功能增强 消息折叠/隐藏 计划中
Skills 与 MCP 运行时安装、热加载改进 计划中
上下文管理与压缩（长工具返回、降低 token 消耗） 计划中
多模态支持 进行中
安全 Shell 执行确认 计划中
工具/Skills 安全性 计划中
可配置安全等级 计划中
多模态 语音/视频通话与实时交互 长期规划
多智能体 基于 AgentScope，原生支持多智能体协作 长期规划
沙箱 与 AgentScope Runtime 沙箱深度集成 长期规划
自愈 守护进程 Agent，实现自动恢复与健康监控 长期规划
CoPaw 优化本地模型 针对 CoPaw 原生 Skills 与常见任务调优的本地模型，提升个人助理可用性 长期规划
大小模型协同 本地模型处理敏感数据，云端模型负责规划与编码；兼顾隐私、性能与能力 长期规划
云原生 与 AgentScope Runtime 深度集成，充分利用云端算力、存储与工具生态 长期规划
Skills 生态 丰富 AgentScope Skills 仓库，提升优质 Skill 的发现与使用 长期规划

状态说明：进行中 — 正在推进；计划中 — 已排期或设计中，也欢迎贡献；征集中 — 我们非常欢迎社区参与；长期规划 — 中长期路线。

参与贡献

CoPaw 在开放协作中持续演进，欢迎各种形式的参与！请参考上方 路线图（尤其是标记为 征集中 的项）选择你感兴趣的方向，并阅读 CONTRIBUTING 了解如何开始。我们特别欢迎：

  • 横向拓展 — 新频道、模型提供商、Skills、MCP。
  • 已有功能扩展与完善 — 展示与交互优化、下载提示、Windows 路径兼容等。

欢迎在 GitHub Discussions 参与讨论、提出想法或认领任务。

从源码安装

git clone https://github.com/agentscope-ai/CoPaw.git
cd CoPaw
pip install -e .
  • 开发（测试、格式化）：pip install -e ".[dev]"
  • 控制台（构建前端）：在项目根目录执行 cd console && npm ci && npm run build，再运行 copaw app。

为什么叫 CoPaw？

CoPaw 既是「你的搭档小爪子」（co-paw），也寓意 Co Personal Agent Workstation（协同个人智能体工作台）。我们希望它不是冰冷的工具，而是一只随时准备帮忙的温暖「小爪子」，是你数字生活中最默契的伙伴。

由谁构建

AgentScope 团队 · AgentScope · AgentScope Runtime · ReMe

联系我们

Discord 钉钉
Discord 钉钉

许可证

CoPaw 采用 Apache License 2.0 开源协议。

贡献者

感谢所有为 CoPaw 做出贡献的朋友们：

贡献者