OpenClaw 是一個開源 AI 助手框架，讓你可以在多個訊息平台（WhatsApp、Telegram、Discord 等）部署自己的 AI 助手。
Moltbook 是一個社群驅動的共享服務，OpenClaw 使用者可以加入現有實例而無需自己託管。
適合人群：開發者、技術愛好者、需要私有 AI 助手的團隊、以及任何想要掌控自己 AI 互動的人。
OpenClaw & Moltbook FAQ
新手常見問題與排錯指南：從安裝、配置、接入渠道到安全注意事項，快速跑通第一個成功案例。
共 33 個問題
OpenClaw 快速開始
先跑通第一個成功案例
Desktop（圖形介面）推薦給新手 - 提供視覺化配置、即時日誌和一鍵操作。
CLI 更適合：
• 伺服器部署
• 自動化和腳本
• 資源受限的環境
• 偏好終端工作流的開發者
兩個版本核心功能完全相同。
你的最小成功清單：
1. OpenClaw 安裝並運行（健康狀態檢查通過）
2. 至少配置一個模型 API Key（OpenAI、Anthropic 等）
3. 連接一個訊息渠道（建議新手先用 Telegram）
4. 發送測試訊息並收到回覆
使用 Desktop 版本通常只需 5-10 分鐘。
必需：
• 至少一個 AI 模型 API Key（OpenAI、Anthropic、Google 等）
渠道接入（至少選一個）：
• WhatsApp：只需手機上安裝了 WhatsApp
• Telegram：透過 @BotFather 建立機器人
• Discord：在 Discord 開發者門戶建立應用
可選：
• 網路搜尋 API Key（增強功能）
從一個渠道開始的好處：
• 專注把基礎搞對
• 清楚理解訊息流程
• 更容易除錯問題
• 先建立信心，再增加複雜度
熟悉之後，添加更多渠道會很簡單。
OpenClaw 安裝
安裝與環境問題
安裝後檢查以下內容：
1. 執行 `openclaw health` 或 `openclaw status`（CLI）或在 Desktop 中查看健康狀態
2. 確認所有服務都顯示綠色勾號
3. 驗證閘道器可存取（預設：http://127.0.0.1:18789）
4. 檢查日誌是否有錯誤訊息
如果所有檢查都通過，就可以配置渠道了。
啟動問題 Top 5：
1. 連接埠被佔用（其他應用在用 18789 連接埠）
2. API Key 缺失或無效
3. 權限不足（嘗試以管理員身份運行）
4. 防火牆阻止連接
5. 依賴版本過舊（Node.js 需要 v22+）
先查日誌 - 通常會指出具體問題。
解決方案：
1. 找到並停止衝突的進程：
• Mac/Linux: `lsof -i :18789` 然後 `kill [PID]`
• Windows (WSL): `lsof -i :18789` 然後 `kill [PID]`
2. 或者修改 OpenClaw 的連接埠：
• 啟動時使用 `openclaw gateway --port 18790`
• 或在 onboard 時指定 `--gateway-port 18790`
按順序嘗試以下步驟：
1. 檢查日誌：`openclaw logs --follow` 查看錯誤訊息
2. 重新配置：執行 `openclaw configure` 重新設定
3. 重新安裝：`npm install -g openclaw@latest`
4. 查看發布說明中的破壞性變更
5. 如果仍然失敗，帶上日誌到 GitHub Issues 報告
OpenClaw 主要透過 `~/.openclaw/openclaw.json` 配置檔管理設定。
常見問題：
1. 修改配置後沒有重啟服務
2. 使用了錯誤的配置路徑
3. JSON 語法錯誤（缺少逗號、引號等）
4. 環境變數需要在 onboard 時透過參數傳入
驗證目前配置：執行 `openclaw status` 查看生效的設定。
OpenClaw 配置
設定與配置基礎
用餐廳來類比：
• 模型 = 廚師（生成回覆的 AI）
• 通道 = 入口（WhatsApp、Telegram 等）
• 閘道器 = 前台（接收和路由請求）
• 技能 = 特殊能力（網路搜尋、程式碼執行等）
你至少需要一個模型和一個通道。閘道器自動運行。技能是可選的增強功能。
最簡單的方式是執行互動式配置精靈：
```
$ openclaw onboard
```
精靈會引導你完成：
• 選擇 AI 模型提供商（Anthropic/OpenAI 等）
• 輸入 API Key
• 安裝並啟動閘道器服務
配置完成後，再用 `openclaw channels login telegram` 連接渠道。
預設閘道器綁定到 127.0.0.1:18789（僅本地存取，安全）。
在 Desktop 中：設定 → 技能 → 開關切換
在 CLI 中：
• 查看可用技能：`openclaw skills list`
• 安裝技能：`openclaw skills install [skill-name]`
• 啟用技能：`openclaw skills enable [skill-name]`
安全提示：
• 停用不需要的技能
• 啟用前先了解技能需要的權限
• 先在安全環境中測試新技能
• 有些技能可以執行程式碼 - 謹慎啟用
切換模型：
1. 執行 `openclaw onboard` 重新配置，選擇新的模型提供商
2. 或編輯 `~/.openclaw/openclaw.json` 中的 agents.defaults.model 設定
3. 重啟服務：`openclaw gateway status` 確認運行狀態
如果新模型失敗：
• 執行 `openclaw models status` 檢查模型連接狀態
• 在提供商網站上檢查 API Key 是否有效
• 驗證模型名稱拼寫（如 `anthropic/claude-opus-4-5`）
• 檢查帳戶的速率限制或配額
安全檢查清單：
✓ 閘道器預設綁定到 localhost（127.0.0.1）
✓ 不要直接把連接埠暴露到公網
✓ 如果需要遠端存取，使用：
• VPN 或 SSH 隧道
• 帶認證的反向代理
• Cloudflare Tunnel
✓ 如果支援的話啟用認證
✓ 生產環境使用 HTTPS
OpenClaw 渠道接入
各渠道特定問題
嘗試以下修復：
1. 確保手機和電腦在同一網路
2. 刷新二維碼（它們很快過期）
3. 更新手機上的 WhatsApp 到最新版本
4. 如果用網頁介面，清除瀏覽器快取
5. 在光線充足的環境掃碼
6. 暫時關閉 VPN
如果仍然失敗，試試手機連結碼方式。
工作階段問題通常由以下原因導致：
1. 手機離線或休眠
2. 手機上的 WhatsApp 被登出
3. 在其他裝置上使用了 WhatsApp Web
4. 網路不穩定
解決方法：
• 保持手機連接穩定的 WiFi
• 關閉 WhatsApp 的電池最佳化
• 不要在其他地方打開 WhatsApp Web
• 檢查 WhatsApp 應用更新
群組行為通常是有意設計的：
• 檢查配置中是否啟用了群組回覆
• 機器人可能需要 @提及才會在群組裡回覆
• 出於安全考慮，預設配置可能停用群組訊息
啟用方法：
• 在 Desktop 設定中啟用群組回覆
• 或透過 `openclaw pairing` 管理群組權限
• 先在小群測試確保正常運作
Telegram 機器人預設啟用隱私模式：
1. 打開 @BotFather
2. 發送 /mybots
3. 選擇你的機器人
4. Bot Settings → Group Privacy → Turn OFF
或者，把機器人設為群組管理員 - 管理員無論隱私模式如何都能看到所有訊息。
簡單步驟：
1. 打開 Telegram，搜尋 @BotFather
2. 發送 /newbot
3. 選擇一個名稱（顯示名）
4. 選擇一個使用者名稱（必須以 'bot' 結尾）
5. 複製提供的 API Token
6. 將 Token 添加到 OpenClaw 配置中
可選：使用 /setcommands 添加指令提示。
通常是 intents 問題：
1. 前往 Discord 開發者門戶
2. 選擇你的應用 → Bot
3. 啟用這些特權 Intents：
• MESSAGE CONTENT INTENT
• SERVER MEMBERS INTENT（如果需要）
4. 儲存並重啟機器人
另外檢查：機器人在頻道是否有讀取訊息權限。
必需的 intents：
• Guilds - 基本伺服器資訊
• Guild Messages - 接收訊息
• Message Content - 讀取訊息內容（特權）
可選：
• Guild Members - 使用者資訊（特權）
• Direct Messages - 私訊支援
注意：特權 intents 在 100+ 伺服器的機器人需要驗證。
最小 Bot Token Scopes：
• chat:write - 發送訊息
• app_mentions:read - 回應 @提及
• channels:history - 讀取頻道訊息
• im:history - 讀取私訊
事件訂閱：
• message.channels
• message.im
• app_mention
從最小權限開始，按需添加更多。
OpenClaw 故障排除
常見問題快速修復
401 表示認證失敗。檢查：
1. API Key 是否正確（沒有多餘空格）
2. Key 是否過期或被撤銷
3. Key 是否有所需的權限/範圍
4. 是否觸發了速率限制
5. 帳戶是否有足夠的額度/配額
先直接用提供商的 API 測試你的 Key。
逐步診斷：
1. 直接測試模型（curl/Postman）- 如果慢，是模型問題
2. 檢查你的網路速度和延遲
3. 試試不同的模型（GPT-3.5 比 GPT-4 快）
4. 查看提供商狀態頁面是否有故障
解決方法：
• 增加逾時設定
• 對長回覆使用串流回應
• 嘗試其他模型提供商
在日誌中查找這些模式：
• 'FATAL' 或 'PANIC' - 嚴重錯誤
• 'OOM' - 記憶體不足
• 'ECONNREFUSED' - 無法連接依賴
• 堆疊追蹤 - 程式碼錯誤
常見修復：
• 增加記憶體分配
• 修復配置錯誤
• 更新到最新版本
• 檢查外部服務可用性
配置排查：
1. 重啟服務了嗎？（大多數改動需要重啟閘道器）
2. JSON 檔案語法正確嗎？（檢查逗號、引號）
3. 是正確的配置檔案嗎？（應該是 `~/.openclaw/openclaw.json`）
4. 閘道器在運行嗎？（`openclaw gateway status`）
驗證配置：
• `openclaw status` - 查看整體狀態
• `openclaw models status` - 檢查模型連接
• `openclaw health` - 健康檢查
日誌位置：
• Desktop：檢視 → 日誌（或設定 → 打開日誌資料夾）
• CLI：`~/.openclaw/logs/` 或標準輸出
• Docker：`docker logs [容器名]`
關鍵錯誤關鍵字：
• ERROR, FATAL, PANIC - 嚴重問題
• timeout, ETIMEDOUT - 連接問題
• 401, 403, 429 - 認證/速率限制問題
• ENOENT - 檔案/路徑缺失
報告中包含：
1. OpenClaw 版本（`openclaw --version`）
2. 作業系統和版本
3. 重現步驟
4. 預期 vs 實際行為
5. 相關日誌（移除敏感資訊！）
6. 配置片段（移除 API Key！）
提交地址：GitHub Issues 頁面
安全問題：直接發郵件給安全聯絡人
OpenClaw 安全指南
安全最佳實踐
公網暴露的風險：
• 任何人都可以向你的 AI 發送請求
• API Key 可能被提取
• 可能被濫用（垃圾訊息、非法內容）
• 未授權使用導致費用暴漲
• 機器人行為的法律責任
安全的遠端存取選項：
• VPN（推薦）
• SSH 隧道
• Cloudflare Tunnel
• 帶認證的反向代理
安全檢查清單：
1. 是否來自官方/驗證過的來源？
2. 如果有原始碼，檢查一下
3. 閱讀其他使用者的評論/問題
4. 了解它請求什麼權限
5. 先在隔離環境中測試
危險信號：
• 請求不必要的權限
• 程式碼被混淆/壓縮
• 沒有原始碼可查
• 沒有社群反饋
立即行動：
1. 現在就在提供商網站上撤銷這個 Key
2. 生成新的 Key
3. 用新 Key 更新所有配置
4. 檢查使用歷史是否有未授權呼叫
5. 復盤是怎麼洩露的（git 歷史？公開儲存庫？）
預防措施：
• 永遠不要把 Key 提交到 git
• 使用 .env 檔案（加入 gitignore）
• 生產環境使用金鑰管理工具
安全預設配置：
• 閘道器只綁定到 localhost（127.0.0.1）
• 技能預設停用
• 群組訊息初始停用
• 啟用速率限制
• 啟用日誌記錄（用於審計）
• 渠道機器人使用最小權限
記住：從嚴格開始，按需放寬。
還是卡住了？
沒找到你要的答案？試試這些資源：