Copaw Ops

CoPaw Ops

本技能用于 CoPaw 的日常巡检、故障定位与恢复操作，优先给出可执行命令和最短恢复路径。

设计模式

本 skill 主要采用：

• Tool Wrapper：提供 CoPaw 命令、诊断路径和参考资料
• Runbook / Pipeline：按"状态检查 → 问题分流 → 选择修复动作 → 验证结果"的顺序执行
• Reviewer（轻度）：先判断问题类型，再决定是否需要恢复动作

Gotchas

• 不要一上来就重启或重置，先看状态和症状
• 涉及重启、reload、init --force、重置、配置修改等高影响动作时，要先向用户说明再执行
• 不要把模型问题、渠道问题、daemon 问题、cron 问题混成一个通用修复命令
• 不要假装 Magic Commands 在所有环境都可用，要先判断当前渠道/环境是否支持
• 修复后一定要回到状态检查，不要停在"命令执行了"
• 多 agent 环境：检查和修复时注意指定正确的 --agent-id（默认：default）

触发场景

• 用户要求排查 CoPaw 服务不可用、响应慢、报错。
• 用户要求查看或修改 CoPaw 配置、模型、渠道、定时任务、会话。
• 用户要求执行 CoPaw 重启、重载、清理、重置。
• 用户要求 Docker / supervisord 场景下的 CoPaw 运维操作。
• 用户要求排查多 agent 环境下的特定 agent 问题。

标准诊断流程

0. 先判断是否需要确认

以下操作默认可以直接做：

• copaw daemon status
• copaw daemon version
• copaw agent list（新增）
• copaw workspace list（新增）
• copaw models list [--agent-id <id>]
• copaw channels list [--agent-id <id>]
• copaw cron list [--agent-id <id>]
• copaw daemon logs -n 100

以下操作属于高影响动作，执行前应先向用户说明：

• copaw daemon reload-config
• /restart
• /daemon restart
• copaw init --force
• copaw workspace delete <id>
• 任何明确会修改配置、重连渠道、重置状态的命令

1. 基础状态检查

当用户报告 CoPaw 故障时，按以下最小闭环执行：

# 1) 基础状态（全局）
copaw daemon status
copaw daemon version

# 2) 多 agent 检查（新增）
copaw agent list              # 列出所有 agent
copaw workspace list          # 列出所有工作区

# 3) 特定 agent 检查（指定 --agent-id）
copaw models list --agent-id <id>
copaw channels list --agent-id <id>
copaw cron list --agent-id <id>

# 4) 最近日志
copaw daemon logs -n 100

# 5) 针对性恢复（按症状）
copaw daemon reload-config

2. 工作区检查（新增）

# 检查工作区结构
ls -la ~/.copaw/workspaces/

# 检查特定 agent 的工作区
ls -la ~/.copaw/workspaces/<agent-id>/

# 检查配置文件
cat ~/.copaw/workspaces/<agent-id>/agent.json

# 检查内置 skills
ls -la ~/.copaw/workspaces/<agent-id>/active_skills/

# 检查向量数据库（如果启用）
ls -la ~/.copaw/workspaces/<agent-id>/file_store/

若在聊天渠道中可直接执行 Magic Commands，则优先：

/status
/restart
/daemon logs 50

故障分流

服务无响应

1. 先 /restart，再 copaw daemon reload-config 2. 检查工作区是否正常：ls -la ~/.copaw/workspaces/ 3. 检查 agent 是否启动：copaw agent list 4. 仍失败再按部署方式重启进程

配置错误

1. copaw daemon reload-config + copaw daemon logs -n 200 2. 检查 agent.json 配置：cat ~/.copaw/workspaces/<id>/agent.json 3. 必要时 copaw init --force

渠道断连

1. copaw channels list --agent-id <id> 检查配置 2. copaw channels config <channel> --agent-id <id> 查看详细配置 3. 针对特定渠道：

• 钉钉：检查 client_id, client_secret, robot_code；使用 dingtalk_channel skill 自动连接
• 飞书：检查 app_id, app_secret, encrypt_key
• QQ：检查 app_id, client_secret

