Skills copaw-ops

CoPaw 运维助手。用于用户提到 copaw 运维、服务无响应、渠道断连、MCP 失败、模型调用失败、cron 不执行、Docker 部署、重载、重启或重置恢复时使用。优先执行状态检查与故障分流；涉及重启、重载、重置、配置修改等高影响动作时，先向用户说明再执行。

install

source · Clone the upstream repo

git clone https://github.com/chujianyun/skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/chujianyun/skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/copaw-ops" ~/.claude/skills/chujianyun-skills-copaw-ops && rm -rf "$T"

manifest: skills/copaw-ops/SKILL.md

source content

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

故障分流

服务无响应

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

配置错误

copaw daemon reload-config

copaw daemon logs -n 200

检查 agent.json 配置：
```
cat ~/.copaw/workspaces/<id>/agent.json
```
必要时
```
copaw init --force
```

渠道断连

```
copaw channels list --agent-id <id>
```
检查配置

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

查看详细配置

针对特定渠道：

钉钉：检查

client_id

client_secret

robot_code

；使用

dingtalk_channel

skill 自动连接

飞书：检查
```
app_id
```
,
```
app_secret
```
,
```
encrypt_key
```
QQ：检查
```
app_id
```
,
```
client_secret
```

```
/daemon restart
```
重启服务

模型调用失败

```
copaw models list --agent-id <id>
```
检查当前模型

copaw models config-key <provider> --agent-id <id>

检查 API key

```
copaw models set-llm --agent-id <id>
```
切换模型

定时任务不执行

```
copaw cron list --agent-id <id>
```
列出所有任务

copaw cron state <job_id> --agent-id <id>

检查任务状态

检查 jobs.json：
```
cat ~/.copaw/workspaces/<id>/jobs.json
```

copaw cron resume <job_id> --agent-id <id>

恢复任务

```
copaw cron run <job_id> --agent-id <id>
```
手动执行测试

内置 Skills 故障（新增）

检查 skill 是否存在：

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

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

上下文爆满

```
/compact
```
或
```
/new
```
用
```
/history
```
验证 Token 使用

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

检查配置：

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

检查必填字段：
- ```
client_id
```
- ```
client_secret
```
- ```
robot_code
```
  （可选）

使用自动连接 skill：

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

检查机器人是否发布（重要！）
检查 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
```
（新增）

回复模板

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

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

多 Agent 环境注意事项

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

常见错误

Agent 不存在

Error: Agent 'xxx' not found

解决：

检查 agent 列表：
```
copaw agent list
```
创建新 agent：
```
copaw workspace create <id>
```

工作区损坏

Error: Workspace directory not found

解决：

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

内置 Skill 加载失败

Error: Failed to load skill 'xxx'

解决：

检查 skill 目录：

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

检查依赖项：
```
pip list
```
查看详细错误：
```
copaw daemon logs -n 200
```