Skip to content

README_zh.md

Latest commit

 

History

History
507 lines (364 loc) · 30.4 KB

README_zh.md

File metadata and controls

507 lines (364 loc) · 30.4 KB

CoPaw

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

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

CoPaw Logo

懂你所需，伴你左右。

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

核心能力：

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

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

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

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

新闻

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

  • [v0.1.0] 新增： 多工作区架构，支持 Agent 切换器；技能安全扫描和危险 Shell 命令检测；可选 Web 认证；企业微信和小艺通道；钉钉 AI 卡片回复；Gemini、DeepSeek、MiniMax、Kimi 模型供应商；控制台暗色模式和多模态聊天；基于 SSE 的流式对话（支持重连）；Whisper 语音转文字；view_image 多模态对话工具；LobeHub、魔搭和 Zip 压缩包技能导入；glob_search 和 grep_search 内置搜索工具；时区选择器；copaw update 自升级命令。
  • [v0.1.0] 优化： 优雅的生命周期管理（Agent 零停机重载）；动态 Agent 级 Token 计数；配置加载保护；控制台多语言改进（含聊天提示词本地化）；Windows 桌面端字节码预编译加速启动；QQ 频道回复逻辑优化和私聊支持。
  • [v0.1.0] 修复： Telegram 消息线程、媒体处理和自动重连；Discord 跨频道消息合并和防抖泛化；飞书通道重载；Ollama/LM Studio 上下文长度和错误提示；定时任务工作区修复；聊天会话导航持久化；Windows 跨磁盘文件移动、AutoRun stderr 和 GBK 编码。
  • [v0.1.0] 贡献者： 感谢新贡献者：@dipeshbabu、@sljeff、@octo-patch、@Alexxigang、@howyoungchen、@nphenix、@skyfaker、@hh0592821、@futuremeng、@toby1123yjh、@hiyuchang、@hanson-hex、@JackyMao1999、@mvanhorn、@yuanxs21、@aissac、@lcq225、@Justin-lu、@rowanchen-com、@pzlav、@mautops、@hikariming、@Vanlee0129、@JiwaniZakir、@EuanTop。

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

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

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

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

目录

推荐阅读：

快速开始

pip 安装

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

pip install copaw
copaw init --defaults
copaw app

在浏览器打开 http://127.0.0.1:8088/ 即可使用控制台（与 CoPaw 对话、配置 Agent）。若要在钉钉、飞书、QQ 等 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 + 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  # 删除所有内容

桌面应用（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 路径）。这会清除"从互联网下载"的隔离标志，使警告通常不会出现，但不如使用 右键 → 打开 安全和可控。

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

使用 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」小节，构建后推送到你的镜像仓库。

使用魔搭创空间

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

部署到阿里云 ECS

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

API Key

若使用云端大模型（如 DashScope、ModelScope），在开始对话前必须配置 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 或 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 等
Skills 扩展与自定义能力
MCP 管理 MCP 客户端
记忆 长期记忆
上下文 上下文管理机制
魔法命令 控制对话状态，无需等待AI理解
心跳 定时自检与摘要
配置与工作目录 工作目录与配置文件
CLI 初始化、定时任务、Skills、清理
FAQ 常见问题 常见问题与报错排查

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

常见问题

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

路线图

方向 事项 状态
横向拓展 更多频道、模型、技能、MCP 等 — 欢迎社区贡献 征集中
已有功能扩展与完善 展示优化、下载提示、Windows 路径兼容等 — 欢迎社区贡献 征集中
控制台 Web UI 在控制台中透出更多信息与配置 进行中
自愈 魔法命令与 Daemon 能力（CLI、status、restart、logs） 进行中
DaemonAgent：自诊断、自愈与恢复 计划中
多智能体 后台任务支持 进行中
多智能体隔离 计划中
智能体间竞争与冲突的解决 计划中
多智能体通信 计划中
多模态 语音/视频通话与实时交互 进行中
大小模型协同 针对 CoPaw 工作流与敏感数据场景的本地小模型训练与微调 进行中
多模型路由。本地模型处理敏感数据，云端模型负责规划与编码；兼顾隐私、性能与能力 计划中
记忆系统 经验沉淀技能提炼 进行中
多模态记忆融合增强 计划中
场景感知主动推送 计划中
安全 Shell 执行确认 计划中
工具/技能安全性 计划中
可配置安全等级 计划中
版本发布与贡献规范 Vibe Coding 等 Agent 的贡献引导 计划中
沙箱 与 AgentScope Runtime 沙箱深度集成 长期规划
云原生 与 AgentScope Runtime 深度集成，充分利用云端算力、存储与工具生态 长期规划
技能生态 丰富 AgentScope Skills 仓库，提升优质技能的发现与使用 长期规划

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

参与贡献

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

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

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

从源码安装

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。

为什么叫 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 做出贡献的朋友们：

贡献者