4. /daemon restart 重启服务

模型调用失败

1. copaw models list --agent-id <id> 检查当前模型 2. copaw models config-key <provider> --agent-id <id> 检查 API key 3. copaw models set-llm --agent-id <id> 切换模型

定时任务不执行

1. copaw cron list --agent-id <id> 列出所有任务 2. copaw cron state <job_id> --agent-id <id> 检查任务状态 3. 检查 jobs.json：cat ~/.copaw/workspaces/<id>/jobs.json 4. copaw cron resume <job_id> --agent-id <id> 恢复任务 5. copaw cron run <job_id> --agent-id <id> 手动执行测试

内置 Skills 故障（新增）

1. 检查 skill 是否存在：ls ~/.copaw/workspaces/<id>/active_skills/ 2. 检查依赖项：

• Office skills（docx/pptx/xlsx）：检查 Python 依赖库
• PDF skill：检查 PDF 工具（pdfplumber 等）
• himalaya skill：检查邮件配置
• browser_visible skill：检查浏览器连接

上下文爆满

1. /compact 或 /new 2. 用 /history 验证 Token 使用

钉钉渠道特殊处理（新增）

1. 检查配置：

   copaw channels config dingtalk --agent-id <id>

2. 检查必填字段：

• client_id
• client_secret
• robot_code（可选）

3. 使用自动连接 skill：

   # 需要可视化浏览器
   copaw skills run dingtalk_channel --agent-id <id>

4. 检查机器人是否发布（重要！） 5. 检查 Stream 模式配置

成功判定标准

• copaw daemon status 正常，且无关键报错。
• copaw agent list 显示所有 agent 正常。
• copaw channels list --agent-id <id> 渠道状态符合预期。
• copaw models list --agent-id <id> 当前模型可用。
• copaw cron list --agent-id <id> / copaw cron state <job_id> 显示任务正常。
• 工作区结构完整：agent.json 存在，active_skills/ 存在。
• 最近日志未持续出现相同错误。

按需加载参考

• 常用命令与巡检清单：references/copaw_commands.md
• 故障恢复策略：references/copaw_recovery.md
• 多 agent 架构说明：references/multi_agent.md（新增）
• 内置 skills 说明：references/builtin_skills.md（新增）

回复模板

向用户汇报时使用以下结构：

1. 现象：用户侧症状 + 影响范围 2. 诊断：执行过的命令与关键输出（注明 agent-id） 3. 处理：已执行恢复动作 4. 结果：当前状态是否恢复 5. 建议：后续预防或观察项

多 Agent 环境注意事项

1. 默认 agent：所有命令默认操作 default agent 2. 指定 agent：使用 --agent-id <id> 参数指定 3. 工作区隔离：每个 agent 有独立的工作区、配置、skills 4. 批量操作：暂不支持批量操作所有 agent，需要逐个检查 5. 日志查看：daemon 日志包含所有 agent，需要过滤查看

常见错误

Agent 不存在

Error: Agent 'xxx' not found

解决： 1. 检查 agent 列表：copaw agent list 2. 创建新 agent：copaw workspace create <id>

工作区损坏

Error: Workspace directory not found

解决： 1. 检查工作区：ls -la ~/.copaw/workspaces/ 2. 重新初始化：copaw init --force

内置 Skill 加载失败

Error: Failed to load skill 'xxx'

解决： 1. 检查 skill 目录：ls ~/.copaw/workspaces/<id>/active_skills/ 2. 检查依赖项：pip list 3. 查看详细错误：copaw daemon logs -n 200

CoPaw 内置 Skills

概述

CoPaw 内置了多个 skills，提供常用功能的封装。这些 skills 位于工作区的 active_skills/ 目录下，可以自动加载和使用。

内置 Skills 列表

1. cron - 定时任务管理

用途：通过 copaw cron 命令管理定时任务

功能：

• 创建、查询、暂停、恢复、删除任务
• 支持多 agent（--agent-id 参数）
• 支持 text 和 agent 两种任务类型

