tianyilt/openclaw-repair-skills

Claw Doctor — OpenClaw 自己修復スキル

このスキルは、OpenClaw / NanoClaw の一般的な問題を診断し、修正します。何かが壊れた場合、諦める前に以下のチェックリストを実行してください。

---

アクティベートするタイミング

以下のいずれかがユーザーから報告された場合、このスキルをアクティベートしてください。

• 「スキルが見つからない」 / スキルがトリガーされない
• スキルスクリプト実行時に「No such file or directory」
• スキルからのAPIキーエラー
• スキルが出力を生成しない、または間違った出力をする
• 「SKILL.md is invalid」 / YAML パースエラー
• スキルがグローバルでは動作するがワークスペースでは動作しない（またはその逆）
• アップデート後にスキルが動作しなくなった

---

スキルのロード順序とパス

OpenClaw は2つの場所からスキルをロードします。ワークスペースのスキルが優先されます。

優先度 1（高）: <workspace>/skills/<skill-name>/SKILL.md
優先度 2（低）:  ~/.openclaw/skills/<skill-name>/SKILL.md

診断: ロードされている全スキルの一覧表示

# グローバルにインストールされているものを表示
ls ~/.openclaw/skills/ 2>/dev/null || echo "グローバルスキルディレクトリがありません"

# 現在のワークスペースにインストールされているものを表示
ls ./skills/ 2>/dev/null || echo "ワークスペーススキルディレクトリがありません"

スキルが両方に存在する場合、ワークスペース版が優先されます — バージョンの不一致を確認してください。

---

問題 1 — スキルがトリガーされない

症状: ユーザーがスキルを呼び出しても、Claude が無視する、またはスキルの手順に従わない。

診断チェックリスト:

1. SKILL.md が実際に存在し、読み取り可能ですか？

   cat ./skills/<skill-name>/SKILL.md | head -20
   

