Skip to content

README_zh.md

Latest commit

 

History

History
589 lines (421 loc) · 33.2 KB

README_zh.md

File metadata and controls

589 lines (421 loc) · 33.2 KB

CoPaw

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

[文档] [English] [日本語] [Русский]

CoPaw Logo

懂你所需，伴你左右。

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

核心能力：

由你掌控 — 记忆与个性化完全由你掌控，支持本地或云端部署。无第三方托管，无数据上传。

Skills 扩展 — 内置定时任务、PDF/Office 处理、新闻摘要等；自定义技能自动加载，无绑定。通过 Skills 决定 CoPaw 能做什么。

多智能体协作 — 创建多个独立智能体，各司其职；启用协作技能，智能体间互相通信共同完成复杂任务。

多层安全防护 — 工具防护、文件访问控制、技能安全扫描，保障运行安全。

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

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

新闻

[2026-03-30] 我们发布了 v1.0.0！完整更新说明见 v1.0.0 发布说明。

  • [v1.0.0] 新增：
    • 多 Agent 系统：支持通过 CLI --background 标志执行后台任务并追踪；通过控制台和 API 启用/禁用 Agent；统一优先级队列系统（含 /stop 命令用于任务取消）
    • 模型供应商：CoPaw 本地模型供应商（基于 llama.cpp）；全局 LLM 流控器（QPM 滑动窗口）
    • 安全：工具守卫规则（保护系统重启与服务控制）；技能扫描器中的中文提示词注入检测
    • 控制台与界面：下载页面（提供桌面安装包及镜像站点）；控制台聊天中的多模态预览（图片、音频、视频、文件）
    • 频道：微信 iLink Bot 频道；自定义频道 HTTP 路由（用于 Webhook）
    • 工具与技能：异步工具执行（含后台任务辅助工具）；双层技能池架构；浏览器 CDP 支持（Chrome 自动化）
  • [v1.0.0] 变更： 上下文管理 v2.0（包含嵌套配置模型、新增压缩钩子、工具结果压缩和主动记忆搜索）；优化截断逻辑；流式 Grep 搜索。
  • [v1.0.0] 修复： 飞书 WebSocket 重连和多实例消息路由；Discord 重复消息；QQ 语音消息转换；多 Agent 模型配置；跨平台文件编码。
  • [v1.0.0] 文档： 全面更新文档，包括多 Agent、安装与 CLI、模型供应商、项目结构指南、上下文管理、安全、MCP 与工具、技能和魔法命令。
  • [v1.0.0] 贡献者： 感谢新贡献者：@qzcpl、@livehl、@carlos999-hqsama、@bowenliang123、@jinglinpeng。

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

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

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

目录

推荐阅读：

快速开始

方式一：pip 安装

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

pip install copaw
copaw init --defaults
copaw app

然后在浏览器中打开控制台：**http://127.0.0.1:8088/**，配置模型后即可开始对话。 若要在钉钉、飞书、微信等 app 内对话，请参考 频道配置 文档。

Console

方式二：脚本安装

无需手动配置 Python，一行命令自动完成安装。脚本会自动下载 uv（Python 包管理器）、创建虚拟环境、安装 CoPaw 及其依赖（含 Node.js 和前端资源）。注意：部分网络环境或企业权限管控下可能无法使用。

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 + local）：

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

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

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

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

Windows（PowerShell）：

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

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

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

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

注意：如需安装本地模型支持（llama.cpp、Ollama、LM Studio），请参考 本地模型 章节。

方式三：使用 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 \
  -v copaw-secrets:/app/working.secret \
  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 保存在 copaw-secrets 卷中。如需传入 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 \
  -v copaw-secrets:/app/working.secret \
  agentscope/copaw:latest

然后在 CoPaw 设置 → 模型 中，将 Base URL 改为 http://host.docker.internal:<端口> — 例如 Ollama 填 http://host.docker.internal:11434，LM Studio 填 http://host.docker.internal:1234/v1。

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

docker run --network=host \
  -v copaw-data:/app/working \
  -v copaw-secrets:/app/working.secret \
  agentscope/copaw:latest

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

提示： 如果你只挂载了 /app/working 而没有单独挂载 /app/working.secret，入口脚本会自动将 secrets 重定向到 /app/working/.secret，使其也保存在同一个 volume 中。

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

方式四：部署到阿里云 ECS

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