常用命令：

copaw cron list --agent-id <id>
copaw cron create --agent-id <id> ...
copaw cron state <job_id> --agent-id <id>
copaw cron resume <job_id> --agent-id <id>
copaw cron run <job_id> --agent-id <id>

故障排查： 1. 检查 jobs.json：cat ~/.copaw/workspaces/<id>/jobs.json 2. 检查任务状态：copaw cron state <job_id> --agent-id <id> 3. 手动执行测试：copaw cron run <job_id> --agent-id <id>

依赖项：无

2. dingtalk_channel - 钉钉自动连接

用途：通过可视化浏览器自动完成钉钉频道接入

功能：

• 自动创建钉钉应用
• 自动配置机器人
• 自动发布机器人
• 自动绑定到 CoPaw channel

使用方式：

# 需要可视化浏览器
copaw skills run dingtalk_channel --agent-id <id>

前置条件： 1. 可视化浏览器模式（headed: true） 2. 钉钉开发者后台账号 3. 图片资源（机器人图标、预览图）

故障排查： 1. 检查配置：copaw channels config dingtalk --agent-id <id> 2. 检查必填字段：client_id, client_secret, robot_code 3. 检查机器人是否发布 4. 检查 Stream 模式配置

依赖项：

• 可视化浏览器（Playwright/Puppeteer）
• 网络连接

3. docx - Word 文档操作

用途：编辑和操作 Word 文档

功能：

• 创建、编辑、读取 Word 文档
• 添加评论、修订
• 验证文档格式

常用脚本：

# 接受所有修订
python scripts/accept_changes.py <input.docx>

# 添加评论
python scripts/comment.py <input.docx>

# 验证文档
python scripts/office/validate.py <input.docx>

故障排查： 1. 检查 Python 依赖：pip list | grep docx 2. 检查文件格式：确保是 .docx 格式 3. 查看详细错误：copaw daemon logs -n 200

依赖项：

• python-docx
• lxml

4. pptx - PowerPoint 文档操作

用途：编辑和操作 PowerPoint 文档

功能：

• 创建、编辑、读取 PPT
• 添加幻灯片
• 生成缩略图
• 清理格式

常用脚本：

# 添加幻灯片
python scripts/add_slide.py <input.pptx>

# 清理格式
python scripts/clean.py <input.pptx>

# 生成缩略图
python scripts/thumbnail.py <input.pptx>

# 验证文档
python scripts/office/validate.py <input.pptx>

故障排查： 1. 检查 Python 依赖：pip list | grep pptx 2. 检查文件格式：确保是 .pptx 格式 3. 查看详细错误：copaw daemon logs -n 200

依赖项：

• python-pptx
• lxml
• Pillow（缩略图功能）

5. xlsx - Excel 文档操作

用途：编辑和操作 Excel 文档

功能：

• 创建、编辑、读取 Excel
• 重新计算公式
• 验证文档格式

常用脚本：

# 重新计算公式
python scripts/recalc.py <input.xlsx>

# 验证文档
python scripts/office/validate.py <input.xlsx>

故障排查： 1. 检查 Python 依赖：pip list | grep openpyxl 2. 检查文件格式：确保是 .xlsx 格式 3. 查看详细错误：copaw daemon logs -n 200

依赖项：

• openpyxl
• lxml

6. pdf - PDF 文档操作

用途：编辑和操作 PDF 文档

功能：

• 创建、编辑、读取 PDF
• 填写表单
• 提取表单字段
• 转换为图片

常用脚本：

# 检查表单字段
python scripts/check_fillable_fields.py <input.pdf>

# 提取表单信息
python scripts/extract_form_field_info.py <input.pdf>

# 填写表单
python scripts/fill_fillable_fields.py <input.pdf>

# 转换为图片
python scripts/convert_pdf_to_images.py <input.pdf>

故障排查： 1. 检查 Python 依赖：pip list | grep pdf 2. 检查 PDF 工具：which pdftotext 3. 查看详细错误：copaw daemon logs -n 200