2. フロントマターのYAMLは正しくパースできますか？

   python3 -c "
   import re, sys
   txt = open('skills/<skill-name>/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: No such file or directory

これは最も一般的なスキルのバグです。SKILL.md 内で scripts/foo として参照されるスクリプトのパスは、カレントワーキングディレクトリではなく、OpenClaw プラグインキャッシュ内のスキルのインストールディレクトリを基準とした相対パスです。

標準的な修正 — 使用前にスクリプトパスを動的に解決します:

# スキル名が "my-skill"、スクリプト名が "run" の場合
MY_SCRIPT=$(find ~/.openclaw -name "run" -path "*/my-skill/*/scripts/*" -type f 2>/dev/null | head -1)
# フォールバック: ワークスペーススキルを確認
[ -z "$MY_SCRIPT" ] && MY_SCRIPT=$(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 <args>

併せて確認: スクリプトは実行可能ですか？

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/<skill-name>.key または環境変数）が記載されている必要があります。
2. キーファイルが存在するか確認します:

   ls ~/.openclaw/secrets/ 2>/dev/null || echo "シークレットディレクトリがありません"
   

3. スキルのセットアップコマンド（通常は scripts/run setup <api-key>）を実行します。
4. キーが保存されたことを確認します:

   cat ~/.openclaw/secrets/<skill-name>.key 2>/dev/null | head -c 20
   

セットアップコマンドがない場合、ユーザーに環境変数を直接設定するよう依頼してください:

export SKILL_API_KEY="their-key-here"
# 永続化のために ~/.zshrc または ~/.bashrc に追加

---

問題 4 — 依存関係が不足している（Node.js / Python / ツール）

症状: node: command not found、python3: No such file or directory、jq: command not found

簡単な依存関係チェック:

echo "=== Core deps ===" && \
node --version 2>/dev/null || echo "MISSING: node" && \
python3 --version 2>/dev/null || echo "MISSING: python3" && \
jq --version 2>/dev/null || echo "MISSING: jq" && \
curl --version 2>/dev/null | head -1 || echo "MISSING: 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スキルの依存関係の場合:

pip3 install -r skills/<skill-name>/requirements.txt 2>/dev/null \
  || echo "requirements.txt が見つかりません"

Nodeスキルの依存関係の場合:

cd skills/<skill-name> && npm install 2>/dev/null \
  || echo "package.json が見つかりません"

---

問題 5 — YAMLフロントマターエラー

症状: スキルは読み込まれるが、メタデータが間違っている / キーワードがインデックスされていない。

有効なフロントマターテンプレート:

---
name: my-skill-name         # 小文字、ハイフンのみ
# スキルの機能を説明する明確な1文。
description: One clear sentence describing what this skill does.
keywords:
  - keyword-one
  - keyword-two
license: MIT
---

よくある間違い:

間違い	修正
スペースの代わりにタブ	2スペースのインデントに置き換える
description 内の引用符で囲まれていない :	値を引用符で囲む
name フィールドの欠落	追加する — 必須です
keywords がインラインリスト [a, b]	ブロックリスト - a\n- b を使用する

検証:

python3 -c "
import yaml, sys
txt = open('skills/<skill-name>/SKILL.md').read().split('---')[1]
try:
    d = yaml.safe_load(txt)
    print('OK:', d)
except yaml.YAMLError as e:
    print('YAMLエラー:', e)
    sys.exit(1)
"

---

問題 6 — アップデート後にスキルが動作しなくなった

症状: OpenClaw がアップデートされ、スキルが動作しなくなった。

チェックリスト:

1. OpenClaw プラグインキャッシュがクリアされたか確認します:

   ls ~/.openclaw/plugins/cache/ 2>/dev/null | head -10
   

2. ソースからスキルを再インストールします:

   # クローンしたスキルリポジトリから
   cp -r /path/to/skills-repo/skills/<skill-name> ~/.openclaw/skills/
   

3. OpenClaw のスキルAPIにおける破壊的変更を確認します — OpenClaw のチェンジログで SKILL.md フォーマットの更新を確認してください。

4. スクリプトを直接テストします（OpenClaw をバイパス）:

   bash skills/<skill-name>/scripts/<main-script> --help
   

---

完全なヘルスチェック

これを実行して、OpenClaw 環境の完全なスナップショットを取得します:

echo "=== OpenClaw ヘルスチェック ===" && \
echo "--- グローバルスキル ---" && ls ~/.openclaw/skills/ 2>/dev/null || echo "(なし)" && \
echo "--- ワークスペーススキル ---" && ls ./skills/ 2>/dev/null || echo "(なし)" && \
echo "--- シークレット ---" && ls ~/.openclaw/secrets/ 2>/dev/null || echo "(なし)" && \
echo "--- プラグインキャッシュ ---" && ls ~/.openclaw/plugins/cache/ 2>/dev/null | head -5 || echo "(空)" && \
echo "--- 依存関係 ---" && \
  node --version 2>/dev/null && \
  python3 --version 2>/dev/null && \
  jq --version 2>/dev/null && \
echo "=== 完了 ==="

---

Claude Code ユーザー向け

このスキルは、Claude Code でユーザーが呼び出せるスキルとしても機能します。以下を ~/.claude/CLAUDE.md の ## User-Invocable Skills セクションに追加してください:

### claw-doctor

OpenClaw / NanoClaw の問題を診断して修正します。

**トリガー**: ユーザーがスキルの読み込み失敗、スクリプト未検出、APIキーエラー、SKILL.md破損、OpenClaw が動作しないことに言及した場合

**手順**: claw-doctor の SKILL.md チェックリストに従います:
1. 症状カテゴリを特定する（トリガー / スクリプトパス / APIキー / 依存関係 / YAML / アップデート後）
2. 該当する診断コマンドを実行する
3. 修正を適用し、完全なヘルスチェックで検証する

---

問題 7 — 飞书 Bot が間違ったモデルを使用する

症状: 飞书（Feishu）での応答モデルが openclaw.json の設定と一致しない。または /new 実行後も古いモデルのままである。

根本原因 1 — Session 内の model override が agent 設定を上書きする

Session ファイルは、以前に手動で切り替えたモデルを永続化し、再起動後もクリアされません。

# どの session に model override があるか特定する
python3 -c "
import json
for agent in ['main', 'sii']:
    path = f'/Users/tianyiliang/.openclaw/agents/{agent}/sessions/sessions.json'  # 実際のパスに合わせて調整
    try:
        data = json.load(open(path))
        for k, v in data.items():
            if v.get('model'):
                print(f'[{agent}] {k}: model={v[\"model\"]}')
    except: pass
"

修正: 該当する session から model/modelProvider フィールドを削除するか、session エントリ全体を削除してから、gateway を再起動します:

openclaw gateway restart

---

根本原因 2 — main agent が agents.list にないため、バインディングが無視される

bindings に "agentId": "main" と書いても効果がありません — main はビルトインエージェントであり、agents.list にない場合はルーティング対象として扱われません。

診断:

openclaw agents list --bindings   # main が表示されるか確認

修正: main を明示的に agents.list に追加します:

python3 -c "
import json
path = '~/.openclaw/openclaw.json'  # 実際のパス
cfg = json.load(open(path))
if not any(a['id'] == 'main' for a in cfg['agents']['list']):
    cfg['agents']['list'].insert(0, {
        'id': 'main',
        'name': 'main',
        'workspace': cfg['agents']['defaults']['workspace'],
        'model': {'primary': 'custom-local/gemini-3-pro-preview', 'fallbacks': []}
    })
    json.dump(cfg, open(path,'w'), indent=2, ensure_ascii=False)
    print('main を agents.list に追加しました')
"

---

根本原因 3 — Model ID がローカルプロキシと一致せず、フォールバックが発生する

openclaw.json で設定された model ID が localhost proxy に存在しない場合、静かに次のモデルにフォールバックします。

# 実際に利用可能なモデルを確認する
curl -s http://localhost:8317/v1/models -H "Authorization: Bearer your-api-key-1" \
  | python3 -c "import json,sys; [print(m['id']) for m in json.load(sys.stdin)['data']]" | sort

openclaw.json の model ID と比較し、完全に一致していることを確認してください。

---

問題 8 — Cron ジョブが OpenRouter 経由になる

症状: openclaw status で cron session が model=openrouter/auto と表示され、クラウド経由になるべきではない。

根本原因: session に authProfileOverride: openrouter:* が永続化されている（以前の認証自動切り替えの残骸）。

診断:

python3 -c "
import json
for agent in ['main', 'sii']:
    path = f'~/.openclaw/agents/{agent}/sessions/sessions.json'
    try:
        data = json.load(open(path))
        for k, v in data.items():
            if 'cron' in k and 'openrouter' in v.get('authProfileOverride',''):
                print(f'[{agent}] {k}: auth={v[\"authProfileOverride\"]} model={v.get(\"model\")}')
    except: pass
"

修正: すべての cron session から openrouter のオーバーライドをクリアします:

python3 -c "
import json, glob
for path in glob.glob('~/.openclaw/agents/*/sessions/sessions.json'):
    data = json.load(open(path))
    changed = False
    for k, v in data.items():
        if 'cron' in k and 'openrouter' in v.get('authProfileOverride',''):
            for field in ['model','modelProvider','authProfileOverride','authProfileOverrideSource','authProfileOverrideCompactionCount']:
                v.pop(field, None)
            changed = True
            print(f'修正しました: {k}')
    if changed:
        json.dump(data, open(path,'w'), ensure_ascii=False)
" && openclaw gateway restart

---

問題 9 — Gateway が応答しない / device signature invalid

症状: openclaw status で RPC probe: failed と表示され、エラーは gateway closed (1008): device signature invalid。飞书 bot が応答せず、gateway は起動しているように見えるが CLI が接続できない。

根本原因: OpenClaw バージョンアップ後、古い LaunchAgent（com.clawdbot.gateway、openclaw-cn をロード）がクリーンアップされず、新しい ai.openclaw.gateway と同時に起動時に登録される。古いプロセスが先に 18789 ポートを占有し、新しいバージョンの CLI は device signature フォーマットの非互換性により拒否される。

診断:

launchctl list | grep -i claw
# com.clawdbot.gateway と ai.openclaw.gateway の両方が表示される場合、この問題です

openclaw gateway status 2>&1 | grep -E "RPC|device|pid"

修正:

# 1. 古い LaunchAgent をバックアップして無効化
cp ~/Library/LaunchAgents/com.clawdbot.gateway.plist \
   ~/Library/LaunchAgents/com.clawdbot.gateway.plist.bak
launchctl bootout gui/$UID/com.clawdbot.gateway
mv ~/Library/LaunchAgents/com.clawdbot.gateway.plist \
   ~/Library/LaunchAgents/com.clawdbot.gateway.plist.disabled

# 2. 新しい gateway を再起動
openclaw gateway restart

# 検証
openclaw gateway status 2>&1 | grep "RPC probe"
# 期待される出力: RPC probe: ok

説明: .plist.disabled ファイルは launchd が起動時にロードしません（.plist サフィックスのみ認識）。これにより、無効化しつつバックアップを保持できます。

---

問題 10 — 非オーナーユーザーのアクセスが拒否される（OAuth 認可 / ツール呼び出し）

症状: アプリケーションオーナーではない飞书ユーザーがメッセージを送信すると、認可エントリまたはツール呼び出しが拒否され、ログに OwnerAccessDeniedError または Permission denied: Only the app owner is authorized が表示される。

根本原因: assertOwnerAccessStrict のデフォルトは ownerOnly=true であり、すべての非オーナーユーザーが拒否されます。これは openclaw-lark 上流の既知の問題です（issues #5、#12）。

修正案 A — 設定で無効化（推奨）: openclaw.json の飞书チャンネル設定に uat.ownerOnly: false を追加します:

# python3 で安全に書き込むため、JSON 手動編集によるエラーを回避
python3 - <<'EOF'
import json

path = '/Users/tianyiliang/.openclaw/openclaw.json'  # 実際のパスに合わせて調整
cfg = json.load(open(path))
ch = cfg.setdefault('channels', {}).setdefault('feishu', {})
uat = ch.setdefault('uat', {})
uat['enabled'] = True
uat['ownerOnly'] = False
json.dump(cfg, open(path, 'w'), indent=2, ensure_ascii=False)
print('完了。次を実行: openclaw gateway restart')
EOF

修正案 B — プラグインのアップグレード: workspace ソースコード版プラグイン（openclaw-lark）を使用している場合、このパッチは PR #11 に含まれています:

• src/core/config-schema.ts: UATConfigSchema に ownerOnly?: boolean を追加
• src/core/owner-policy.ts: assertOwnerAccessStrict で ownerOnly フラグをチェック

検証: gateway 再起動後、非オーナーユーザーがメッセージを送信しても、ログに OwnerAccessDeniedError が表示されなくなります。

---

コントリビューション

新しい OpenClaw の障害モードを見つけましたか？以下の内容で PR を開いてください:

1. 症状（正確なエラーメッセージまたは動作）
2. 根本原因
3. 診断コマンド
4. 修正

エントリは簡潔に、コマンドを先頭にしてください。ドクターは迅速に参照できるべきです。