第 11 章トラブルシューティングと最適化

OpenClaw を使用すると、さまざまな問題が発生することは避けられません。この章では、一般的な問題の解決策、パフォーマンスチューニングのヒント、コミュニティリソースについてまとめます。

読書に関するアドバイス: セクション 1「よくある質問のクイックチェック」は、問題が発生したときにすぐに見つけられるように、全員が読むことをお勧めします。特定の問題が発生した場合は、次のログ診断、パフォーマンスの最適化、その他のコンテンツを読むことができます。

1. 簡単な FAQ

1.1 インストールの問題

問題	原因	ソリューション
`npm install -g openclaw` 失敗	Node.js のバージョンが低すぎます	Node.js 22+ にアップグレード
権限エラー	npm グローバルインストールに対する権限が不十分です	`sudo` を使用するか、npm プレフィックスを設定します。
ネットワークタイムアウト	npm ソースにアクセスできません	タオバオのソースに切り替える: `npm config set registry https://registry.npmmirror.com`

1.2 API接続の問題

問題	原因	ソリューション
`401 Unauthorized`	API キーが無効か期限切れです	API キーの確認と更新
`429 Too Many Requests`	API 呼び出し制限に達しました	同時タスクを減らすか、API パッケージをアップグレードする
接続タイムアウト	ネットワークの問題（特に海外APIアクセス時）	ネットワークプロキシ (HTTP_PROXY 環境変数) を構成するか、国内プロバイダー (シリコンモバイルなど、第 1 章を参照) に切り替えます。
`503 Service Unavailable`	API サービスは一時的に利用できません	回復を待つか、バックアップモデルに切り替えます
助手は「記憶喪失」（以前に与えられた情報を忘れる）を患っています。長い会話はコンテキストウィンドウを超え、ネイティブメモリ圧縮により詳細が失われます。キー情報を USER.md または MEMORY.md に書き込みます (詳細については、第九章を参照)。長距離シナリオでは、OpenViking メモリプラグインをインストールできます。

1.3 チャネルアクセスの問題

問題	原因	ソリューション
電報が応答しない	ボットトークンエラーまたはネットワークの問題	トークンを確認し、プロキシ構成を確認します。
Feishu メッセージが応答しません。権限が有効になっていない、またはペアリングが完了していません。 Feishu オープンプラットフォームの権限設定を確認する
QQ が切断されました	NapCat WebSocket が切断されました	NapCat の実行ステータスを確認し、再度ログインします。

1.4 スキルの問題

問題	原因	ソリューション
`clawhub install` 失敗	ネットワークの問題またはスキル名が間違っています	ネットワークをチェックし、スキル名 (スラッグ) が正しいことを確認します。
インストール後はスキルが使用できなくなります	システムの依存関係が欠落しています	SKILL.md で要件を確認する
API キーの設定後もエラーが報告される	openclaw.json 形式エラー	対話型構成には `openclaw config` を使用します。

展開: ログ診断

2. ログ診断

2.1 ログの表示

bash

# 查看实时日志（持续输出）
openclaw logs --follow

# 查看最近 100 条日志
openclaw logs --limit 100

# 以 JSON 格式输出（方便用 jq 等数据处理工具过滤，新手可忽略此选项）
openclaw logs --limit 100 --json

# 纯文本输出（无颜色）
openclaw logs --limit 50 --plain

2.2 ログレベル

jsonc

// openclaw.json 中的 logging 配置
{
  "logging": {
    "level": "info",
    "file": true,
    "maxSize": "50mb",
    "maxFiles": 10
  }
}

開発中およびデバッグ中に一時的にデバッグレベルをオンにすることができます。

bash

openclaw config set logging.level debug
openclaw gateway restart

展開: パフォーマンスの最適化

3. パフォーマンスの最適化

3.1 応答速度

アクティブなスキルの減少: スキルごとに約 200 ～ 500 トークンずつコンテキストが追加されました。 10 スキルで 3000 ～ 5000 トークンが追加される場合があります。

bash

# 查看当前活跃技能数量
clawhub list --active

# 禁用不常用的技能
clawhub uninstall rarely-used-skill

より高速なモデルを使用: Haiku は、単純なタスクでは Opus より 5 ～ 10 倍高速です。

キャッシュを有効にする:

json

{
  "cache": {
    "enabled": true,
    "ttl": 3600,
    "maxSize": "100mb"
  }
}

3.2 メモリの最適化

bash

# 查看 OpenClaw 内存使用
openclaw status --verbose

# 清理对话历史缓存
openclaw cleanup --conversations --older-than 7d

# 清理技能缓存
openclaw cleanup --skill-cache

3.3 トークンの最適化

bash

# 查看每次调用的 Token 消耗
openclaw usage --detail

# 按技能统计
openclaw usage --by-skill --period month

展開: データのバックアップとリカバリ

4. データのバックアップとリカバリ

4.1 バックアップが必要なもの