依赖项：

• pdfplumber
• PyPDF2
• Pillow

7. himalaya - 邮件客户端

用途：管理邮件

功能：

• 发送、接收邮件
• 管理邮件文件夹
• 搜索邮件

配置： 参见 references/configuration.md

故障排查： 1. 检查邮件配置：cat ~/.config/himalaya/config.toml 2. 检查网络连接 3. 检查认证信息

依赖项：

• himalaya CLI

8. browser_visible - 浏览器可视化

用途：控制可视化浏览器

功能：

• 打开、关闭浏览器
• 导航网页
• 截图
• 执行脚本

使用方式：

# 启动可视化浏览器
copaw skills run browser_visible --agent-id <id>

故障排查： 1. 检查浏览器是否安装 2. 检查浏览器驱动（ChromeDriver/GeckoDriver） 3. 检查网络连接

依赖项：

• Playwright 或 Puppeteer
• 浏览器（Chrome/Firefox/Safari）

9. news - 新闻获取

用途：获取新闻信息

功能：

• 获取最新新闻
• 分类新闻
• 搜索新闻

使用方式：

# 获取最新新闻
copaw skills run news --agent-id <id>

故障排查： 1. 检查网络连接 2. 检查新闻源配置 3. 查看详细错误：copaw daemon logs -n 200

依赖项：

• 网络连接
• 新闻源 API（可选）

10. file_reader - 文件读取

用途：读取各种格式的文件

功能：

• 读取文本文件
• 读取二进制文件
• 读取压缩文件

使用方式：

# 读取文件
copaw skills run file_reader --agent-id <id>

故障排查： 1. 检查文件路径 2. 检查文件权限 3. 检查文件格式

依赖项：无

11. guidance - 指导

用途：提供使用指导和帮助

功能：

• 提供命令帮助
• 提供使用指南
• 提供故障排查建议

使用方式：

# 获取指导
copaw skills run guidance --agent-id <id>

故障排查： 1. 检查 skill 是否加载 2. 查看详细错误：copaw daemon logs -n 200

依赖项：无

Skills 故障排查

通用排查流程

1. 检查 skill 是否存在：

   ls ~/.copaw/workspaces/<id>/active_skills/

2. 检查 skill 配置：

   cat ~/.copaw/workspaces/<id>/active_skills/<skill>/SKILL.md

3. 检查依赖项：

   pip list | grep <dependency>

4. 查看详细错误：

   copaw daemon logs -n 200 | grep <skill>

5. 重新加载 skills：

   copaw daemon reload-config

常见错误

Skill 加载失败

错误：

Error: Failed to load skill 'xxx'

解决： 1. 检查 SKILL.md 格式 2. 检查依赖项是否安装 3. 查看详细错误日志

依赖项缺失

错误：

ModuleNotFoundError: No module named 'xxx'

解决：

pip install <module>

权限问题

错误：

PermissionError: [Errno 13] Permission denied

解决：

