OpenClaw - 自托管 AI 智能助手平台

OpenClaw 完全開源，你可以在 OpenClaw 的 GitHub 倉庫 瀏覽源码、提交 Issue 或參與貢獻。本教程涵蓋安裝、設定，以及將 OpenClaw 對接 CoffeeRouter 的完整步驟。

🌟 核心特性

多渠道集成

• 多渠道集成：支援 Telegram、Discord、WhatsApp、iMessage 等多種消息渠道，也可通過插件擴展更多平台
• 單一網關：通過一個 Gateway 進程統一管理所有渠道
• 語音支援：支援 macOS/iOS/Android 語音交互
• Canvas 界面：可渲染交互式 Canvas 界面

自托管與數據安全

• 完全自托管：執行在你自己的機器或伺服器上
• 開源透明：MIT 開源協議，程式碼完全透明
• 數據本地化：上下文和技能存儲在你的本地計算機，而非雲端

智能代理能力

• 持續執行：支援後台常駐執行，擁有持久記憶
• 計劃任務：支援 cron 定時任務
• 會話隔离：按代理/工作區/發送者隔离會話
• 多代理路由：支援多代理協同工作
• 工具調用：原生支援工具調用和程式碼執行

📦 接入前准備

在開始接入 CoffeeRouter 之前，建議先按 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 跑起來，後面再把預設模型切到 CoffeeRouter。

3. 檢查 Gateway 與 Control UI

openclaw gateway status

openclaw dashboard

如果瀏覽器能打開 Control UI，說明 OpenClaw 基礎執行已經正常。這個階段不需要先設定 Telegram、Discord、飛書等消息渠道。

4. 定位設定檔案

OpenClaw 的設定檔案通常位於 ~/.openclaw/openclaw.json，你可以在引導向導生成的基礎上繼續修改。

🚀 使用 CoffeeRouter 作為模型提供商

OpenClaw 支援通過 models.providers 接入自定義或兼容 OpenAI 介面的模型網關。對於 CoffeeRouter，最常見的做法是把它作為一個自定義 provider 加進設定裡，再把預設模型指向 coffeerouter/模型ID。

接入思路

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

推薦做法：用環境變量保存密鑰

先在目前 shell、服務環境，或 OpenClaw 可讀取的 .env 中提供你的 CoffeeRouter 密鑰：

export COFFEEROUTER_API_KEY="sk-your-coffeerouter-key"

然後在 openclaw.json 裡補充或修改以下片段：

{
  models: {
    mode: "merge",
    providers: {
      coffeerouter: {
        baseUrl: "https://<your-coffeerouter-domain>/v1",
        apiKey: "${COFFEEROUTER_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: "coffeerouter/gemini-2.5-flash",
        fallbacks: ["coffeerouter/kimi-k2.5"],
      },
      models: {
        "coffeerouter/gemini-2.5-flash": { alias: "flash" },
        "coffeerouter/kimi-k2.5": { alias: "kimi" },
      },
    },
  },
}

這不是一份必須原樣照抄的完整設定，而是接入 CoffeeRouter 最關鍵的部分。只要 provider、模型 ID 和預設模型引用對應正確，OpenClaw 就能通過 CoffeeRouter 調用你暴露出來的模型資源。

關鍵設定說明

設定項	說明
models.mode	建議設為 merge，在保留 OpenClaw 內置 provider 的同時追加 coffeerouter
models.providers.coffeerouter.baseUrl	你的 CoffeeRouter 地址，通常需要帶上 /v1
models.providers.coffeerouter.apiKey	CoffeeRouter 密鑰，推薦通過 ${COFFEEROUTER_API_KEY} 注入
models.providers.coffeerouter.api	對於 CoffeeRouter 這類 OpenAI 兼容網關，使用 openai-completions
models.providers.coffeerouter.models	這裡列出的模型 ID 必須與你的 CoffeeRouter 實際暴露的模型名稱一致
agents.defaults.model.primary	預設主模型，格式必須是 provider/model-id
agents.defaults.model.fallbacks	備選模型列表，主模型失敗時自動切換
agents.defaults.models	可選，用來給模型起別名，方便在 UI 或會話裡引用

驗證是否接入成功

完成設定後，回到 Control UI 或重新打開：

openclaw dashboard

如果你能在 OpenClaw 中正常發起對話，并且預設模型已經變成 coffeerouter/...，說明接入成功。你也可以使用：

openclaw models list

確認 coffeerouter/ 前綴的模型已經出現在可選列表中。

常見問題

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