[tools] ClawdBot 配置指南：從安裝到除錯

cover

概念圖

ClawdBot 是什麼？

ClawdBot 是基於 OpenClaw 框架的 Discord 機器人，可以連接各種 LLM（Large Language Model）來提供 AI 助手功能。它支援多種模型提供者，包括 OpenAI、Anthropic、Google Gemini 等。

配置文件位置

ClawdBot 和 OpenClaw 有各自獨立的配置文件：

服務	配置路徑	用途
ClawdBot	`~/.clawdbot/clawdbot.json`	Discord 機器人專用配置
OpenClaw	`~/.openclaw/openclaw.json`	OpenClaw CLI/Gateway 配置

重要：這兩個配置是獨立的！修改 .openclaw/openclaw.json 不會影響 ClawdBot 的行為，反之亦然。

配置文件結構

基本結構

{
  "env": { ... },
  "auth": { ... },
  "models": { ... },
  "agents": { ... },
  "channels": { ... },
  "gateway": { ... }
}

模型配置（關鍵區塊）

模型配置分為兩個部分：

1. 預設模型（agents.defaults.model）

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai-codex/gpt-5.2-codex"
      }
    }
  }
}

這是 Agent 使用的主要模型。格式為 provider/model-id。

2. 認證配置（auth.profiles）

{
  "auth": {
    "profiles": {
      "openai-codex:default": {
        "provider": "openai-codex",
        "mode": "oauth"
      }
    }
  }
}

認證 profile 決定了如何連接到模型提供者。

常見的模型設定

Provider	Model ID 範例	認證方式
openai-codex	`openai-codex/gpt-5.2-codex`	oauth
openai	`openai/gpt-4o`	api_key
anthropic	`anthropic/claude-3-5-sonnet`	api_key
google	`google/gemini-2.0-flash`	api_key

Discord 頻道配置

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "${DISCORD_BOT_TOKEN}",
      "dm": {
        "policy": "allowlist",
        "allowFrom": ["your-user-id"]
      }
    }
  }
}

token：Discord Bot Token（建議用環境變數）
dm.policy：私訊政策（allowlist 或 denylist）
dm.allowFrom：允許私訊的使用者 ID 列表

常見問題排解

問題：出現 Gemini 429 Rate Limit 錯誤

症狀：

Agent failed before reply: All models failed (3):
google/gemini-2.0-flash: LLM error: { "error": { "code": 429, ... } }

原因：配置中可能殘留了 Google 相關的認證 profile 或 fallback 模型設定。

解決方案：

檢查 auth.profiles 是否有 google:default：

// 移除這個
"google:default": {
  "provider": "google",
  "mode": "api_key"
}

確保 agents.defaults.model.primary 指向正確的模型：

"model": {
  "primary": "openai-codex/gpt-5.2-codex"  // 不要用 google/gemini-*
}

清空不需要的 providers：

"models": {
  "providers": {}
}

重啟 ClawdBot（配置修改後必須重啟才會生效）

問題：修改配置後沒有生效

解決方案：必須重啟 Gateway 服務。

# 關閉
taskkill /F /IM node.exe
 
# 啟動（從 .clawdbot 目錄）
cd ~/.clawdbot
pnpm openclaw gateway run

或使用桌面捷徑腳本（見下方）。

問題：不確定目前使用哪個模型

直接在 Discord 問 ClawdBot：

請問你現在使用什麼模型？

它會回報當前的 model ID。

實用腳本

ClawdBot-Start.bat

@echo off
title ClawdBot Gateway
cd /d %USERPROFILE%\.clawdbot
pnpm openclaw gateway run
pause

ClawdBot-Stop.bat

@echo off
title ClawdBot Shutdown
powershell -Command "Get-Process -Name node -ErrorAction SilentlyContinue | Stop-Process -Force"
echo ClawdBot Gateway stopped.
pause

最佳實踐

單一模型提供者：避免配置多個模型提供者，減少 fallback 混亂
使用環境變數：敏感資訊（token、API key）用 ${ENV_VAR} 格式
定期檢查 Gateway 日誌：\tmp\openclaw\openclaw-*.log
保持配置同步：如果同時使用 OpenClaw 和 ClawdBot，確保兩邊配置一致

配置範例：純 OpenAI Codex

{
  "env": {
    "shellEnv": { "enabled": true }
  },
  "auth": {
    "profiles": {
      "openai-codex:default": {
        "provider": "openai-codex",
        "mode": "oauth"
      }
    }
  },
  "models": {
    "providers": {}
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai-codex/gpt-5.2-codex"
      },
      "contextTokens": 8192,
      "timeoutSeconds": 300
    }
  },
  "channels": {
    "discord": {
      "enabled": true,
      "token": "${DISCORD_BOT_TOKEN}",
      "dm": {
        "policy": "allowlist",
        "allowFrom": ["your-user-id"]
      }
    }
  },
  "gateway": {
    "mode": "local"
  }
}

Terry Yao's Blog

分類

目錄