chmod +x ~/.copaw/workspaces/<id>/active_skills/<skill>/scripts/*.py

网络问题

错误：

ConnectionError: Unable to connect

解决： 1. 检查网络连接 2. 检查代理设置 3. 检查防火墙规则

Skills 管理

列出所有 Skills

# 列出所有内置 skills
copaw skills list --agent-id <id>

# 列出特定 skill 的详细信息
copaw skills config <skill> --agent-id <id>

禁用 Skill

# 移动到临时目录
mv ~/.copaw/workspaces/<id>/active_skills/<skill> ~/.copaw/workspaces/<id>/disabled_skills/

# 重新加载配置
copaw daemon reload-config

启用 Skill

# 移动回 active_skills 目录
mv ~/.copaw/workspaces/<id>/disabled_skills/<skill> ~/.copaw/workspaces/<id>/active_skills/

# 重新加载配置
copaw daemon reload-config

更新 Skill

# 备份旧版本
cp -r ~/.copaw/workspaces/<id>/active_skills/<skill> ~/.copaw/workspaces/<id>/active_skills/<skill>.bak

# 更新代码
cd ~/.copaw/workspaces/<id>/active_skills/<skill>
git pull

# 重新加载配置
copaw daemon reload-config

自定义 Skills

创建自定义 Skill

1. 创建目录：

   mkdir -p ~/.copaw/workspaces/<id>/active_skills/<skill>

2. 创建 SKILL.md：

   ---
   name: <skill>
   description: <skill description>
   ---

   # <Skill Name>

   <skill content>

3. 创建脚本（可选）：

   mkdir -p ~/.copaw/workspaces/<id>/active_skills/<skill>/scripts
   touch ~/.copaw/workspaces/<id>/active_skills/<skill>/scripts/main.py

4. 重新加载配置：

   copaw daemon reload-config

Skill 开发最佳实践

1. 清晰的描述：在 SKILL.md 中提供清晰的描述 2. 完整的文档：包含使用说明和故障排查指南 3. 错误处理：脚本中包含完善的错误处理 4. 依赖管理：明确列出所有依赖项 5. 版本控制：使用 Git 管理代码

参考资料

• CoPaw 命令速查
• 故障恢复策略
• 多 Agent 架构

CoPaw 命令速查

1. 服务启停与状态

copaw app
copaw app --host 0.0.0.0 --port 9090
copaw app --reload
copaw app --workers 4
copaw app --log-level debug

copaw daemon status
copaw daemon version
copaw daemon logs -n 100
copaw daemon reload-config

Magic Commands（聊天中）：

/status
/restart
/daemon reload-config
/daemon logs 50

2. 多 Agent 管理（新增）

# 列出所有 agent
copaw agent list

# 列出所有工作区
copaw workspace list

# 创建新工作区
copaw workspace create <agent-id>

# 删除工作区（高影响操作）
copaw workspace delete <agent-id>

# 检查工作区状态
copaw workspace validate <agent-id>

多 agent 参数说明：

• --agent-id <id>：指定操作的 agent（默认：default）
• 适用于：models、channels、cron、chats、skills 等命令

工作区结构：

~/.copaw/workspaces/<agent-id>/
├── agent.json          # Agent 配置
├── active_skills/      # 内置 skills
├── file_store/         # 向量数据库（可选）
├── chats.json          # 聊天记录
├── jobs.json           # 定时任务
├── AGENTS.md           # Agent 说明
├── MEMORY.md           # 记忆
├── HEARTBEAT.md        # 心跳检查
└── memory/             # 记忆目录

3. 初始化与配置

copaw init
copaw init --defaults
copaw init --force

默认工作目录：~/.copaw/

• config.json - 根配置（多 agent 架构）
• workspaces/ - 工作区目录
• copaw.log - 日志文件

环境变量覆盖：

export COPAW_WORKING_DIR=/custom/path
export COPAW_LOG_LEVEL=debug
export COPAW_MEMORY_COMPACT_THRESHOLD=100000

4. 模型管理

# 默认 agent
copaw models list
copaw models config
copaw models config-key dashscope
copaw models set-llm

# 指定 agent
copaw models list --agent-id <id>
copaw models config --agent-id <id>
copaw models set-llm --agent-id <id>

# 本地模型
copaw models download Qwen/Qwen3-4B-GGUF
copaw models local
copaw models remove-local <model_id> --yes

# Ollama 模型
copaw models ollama-pull qwen3:8b
copaw models ollama-list
copaw models ollama-remove qwen3:8b

5. 渠道管理

# 默认 agent
copaw channels list
copaw channels config
copaw channels add dingtalk
copaw channels remove my_channel

# 指定 agent
copaw channels list --agent-id <id>
copaw channels config dingtalk --agent-id <id>
copaw channels add dingtalk --agent-id <id>

支持渠道：iMessage, Discord, DingTalk, Feishu, QQ, Console, Telegram, Matrix, Mattermost, MQTT

钉钉渠道配置：

copaw channels config dingtalk --agent-id <id>

必填字段：

• client_id
• client_secret
• robot_code（可选）

6. 定时任务管理

# 默认 agent
copaw cron list
copaw cron get <job_id>
copaw cron state <job_id>
copaw cron create ...
copaw cron delete <job_id>
copaw cron pause <job_id>
copaw cron resume <job_id>
copaw cron run <job_id>

# 指定 agent
copaw cron list --agent-id <id>
copaw cron state <job_id> --agent-id <id>
copaw cron create --agent-id <id> ...
copaw cron resume <job_id> --agent-id <id>
copaw cron run <job_id> --agent-id <id>

创建示例：

copaw cron create \
  --agent-id default \
  --type agent \
  --name "每日检查" \
  --cron "0 9 * * *" \
  --channel dingtalk \
  --target-user "user_id" \
  --target-session "session_id" \
  --text "今日待办有哪些？"

7. 会话与技能

# 默认 agent
copaw chats list
copaw chats list --channel dingtalk
copaw chats get <chat_id>
copaw chats delete <chat_id>

copaw skills list
copaw skills config

# 指定 agent
copaw chats list --agent-id <id>
copaw skills list --agent-id <id>

内置 Skills：

• cron - 定时任务管理
• dingtalk_channel - 钉钉自动连接
• docx/pptx/xlsx - Office 文档操作
• pdf - PDF 操作
• himalaya - 邮件客户端
• browser_visible - 浏览器可视化
• news - 新闻
• file_reader - 文件读取
• guidance - 指导

聊天命令：

/compact
/new
/clear
/history
/compact_str

8. 环境变量与清理

copaw env list
copaw env set TAVILY_API_KEY "xxx"
copaw env delete TAVILY_API_KEY

copaw clean
copaw clean --yes
copaw clean --dry-run

9. Docker / Supervisord

docker run -d -p 8088:8088 -v ~/.copaw:/app/working -e COPAW_PORT=8088 copaw:latest
docker exec -it <container_id> bash

supervisorctl status
supervisorctl restart app
supervisorctl tail -f app

日志路径：

• /var/log/supervisord.log
• /var/log/app.out.log
• /var/log/app.err.log
• /app/working/copaw.log

10. 监控巡检清单

# 全局状态
copaw daemon status
copaw daemon version
copaw daemon logs -n 50

# 多 agent 检查
copaw agent list
copaw workspace list

# 特定 agent 检查
copaw models list --agent-id <id>
copaw channels list --agent-id <id>
copaw cron list --agent-id <id>
copaw chats list --agent-id <id>

# 工作区检查
ls -la ~/.copaw/workspaces/<id>/
cat ~/.copaw/workspaces/<id>/agent.json

聊天中补充检查：

/history

11. 常用参数说明

CoPaw 故障恢复手册

1. 服务无响应

优先级从高到低：

/restart

copaw daemon reload-config

按部署方式重启：

sudo systemctl restart copaw
docker restart <container_id>
supervisorctl restart app

2. MCP 客户端连接失败

• 系统会自动重试最多 3 次。
• 重试失败后应跳过故障客户端并继续运行其他功能。
• 修复配置后修改 config.json 触发热重载，或执行 copaw daemon reload-config。

3. 渠道断连

copaw channels list
copaw channels config

聊天中执行：

/daemon restart

4. Token 超限 / 上下文爆满

/compact
/new
/history

5. 配置错误导致启动失败

copaw daemon reload-config
copaw daemon logs -n 200
copaw init --force

6. 模型调用失败

copaw models list
copaw models config-key <provider>
copaw models set-llm

7. 定时任务不执行

copaw cron state <job_id>
copaw cron list
copaw cron resume <job_id>
copaw cron run <job_id>

8. 清理与重置

仅清理记忆：

rm -rf ~/.copaw/memory/ ~/.copaw/MEMORY.md

完全重置：

copaw clean --yes
copaw init

9. 恢复后验证

恢复动作执行后，必须复核：

copaw daemon status
copaw daemon logs -n 100
copaw channels list
copaw models list
copaw cron list

若仍有错误，记录最近日志中的首个关键异常并切换到对应分支策略重试。

CoPaw 多 Agent 架构

概述

CoPaw 从单 agent 架构升级为多 agent 架构（2026-03-18），支持同时运行多个独立的 agent 实例，每个 agent 有独立的工作区、配置、skills 和记忆。

架构说明

工作区结构

~/.copaw/
├── config.json              # 根配置（多 agent 架构）
├── copaw.log                # 全局日志
├── bin/
│   └── copaw                # CLI wrapper 脚本
└── workspaces/
    ├── default/             # 默认 agent 工作区
    │   ├── agent.json       # Agent 配置
    │   ├── active_skills/   # 内置 skills
    │   ├── file_store/      # 向量数据库（可选）
    │   ├── chats.json       # 聊天记录
    │   ├── jobs.json        # 定时任务
    │   ├── AGENTS.md        # Agent 说明
    │   ├── MEMORY.md        # 记忆
    │   ├── HEARTBEAT.md     # 心跳检查
    │   └── memory/          # 记忆目录
    └── <agent-id>/          # 其他 agent 工作区
        └── ...

配置层次

1. 根配置：~/.copaw/config.json

• 定义所有 agent 的共享配置
• 管理多 agent 架构

2. Agent 配置：~/.copaw/workspaces/<agent-id>/agent.json

• 每个 agent 的独立配置
• 渠道、模型、skills 等设置

Agent 管理

列出所有 Agent

copaw agent list

输出示例：

Agent ID    Name              Status    Workspace
default     Default Agent     running   ~/.copaw/workspaces/default
agent-2     Secondary Agent   running   ~/.copaw/workspaces/agent-2

创建新 Agent

# 创建新工作区
copaw workspace create <agent-id>

# 示例
copaw workspace create agent-2

删除 Agent

# 删除工作区（高影响操作）
copaw workspace delete <agent-id>

# 示例
copaw workspace delete agent-2

注意：删除工作区会清除所有数据（聊天记录、定时任务、记忆等），需谨慎操作。

验证工作区

# 检查工作区状态
copaw workspace validate <agent-id>

# 示例
copaw workspace validate default

多 Agent 操作

指定 Agent

几乎所有命令都支持 --agent-id 参数：

# 模型管理
copaw models list --agent-id <id>
copaw models set-llm --agent-id <id>

# 渠道管理
copaw channels list --agent-id <id>
copaw channels config dingtalk --agent-id <id>

# 定时任务
copaw cron list --agent-id <id>
copaw cron create --agent-id <id> ...

# 会话管理
copaw chats list --agent-id <id>

默认 Agent

如果不指定 --agent-id，默认操作 default agent：

# 这两个命令等价
copaw models list
copaw models list --agent-id default

批量操作

目前不支持批量操作所有 agent，需要逐个检查：

# 检查所有 agent 的模型
copaw agent list | awk '{print $1}' | while read id; do
  echo "=== Agent: $id ==="
  copaw models list --agent-id $id
done

配置迁移

从单 agent 迁移

CoPaw 会自动迁移旧配置：

2026-03-18 09:04:13 | Checking for legacy config migration...
2026-03-18 09:04:13 | ============================================================
2026-03-18 09:04:13 | Migrating legacy config to multi-agent structure...
2026-03-18 09:04:13 | ============================================================
2026-03-18 09:04:13 | Created default agent workspace: /Users/liuwangyang/.copaw/workspaces/default
2026-03-18 09:04:13 | Created agent config: /Users/liuwangyang/.copaw/workspaces/default/agent.json
2026-03-18 09:04:13 | Updated root config.json to multi-agent structure
2026-03-18 09:04:13 | ============================================================
2026-03-18 09:04:13 | Migration completed successfully!
2026-03-18 09:04:13 |   Default agent workspace: /Users/liuwangyang/.copaw/workspaces/default
2026-03-18 09:04:13 |   Default agent config: /Users/liuwangyang/.copaw/workspaces/default/agent.json
2026-03-18 09:04:13 | ============================================================

手动迁移

如果自动迁移失败，可以手动迁移：

1. 备份旧配置：

   cp -r ~/.copaw ~/.copaw.backup

2. 创建新工作区：

   copaw workspace create default

3. 复制配置：

   cp ~/.copaw.backup/config.json ~/.copaw/workspaces/default/agent.json

4. 重启服务：

   copaw daemon reload-config

工作区检查

检查工作区结构

# 列出所有工作区
ls -la ~/.copaw/workspaces/

# 检查特定工作区
ls -la ~/.copaw/workspaces/<agent-id>/

检查配置文件

# 查看 agent 配置
cat ~/.copaw/workspaces/<agent-id>/agent.json

# 查看定时任务
cat ~/.copaw/workspaces/<agent-id>/jobs.json

# 查看聊天记录
cat ~/.copaw/workspaces/<agent-id>/chats.json

检查内置 Skills

# 列出内置 skills
ls -la ~/.copaw/workspaces/<agent-id>/active_skills/

# 查看特定 skill
cat ~/.copaw/workspaces/<agent-id>/active_skills/cron/SKILL.md

检查向量数据库

# 检查向量数据库（如果启用）
ls -la ~/.copaw/workspaces/<agent-id>/file_store/

常见问题

Agent 不存在

错误：

Error: Agent 'xxx' not found

解决： 1. 检查 agent 列表：copaw agent list 2. 创建新 agent：copaw workspace create <id> 3. 检查拼写错误

工作区损坏

错误：

Error: Workspace directory not found

解决： 1. 检查工作区：ls -la ~/.copaw/workspaces/ 2. 重新初始化：copaw init --force 3. 从备份恢复：cp -r ~/.copaw.backup/workspaces/<id> ~/.copaw/workspaces/

配置冲突

错误：

Error: Configuration conflict

解决： 1. 检查 agent.json 格式：cat ~/.copaw/workspaces/<id>/agent.json 2. 验证 JSON 格式：python -m json.tool ~/.copaw/workspaces/<id>/agent.json 3. 重置配置：copaw init --force

Skills 加载失败

错误：

Error: Failed to load skill 'xxx'

解决： 1. 检查 skill 目录：ls ~/.copaw/workspaces/<id>/active_skills/ 2. 检查依赖项：pip list 3. 查看详细错误：copaw daemon logs -n 200

日志查看

全局日志

# 查看所有 agent 的日志
copaw daemon logs -n 100

# 过滤特定 agent 的日志
copaw daemon logs -n 100 | grep "agent-2"

工作区日志

# 查看特定工作区的日志
tail -f ~/.copaw/workspaces/<agent-id>/copaw.log

性能优化

资源隔离

每个 agent 独立运行，资源隔离：

• 独立的内存空间
• 独立的向量数据库
• 独立的聊天记录

并发控制

默认情况下，所有 agent 共享同一个 daemon 进程。如果需要更高的并发性能：

1. 增加工作线程：

   copaw app --workers 4

2. 使用多进程部署（Docker）：

   docker run -d -p 8088:8088 copaw:latest
   docker run -d -p 8089:8088 copaw:latest

最佳实践

Agent 命名

• 使用有意义的名称：production, staging, dev
• 避免特殊字符：只使用字母、数字、下划线、连字符
• 保持简短：建议不超过 20 个字符

配置管理

1. 独立配置：每个 agent 有独立的配置文件 2. 版本控制：将 agent.json 加入 Git 管理 3. 环境隔离：不同环境使用不同的 agent

监控和告警

1. 定期检查：使用 heartbeat 定期检查所有 agent 状态 2. 日志监控：监控 daemon 日志，及时发现异常 3. 资源监控：监控 CPU、内存、磁盘使用情况

备份策略

1. 定期备份：定期备份工作区目录 2. 配置备份：备份所有 agent.json 文件 3. 数据备份：备份向量数据库和聊天记录

参考资料

• CoPaw 命令速查
• 故障恢复策略
• 内置 Skills 说明