Claw Doctor — OpenClaw Self-Repair Skill
This skill diagnoses and fixes common OpenClaw / NanoClaw problems. When something breaks, run through the checklist below before giving up.
When to Activate
Activate this skill when the user reports any of the following:
- - "skill not found" / skill does not trigger
- "No such file or directory" when running a skill script
- API key errors from a skill
- Skill produces no output or wrong output
- "SKILL.md is invalid" / YAML parse errors
- A skill works globally but not in workspace (or vice versa)
- Skills were working before but stopped after an update
Skill Load Order & Paths
OpenClaw loads skills from two locations. Workspace skills take priority.
CODEBLOCK0
Diagnostic: list all loaded skills
CODEBLOCK1
If a skill appears in both, the workspace version wins — check for version mismatches.
Problem 1 — Skill Does Not Trigger
Symptom: User invokes a skill but Claude ignores it or does not follow the skill procedure.
Diagnosis checklist:
- 1. Is the
SKILL.md actually present and readable?
CODEBLOCK2
- 2. Does the frontmatter YAML parse correctly?
CODEBLOCK3
- 3. Do the
keywords in the SKILL.md match what the user said?
- Add more keyword variants (synonyms, abbreviations) if not matching.
- 4. Is
description clear enough for the model to identify the skill?
- Short, specific descriptions outperform vague ones.
Fix: Ensure frontmatter is valid YAML (no tabs, proper quoting, correct indentation).
Problem 2 — Script Not Found (Path Resolution)
Symptom: INLINECODE3
This is the most common skill bug. Scripts referenced in SKILL.md as scripts/foo are relative to the skill's installation directory inside the OpenClaw plugin cache, not the current working directory.
Canonical fix — resolve the script path dynamically before every use:
CODEBLOCK4
Also check: Is the script executable?
CODEBLOCK5
Problem 3 — API Key Not Configured
Symptom: Skill returns {"success": false, "setup_required": true} or 401/403 errors.
Standard API key setup flow:
- 1. The skill's SKILL.md should document where the key is stored (usually
~/.openclaw/secrets/<skill-name>.key or an env var). - Check if the key file exists:
ls ~/.openclaw/secrets/ 2>/dev/null || echo "No secrets dir"
- 3. Run the skill's setup command (usually
scripts/run setup <api-key>). - Verify the key was saved:
CODEBLOCK7
If no setup command exists, ask the user to set the env var directly:
export SKILL_API_KEY="their-key-here"
# Add to ~/.zshrc or ~/.bashrc for persistence
Problem 4 — Dependency Missing (Node.js / Python / tool)
Symptom: node: command not found, python3: No such file or directory, INLINECODE10
Quick dependency check:
CODEBLOCK9
Fix by platform:
| Tool | macOS | Ubuntu/Debian |
|---|
| Node.js | INLINECODE11 | INLINECODE12 |
| Python 3 |
brew install python3 |
apt install python3 |
| jq |
brew install jq |
apt install jq |
For Python skill dependencies:
CODEBLOCK10
For Node skill dependencies:
cd skills/<skill-name> && npm install 2>/dev/null \
|| echo "No package.json found"
Problem 5 — YAML Frontmatter Errors
Symptom: Skill loads but metadata is wrong / keywords not indexed.
Valid frontmatter template:
CODEBLOCK12
Common mistakes:
| Mistake | Fix |
|---|
| Tabs instead of spaces | Replace with 2-space indentation |
Unquoted : in description |
Wrap value in quotes |
| Missing
name field | Add it — it's required |
|
keywords as inline list
[a, b] | Use block list
- a\n- b |
Validate:
CODEBLOCK13
Problem 6 — Skill Worked Before, Broke After Update
Symptom: OpenClaw updated and a skill stopped working.
Checklist:
- 1. Check if the OpenClaw plugin cache was cleared:
CODEBLOCK14
- 2. Reinstall the skill from source:
CODEBLOCK15
- 3. Check for breaking changes in OpenClaw's skill API — look at the OpenClaw changelog for
SKILL.md format updates.
- 4. Test the script directly (bypassing OpenClaw):
bash skills/<skill-name>/scripts/<main-script> --help
Full Health Check
Run this to get a complete snapshot of the OpenClaw environment:
CODEBLOCK17
For Claude Code Users
This skill also works as a Claude Code user-invocable skill. Add the following to ~/.claude/CLAUDE.md under ## User-Invocable Skills:
CODEBLOCK18
Contributing
Found a new OpenClaw failure mode? Open a PR with:
- 1. The symptom (exact error message or behavior)
- Root cause
- Diagnostic command
- Fix
Keep entries short and command-first. The doctor should be fast to consult.
技能名称: claw-doctor
详细描述:
Claw Doctor — OpenClaw 自我修复技能
本技能用于诊断和修复常见的 OpenClaw / NanoClaw 问题。当出现故障时，请在放弃之前按以下清单逐一排查。
何时激活
当用户报告以下任何情况时，激活此技能：
- - 技能未找到 / 技能未触发
- 运行技能脚本时出现没有那个文件或目录
- 技能相关的 API 密钥错误
- 技能无输出或输出错误
- SKILL.md 无效 / YAML 解析错误
- 技能在全局生效但在工作区无效（或反之）
- 技能之前正常，但更新后停止工作
技能加载顺序与路径
OpenClaw 从两个位置加载技能。工作区技能优先。
优先级 1（高）：/skills//SKILL.md
优先级 2（低）：~/.openclaw/skills//SKILL.md
诊断：列出所有已加载的技能
bash
显示全局安装的技能
ls ~/.openclaw/skills/ 2>/dev/null || echo 无全局技能目录
显示当前工作区安装的技能
ls ./skills/ 2>/dev/null || echo 无工作区技能目录
如果某个技能同时出现在两个位置，工作区版本优先——请检查版本是否不匹配。
问题 1 — 技能未触发
症状：用户调用技能，但 Claude 忽略或不遵循技能流程。
诊断清单：
- 1. SKILL.md 是否实际存在且可读？
bash
cat ./skills/
/SKILL.md | head -20
- 2. 前置 YAML 元数据是否正确解析？
bash
python3 -c
import re, sys
txt = open(skills//SKILL.md).read()
fm = re.search(r^---\n(.*?)\n---, txt, re.DOTALL)
print(找到前置元数据：, bool(fm))
if fm:
import yaml; d = yaml.safe_load(fm.group(1)); print(键：, list(d.keys()))
- 3. SKILL.md 中的 keywords 是否与用户所说的匹配？
- 如果不匹配，添加更多关键词变体（同义词、缩写）。
- 4. description 是否足够清晰，让模型能够识别该技能？
- 简短、具体的描述优于模糊的描述。
修复：确保前置元数据是有效的 YAML（无制表符、正确引号、正确缩进）。
问题 2 — 脚本未找到（路径解析）
症状：bash: scripts/run: 没有那个文件或目录
这是最常见的技能错误。SKILL.md 中引用的脚本（如 scripts/foo）是相对于技能在 OpenClaw 插件缓存中的安装目录，而非当前工作目录。
标准修复——每次使用前动态解析脚本路径：
bash
对于名为 my-skill 且脚本名为 run 的技能
MY_SCRIPT=$(find ~/.openclaw -name run -path /my-skill//scripts/* -type f 2>/dev/null | head -1)
备用：检查工作区技能
[ -z $MYSCRIPT ] && MYSCRIPT=$(find ./skills -name run -path /my-skill/scripts/ -type f 2>/dev/null | head -1)
if [ -z $MY_SCRIPT ]; then
echo 错误：未找到脚本。技能是否已安装？
exit 1
fi
$MY_SCRIPT <参数>
还需检查：脚本是否可执行？
bash
chmod +x ~/.openclaw/skills/my-skill/scripts/*
chmod +x ./skills/my-skill/scripts/*
问题 3 — API 密钥未配置
症状：技能返回 {success: false, setup_required: true} 或 401/403 错误。
标准 API 密钥设置流程：
- 1. 技能的 SKILL.md 应说明密钥存储位置（通常为 ~/.openclaw/secrets/.key 或环境变量）。
- 检查密钥文件是否存在：
bash
ls ~/.openclaw/secrets/ 2>/dev/null || echo 无密钥目录
- 3. 运行技能的设置命令（通常为 scripts/run setup ）。
- 验证密钥已保存：
bash
cat ~/.openclaw/secrets/.key 2>/dev/null | head -c 20
如果没有设置命令，请用户直接设置环境变量：
bash
export SKILLAPIKEY=他们的密钥
添加到 ~/.zshrc 或 ~/.bashrc 以持久化
问题 4 — 依赖缺失（Node.js / Python / 工具）
症状：node: 命令未找到、python3: 没有那个文件或目录、jq: 命令未找到
快速依赖检查：
bash
echo === 核心依赖 === && \
node --version 2>/dev/null || echo 缺失：node && \
python3 --version 2>/dev/null || echo 缺失：python3 && \
jq --version 2>/dev/null || echo 缺失：jq && \
curl --version 2>/dev/null | head -1 || echo 缺失：curl
按平台修复：
| 工具 | macOS | Ubuntu/Debian |
|---|
| Node.js | brew install node | apt install nodejs npm |
| Python 3 |
brew install python3 | apt install python3 |
| jq | brew install jq | apt install jq |
对于 Python 技能依赖：
bash
pip3 install -r skills//requirements.txt 2>/dev/null \
|| echo 未找到 requirements.txt
对于 Node 技能依赖：
bash
cd skills/ && npm install 2>/dev/null \
|| echo 未找到 package.json
问题 5 — YAML 前置元数据错误
症状：技能加载但元数据错误 / 关键词未索引。
有效前置元数据模板：
yaml
name: my-skill-name # 小写，仅使用连字符
description: 一句清晰的描述，说明该技能的功能。
keywords:
- keyword-one
- keyword-two
license: MIT
常见错误：
| 错误 | 修复 |
|---|
| 使用制表符而非空格 | 替换为 2 空格缩进 |
| 描述中未加引号的 : |
将值用引号括起来 |
| 缺少 name 字段 | 添加——这是必填项 |
| keywords 为内联列表 [a, b] | 使用块列表 - a\n- b |
验证：
bash
python3 -c
import yaml, sys
txt = open(skills//SKILL.md).read().split(---)[1]
try:
d = yaml.safe_load(txt)
print(正常：, d)
except yaml.YAMLError as e:
print(YAML 错误：, e)
sys.exit(1)
问题 6 — 技能之前正常，更新后失效
症状：OpenClaw 更新后，某个技能停止工作。
检查清单：
- 1. 检查 OpenClaw 插件缓存是否被清除：
bash
ls ~/.openclaw/plugins/cache/ 2>/dev/null | head -10
- 2. 从源重新安装技能：
bash
# 从克隆的技能仓库
cp -r /path/to/skills-repo/skills/ ~/.openclaw/skills/
- 3. 检查 OpenClaw 技能 API 的破坏性变更——查看 OpenClaw 更新日志中关于 SKILL.md 格式的更新。
- 4. 直接测试脚本（绕过 OpenClaw）：
bash
bash skills//scripts/ --help
全面健康检查
运行以下命令获取 OpenClaw 环境的完整快照：
bash
echo === OpenClaw 健康检查 === && \
echo --- 全局技能 --- && ls ~/.openclaw/skills/ 2>/dev/null || echo (无) && \
echo --- 工作区技能 --- && ls ./skills/ 2>/dev/null || echo (无) && \
echo --- 密钥 --- && ls ~/.openclaw/secrets/
