Skip to main content

​
專案介紹

OpenClaw 是一個開源、自託管的個人 AI 助手平台，將訊息應用連接到運行在你自己硬體上的 AI 代理。專為開發者和進階用戶設計，無需交出資料控制權即可擁有自主 AI 助手。 OpenClaw 完全開源，你可以在 OpenClaw 的 GitHub 倉庫 瀏覽原始碼、提交 Issue 或參與貢獻。本教程涵蓋安裝、配置，以及將 OpenClaw 對接 MixRoute API 的完整步驟。

​
🌟 核心特性

​
多管道整合

  • Canvas 介面：可渲染互動式 Canvas 介面
  • 語音支援：支援 macOS/iOS/Android 語音互動
  • 單一閘道：透過一個 Gateway 進程統一管理所有管道
  • 多管道整合：支援 Telegram、Discord、WhatsApp、iMessage 等多種訊息管道，也可透過外掛擴充更多平台

​
自託管與資料安全

  • 資料本地化：上下文和技能儲存在你的本地電腦，而非雲端
  • 開源透明：MIT 開源協議，程式碼完全透明
  • 完全自託管：運行在你自己的機器或伺服器上

​
智能代理能力

  • 工具呼叫：原生支援工具呼叫和程式碼執行
  • 多代理路由：支援多代理協同工作
  • 會話隔離：依代理/工作區/發送者隔離會話
  • 排程任務：支援 cron 定時任務
  • 持續運行：支援背景常駐運行，擁有持久記憶

​
📦 接入前準備

準備資訊

  • Node.js 22 或更高版本
  • 一個可用的 MixRoute API 位址（通常以 /v1 結尾）
  • 一個可用的 MixRoute API Key
在開始接入 MixRoute API 之前，建議先依照 OpenClaw 官方目前推薦流程把 Gateway 和 Control UI 跑起來。這樣後續排查問題時，更容易區分是 OpenClaw 本身未啟動，還是模型提供者配置有誤。

​
1. 安裝 OpenClaw（macOS/Linux）

curl -fsSL https://openclaw.ai/install.sh | bash
其他安裝方式可參考 OpenClaw 官方文檔：Getting Started。

​
2. 運行引導精靈

openclaw onboard --install-daemon
該精靈會完成基礎認證、Gateway 設置，以及可選的管道初始化。這裡的目標是先把 OpenClaw 跑起來，後面再把預設模型切到 MixRoute API。

​
3. 檢查 Gateway 與 Control UI

openclaw gateway status

openclaw dashboard
如果瀏覽器能打開 Control UI，說明 OpenClaw 基礎運行已經正常。此階段不需要先配置 Telegram、Discord、飛書等訊息管道。

​
4. 定位配置檔

OpenClaw 的配置檔通常位於 ~/.openclaw/openclaw.json，你可以在引導精靈生成的基礎上繼續修改。
如果你把 OpenClaw 跑在專用服務帳號下，或希望自訂配置/狀態目錄，可以使用環境變數 OPENCLAW_CONFIG_PATH、OPENCLAW_STATE_DIR、OPENCLAW_HOME。詳細說明見官方文檔：Environment Variables。

​
🚀 使用 MixRoute API 作為模型提供者

OpenClaw 支援透過 models.providers 接入自訂或相容 OpenAI 介面的模型閘道。對於 MixRoute API，最常見的做法是把它作為一個自訂 provider 加進配置裡，再把預設模型指向 mixroute/模型ID。

​
接入思路

  1. 在 models.providers 下宣告一個 mixroute provider
  2. 將 baseUrl 指向你的 MixRoute API 位址，並確保包含 /v1
  3. 將 api 設為 openai-completions
  4. 在 models 中列出你希望 OpenClaw 使用的模型 ID
  5. 在 agents.defaults.model.primary 中把預設模型切到 mixroute/...

​
推薦做法：用環境變數保存金鑰

先在當前 shell、服務環境，或 OpenClaw 可讀取的 .env 中提供你的 MixRoute API 金鑰： 
export MIXROUTE_API_KEY="sk-your-mixroute-key"
然後在 openclaw.json 裡補充或修改以下片段： 
{
  "models": {
    "mode": "merge",
    "providers": {
      "mixroute": {
        "baseUrl": "https://api.mixroute.ai/v1",
        "apiKey": "${MIXROUTE_API_KEY}",
        "api": "openai-completions",
        "models": [
          { "id": "gemini-2.5-flash", "name": "Gemini 2.5 Flash" },
          { "id": "kimi-k2.5", "name": "Kimi K2.5" }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "mixroute/gemini-2.5-flash",
        "fallbacks": ["mixroute/kimi-k2.5"]
      },
      "models": {
        "mixroute/gemini-2.5-flash": { "alias": "flash" },
        "mixroute/kimi-k2.5": { "alias": "kimi" }
      }
    }
  }
}
這不是一份必須原樣照抄的完整配置，而是接入 MixRoute API 最關鍵的部分。只要 provider、模型 ID 和預設模型引用對應正確，OpenClaw 就能透過 MixRoute API 呼叫你暴露出來的模型資源。

​
關鍵配置說明

配置項說明
models.mode建議設為 merge，在保留 OpenClaw 內建 provider 的同時追加 mixroute
models.providers.mixroute.baseUrl你的 MixRoute API 位址，通常為 https://api.mixroute.ai/v1，需包含 /v1
models.providers.mixroute.apiKeyMixRoute API 金鑰，推薦透過 ${MIXROUTE_API_KEY} 注入
models.providers.mixroute.api對於 MixRoute API 這類 OpenAI 相容閘道，使用 openai-completions
models.providers.mixroute.models這裡列出的模型 ID 必須與 MixRoute API 實際暴露的模型名稱一致
agents.defaults.model.primary預設主模型，格式必須是 provider/model-id
agents.defaults.model.fallbacks備選模型列表，主模型失敗時自動切換
agents.defaults.models可選，用來給模型起別名，方便在 UI 或會話裡引用

​
驗證是否接入成功

完成配置後，回到 Control UI 或重新打開： 
openclaw dashboard
如果你能在 OpenClaw 中正常發起對話，並且預設模型已經變成 mixroute/...，說明接入成功。你也可以使用： 
openclaw models list
確認 mixroute/ 前綴的模型已經出現在可選列表中。

​
常見問題

  • baseUrl 沒帶 /v1：這是最常見的接入錯誤之一。
  • 模型 ID 填錯：primary 和 fallbacks 必須與 models.providers.mixroute.models 裡的 id 對應。
  • 金鑰只在當前終端生效：如果 Gateway 以背景服務運行，請確保服務進程也能讀取 MIXROUTE_API_KEY。
  • 想前台排障：可使用官方前台運行方式 openclaw gateway --port 18789 觀察日誌與報錯。