~/.openclaw/
├── openclaw.json        # 配置文件（API Key、渠道设置）
├── workspace/           # 工作区（详见第九章第 7 节）
│   ├── IDENTITY.md      # 助理身份（名字、风格）
│   ├── SOUL.md          # 人格设定和行为准则
│   ├── USER.md          # 你的个人信息和偏好
│   ├── AGENTS.md        # 工作流程和操作规范
│   ├── TOOLS.md         # 环境专属信息（服务器、设备等）
│   ├── MEMORY.md        # 长期记忆
│   ├── HEARTBEAT.md     # 定期巡检清单
│   ├── BOOT.md          # 网关启动时执行的任务
│   ├── BOOTSTRAP.md     # 首次运行初始化（完成后自动删除）
│   └── memory/          # 每日工作日志
├── skills/              # 已安装技能及配置
├── cron/                # 定时任务
└── conversations/       # 对话历史

4.2 バックアップコマンド

bash

# 完整备份
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw/

# 只备份配置和工作区（不含对话历史）
tar -czf openclaw-config-$(date +%Y%m%d).tar.gz \
  ~/.openclaw/openclaw.json \
  ~/.openclaw/workspace/ \
  ~/.openclaw/skills/ \
  ~/.openclaw/cron/

4.3 回復

bash

# 恢复备份
tar -xzf openclaw-backup-20260307.tar.gz -C ~/

# 重启服务
openclaw gateway restart

展開: アップグレードガイド

5. アップグレードガイド

5.1 OpenClaw のアップグレード

bash

# 查看当前版本
openclaw --version

# 升级到最新版
npm update -g openclaw

# Docker 用户
docker pull ghcr.io/openclaw/openclaw:latest
docker compose up -d

5.2 アップグレードに関する注意事項

アップグレードする前に ~/.openclaw/ ディレクトリをバックアップしてください
重大な変更についてはリリースノートを参照してください
メジャーバージョンアップ後に一部のスキルの再設定が必要になる場合があります

6. コミュニティリソース

6.1 公式リソース

リソース	住所
公式ドキュメント	https://openclaw.ai/docs
GitHub リポジトリ	https://github.com/openclaw/openclaw
ClawHub スキルマーケット	https://github.com/openclaw/clawhub
ディスコードコミュニティ	https://discord.gg/openclaw

6.2 中国人コミュニティ

リソース	住所
このチュートリアルのオンライン版	https://datawhalechina.github.io/hello-claw
データホエールコミュニティ	https://github.com/datawhalechina

6.3 助けを得る

問題が発生した場合のトラブルシューティング手順:

まず、この章の「クイック FAQ」を確認してください。
GitHub の問題を検索する
Discord コミュニティで質問する
GitHub の問題を送信する (ログと再現手順を添付)

「Adopt a Claw」をすべて完了したことおめでとうございます!これで、OpenClaw のインストールと構成、モバイルアクセス、自動化されたタスク、スキルシステム、外部サービスの統合、運用展開、マルチモデルの最適化、および実用的なアプリケーションシナリオをマスターできました。

OpenClaw の内部についてさらに詳しく知りたい場合、または独自の AI エージェントを最初から構築したい場合は、第 2 部「Claw の構築」を読み続けてください。

次のステップ: 第二部分：构建 Claw

第 11 章 トラブルシューティングと最適化 ​

1. 簡単な FAQ ​

1.1 インストールの問題 ​

1.2 API接続の問題 ​

1.3 チャネルアクセスの問題 ​

1.4 スキルの問題 ​

2. ログ診断 ​

2.1 ログの表示 ​

2.2 ログレベル ​

3. パフォーマンスの最適化 ​

3.1 応答速度 ​

3.2 メモリの最適化 ​

3.3 トークンの最適化 ​

4. データのバックアップとリカバリ ​

4.1 バックアップが必要なもの ​

4.2 バックアップコマンド ​

4.3 回復 ​

5. アップグレードガイド ​

5.1 OpenClaw のアップグレード ​

5.2 アップグレードに関する注意事項 ​

6. コミュニティリソース ​

6.1 公式リソース ​

6.2 中国人コミュニティ ​

6.3 助けを得る ​

第 11 章トラブルシューティングと最適化

1. 簡単な FAQ

1.1 インストールの問題

1.2 API接続の問題

1.3 チャネルアクセスの問題

1.4 スキルの問題

2. ログ診断

2.1 ログの表示

2.2 ログレベル

3. パフォーマンスの最適化

3.1 応答速度

3.2 メモリの最適化

3.3 トークンの最適化

4. データのバックアップとリカバリ

4.1 バックアップが必要なもの

4.2 バックアップコマンド

4.3 回復

5. アップグレードガイド

5.1 OpenClaw のアップグレード

5.2 アップグレードに関する注意事項

6. コミュニティリソース

6.1 公式リソース

6.2 中国人コミュニティ

6.3 助けを得る