第十一章 故障排查與優化
使用 OpenClaw 的過程中難免會遇到各種問題。本章彙總了常見問題的解決方案、性能調優技巧和社區資源。
閱讀建議：第 1 節"常見問題速查"建議每個人都過一遍，遇到問題時能快速定位。後面的日誌診斷、性能優化等內容可以等遇到具體問題時再展開閱讀。
1. 常見問題速查
1.1 安裝問題
| 問題 | 原因 | 解決方案 |
|---|---|---|
npm install -g openclaw 失敗 | Node.js 版本過低 | 升級到 Node.js 22+ |
| 權限錯誤 | npm 全局安裝權限不足 | 使用 sudo 或配置 npm prefix |
| 網絡超時 | npm 源不可訪問 | 切換爲淘寶源：npm config set registry https://registry.npmmirror.com |
1.2 API 連接問題
| 問題 | 原因 | 解決方案 |
|---|---|---|
401 Unauthorized | API Key 無效或過期 | 檢查並更新 API Key |
429 Too Many Requests | 達到 API 調用限制 | 減少併發任務，或升級 API 套餐 |
| 連接超時 | 網絡問題（尤其訪問海外 API） | 配置網絡代理（HTTP_PROXY 環境變量）或改用國內提供商（如硅基流動，參考第一章） |
503 Service Unavailable | API 服務暫時不可用 | 等待恢復，或切換到備用模型 |
| 助理"失憶"（忘記之前交代的信息） | 長對話超出上下文窗口，原生記憶壓縮丟失細節 | 將關鍵信息寫入 USER.md 或 MEMORY.md（詳見第九章）；長程場景可安裝 OpenViking 記憶插件 |
1.3 渠道接入問題
| 問題 | 原因 | 解決方案 |
|---|---|---|
| Telegram 無響應 | Bot Token 錯誤或網絡問題 | 檢查 Token，確認代理配置 |
| 飛書消息不回覆 | 權限未開通或未完成配對 | 檢查飛書開放平臺權限設置 |
| QQ 斷線 | NapCat WebSocket 斷開 | 檢查 NapCat 運行狀態，重新登錄 |
1.4 技能問題
| 問題 | 原因 | 解決方案 |
|---|---|---|
clawhub install 失敗 | 網絡問題或技能名稱錯誤 | 檢查網絡，確認技能名稱（slug）正確 |
| 技能安裝後不可用 | 缺少系統依賴 | 檢查 SKILL.md 中的 requirements |
| API Key 配置後仍報錯 | 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 --plain2.2 日誌級別
jsonc
// openclaw.json 中的 logging 配置
{
"logging": {
"level": "info",
"file": true,
"maxSize": "50mb",
"maxFiles": 10
}
}開發調試時可以臨時開啓 debug 級別：
bash
openclaw config set logging.level debug
openclaw gateway restart展開：性能優化
3. 性能優化
3.1 響應速度
減少活躍技能：每個技能增加約 200-500 tokens 的上下文。10 個技能可能增加 3000-5000 tokens。
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-cache3.3 Token 優化
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 -d5.2 升級注意事項
- 升級前備份
~/.openclaw/目錄 - 查看 Release Notes 瞭解破壞性變更
- 大版本升級後可能需要重新配置部分技能
6. 社區資源
6.1 官方資源
| 資源 | 地址 |
|---|---|
| 官方文檔 | https://openclaw.ai/docs |
| GitHub 倉庫 | https://github.com/openclaw/openclaw |
| ClawHub 技能市場 | https://github.com/openclaw/clawhub |
| Discord 社區 | https://discord.gg/openclaw |
6.2 中文社區
| 資源 | 地址 |
|---|---|
| 本教程在線版 | https://datawhalechina.github.io/hello-claw |
| Datawhale 社區 | https://github.com/datawhalechina |
6.3 獲取幫助
遇到問題時的排查步驟：
- 先查本章的"常見問題速查"
- 搜索 GitHub Issues
- 到 Discord 社區提問
- 提交 GitHub Issue（附上日誌和復現步驟）
恭喜你完成了"領養 Claw"的全部內容！現在你已經掌握了 OpenClaw 的安裝配置、移動端接入、自動化任務、技能系統、外部服務集成、生產部署、多模型優化和實際應用場景。
如果你想進一步瞭解 OpenClaw 的內部原理，或者從零構建自己的 AI Agent，請繼續閱讀第二部分"構建 Claw"。
下一步：第二部分：構建 Claw