方式五：使用魔搭创空间

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

方式六：桌面应用（Beta）

Beta 版本说明：桌面应用目前处于 Beta 测试阶段，存在以下已知限制：

  • 兼容性测试不完整：未在所有系统版本和硬件配置上进行充分测试
  • 性能可能存在缺陷：启动速度、内存占用等方面可能需要进一步优化
  • 功能持续完善中：部分功能可能不稳定或缺失

如果你不习惯使用命令行，可以下载并使用 CoPaw 的桌面应用版本，无需手动配置 Python 环境或执行命令。

下载

从 GitHub Releases 下载桌面应用：

  • Windows: CoPaw-Setup-<version>.exe
  • macOS: CoPaw-<version>-macOS.zip (推荐 Apple Silicon)

特点

  • ✅ 零配置：下载后双击即可运行，无需安装 Python 或配置环境变量
  • ✅ 跨平台：支持 Windows 10+ 和 macOS 14+
  • ✅ 可视化：自动打开浏览器界面，无需手动输入地址
  • ⚠️ Beta 阶段：功能持续完善中，欢迎反馈问题

首次启动

重要提示：首次启动可能需要 10-60 秒（取决于您的系统配置）。应用需要初始化 Python 环境和加载依赖，请耐心等待浏览器窗口自动打开。

macOS：绕过系统安全限制

当你从 Releases 下载 CoPaw macOS 应用时，macOS 可能显示："Apple 无法验证 'CoPaw' 不包含恶意软件"。这是因为应用未经过公证。你仍然可以通过以下方式打开：

  • 右键打开（推荐） 右键点击（或 Control + 点击）CoPaw 应用 → "打开" → 在对话框中再次点击 "打开"。这会告诉 Gatekeeper 你信任该应用；之后可以像往常一样双击启动。

  • 在系统设置中允许 如果仍被阻止，进入 系统设置 → 隐私与安全性，向下滚动找到类似 "已阻止 'CoPaw'，因为无法验证开发者" 的提示，点击 "仍要打开" 或 "允许"。

  • 移除隔离属性（不推荐大多数用户） 在终端运行： xattr -cr /Applications/CoPaw.app （或使用解压后的 .app 路径）。这会清除"从互联网下载"的隔离标志，使警告通常不会出现，但不如使用 右键 → 打开 安全和可控。

详细使用说明、故障排除和常见问题，请参见 桌面应用指南。

使用魔搭创空间

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

使用 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 \
  -v copaw-secrets:/app/working.secret \
  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 保存在 copaw-secrets 卷中。如需传入 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 \
  -v copaw-secrets:/app/working.secret \
  agentscope/copaw:latest

然后在 CoPaw 设置 → 模型 中，将 Base URL 改为 http://host.docker.internal:<端口> — 例如 Ollama 填 http://host.docker.internal:11434，LM Studio 填 http://host.docker.internal:1234/v1。

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

docker run --network=host \
  -v copaw-data:/app/working \
  -v copaw-secrets:/app/working.secret \
  agentscope/copaw:latest

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

提示： 如果你只挂载了 /app/working 而没有单独挂载 /app/working.secret，入口脚本会自动将 secrets 重定向到 /app/working/.secret，使其也保存在同一个 volume 中。

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

部署到阿里云 ECS

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

API Key

若使用云端大模型 API（如通义千问、Gemini、OpenAI），在开始对话前必须配置 API Key。未配置有效 Key 前，CoPaw 无法正常工作。详情请参考官方文档。

配置方式：

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

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

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

本地模型

CoPaw 可在本机完全本地运行大模型，无需 API Key 或云端服务。详情请见官方文档

后端 适用场景 安装
llama.cpp 跨平台（macOS / Linux / Windows） 无需额外安装，在 Web 界面中点击 Download Llama.cpp 即可
Ollama 跨平台（需要 Ollama 服务运行） 提前安装 Ollama 应用并启动
LM Studio 跨平台（需要 LM Studio 服务运行） 提前安装 LM Studio 应用并启动

文档

主题 说明
项目介绍 CoPaw 是什么、怎么用
快速开始 安装与运行（本地或魔搭创空间）
控制台 Web 界面：对话、配置与定时任务
模型 配置云/本地/自定义提供商
频道配置 钉钉、飞书、微信、Discord、Telegram 等
Skills 扩展与自定义能力
MCP和工具 管理 MCP 客户端和工具
记忆 长期记忆机制
上下文 上下文管理机制
魔法命令 控制对话状态，无需等待 AI 理解
安全 工具防护、文件防护、技能安全扫描
心跳 定时自检与摘要
多智能体 创建多个智能体并启用协作
配置与工作目录 工作目录与配置文件
CLI 初始化、定时任务、Skills、清理
FAQ 常见问题与报错排查

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

安全特性

CoPaw 内置多层安全防护机制，保障你的数据与系统安全：

  • 工具防护 — 自动拦截危险 Shell 命令（如 rm -rf /、fork 炸弹、反向 shell 等）
  • 文件访问守卫 — 限制智能体访问敏感路径（如 ~/.ssh、密钥文件、系统目录等）
  • 技能安全扫描 — 安装技能前自动扫描，检测提示词注入、命令注入、硬编码密钥、数据外泄等风险
  • 本地部署 — 所有数据与记忆存储在本地，无第三方上传（使用云端 LLM API 时，对话内容会发送到对应的 API 提供商）

详见 安全文档。

常见问题

更多常见问题、故障排查技巧和已知问题，请访问 FAQ 页面。

掌握最新动态

Star CoPaw

在 GitHub 上 Star CoPaw，第一时间收到新版本发布通知。

路线图

方向 事项 状态
横向拓展 更多频道、模型、技能、MCP 等 — 欢迎社区贡献 征集中
已有功能扩展与完善 展示优化、下载提示、Windows 路径兼容等 — 欢迎社区贡献 征集中
控制台 Web UI 在控制台中透出更多信息与配置 进行中
多智能体 Agentic Ralph Loop 进行中
多模态 语音/视频通话与实时交互 进行中
大小模型协同 多模型路由，不同任务使用不同模型 进行中
记忆系统 经验沉淀与技能提炼 进行中
记忆机制切换 进行中
多模态记忆融合 计划中
场景感知主动推送 计划中
沙箱 与 AgentScope Runtime 沙箱深度集成 进行中
云原生 与 AgentScope Runtime 深度集成；利用云端算力、存储、工具与技能 进行中
技能生态 丰富 AgentScope Skills 仓库，提升优质技能的发现与使用 计划中

状态说明：进行中 — 正在积极开发；计划中 — 已排队或设计中，也欢迎贡献；征集中 — 我们强烈鼓励社区参与。

从源码安装

git clone https://github.com/agentscope-ai/CoPaw.git
cd CoPaw

# 先构建前端控制台（Web 界面必需）
cd console && npm ci && npm run build
cd ..

# 将控制台构建产物复制到包目录
mkdir -p src/copaw/console
cp -R console/dist/. src/copaw/console/

# 安装 Python 包
pip install -e .
  • 开发（测试、格式化）：pip install -e ".[dev,full]"
  • 然后：运行 copaw init --defaults，再运行 copaw app。

版本更新提示： 当执行 git pull 更新到大版本后，请重新构建前端、重新安装 Python 包（pip install -e .）、重启 copaw app，并清除浏览器缓存（Ctrl+Shift+R 或 macOS 上 Cmd+Shift+R）。

参与贡献

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

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

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

为什么叫 CoPaw？

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

由谁构建

AgentScope 团队 · AgentScope · AgentScope Runtime · ReMe

联系我们

Discord X (Twitter) 钉钉 小红书
Discord X 钉钉 小红书

遥测数据

CoPaw 在执行 copaw init 时会收集匿名使用数据，帮助我们了解用户环境并优化产品。数据每个版本收集一次 — 当你升级 CoPaw 后，会重新收集以便我们了解版本分布。

收集的信息：

  • CoPaw 版本（如 0.0.7）
  • 安装方式（pip、Docker 或桌面应用）
  • 操作系统及版本（如 macOS 14.0、Ubuntu 22.04）
  • Python 版本（如 3.13）
  • CPU 架构（如 x86_64、arm64）
  • GPU 是否可用（是/否）

不收集： 不涉及任何个人数据、文件、密钥、IP 地址或可识别信息。

交互式运行 copaw init 时，会询问你是否同意。使用 --defaults 模式则自动同意。提示每个版本仅出现一次，且不影响 CoPaw 的任何功能。

许可证

CoPaw 采用 Apache License 2.0 开源协议。

贡献者

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

贡献者