> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixroute.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenClaw

> 安裝 OpenClaw、對接 MixRoute API，快速搭建自託管 AI 助手

## 專案介紹

OpenClaw 是一個開源、自託管的個人 AI 助手平台，將訊息應用連接到運行在你自己硬體上的 AI 代理。專為開發者和進階用戶設計，無需交出資料控制權即可擁有自主 AI 助手。

* **GitHub**：[https://github.com/openclaw/openclaw](https://github.com/openclaw/openclaw)
* **專案文檔**：[https://docs.openclaw.ai](https://docs.openclaw.ai/)
* **官方主頁**：[https://openclaw.ai](https://openclaw.ai/)

OpenClaw 完全開源，你可以在 [OpenClaw 的 GitHub 倉庫](https://github.com/openclaw/openclaw) 瀏覽原始碼、提交 Issue 或參與貢獻。本教程涵蓋安裝、配置，以及將 OpenClaw 對接 MixRoute API 的完整步驟。

## 🌟 核心特性

### 多管道整合

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

### 自託管與資料安全

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

### 智能代理能力

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

## 📦 接入前準備

<CardGroup cols={1}>
  <Card title="準備資訊" icon="list-check">
    * Node.js 22 或更高版本
    * 一個可用的 MixRoute API 位址（通常以 `/v1` 結尾）
    * 一個可用的 MixRoute API Key
  </Card>
</CardGroup>

在開始接入 MixRoute API 之前，建議先依照 OpenClaw 官方目前推薦流程把 Gateway 和 Control UI 跑起來。這樣後續排查問題時，更容易區分是 OpenClaw 本身未啟動，還是模型提供者配置有誤。

### 1. 安裝 OpenClaw（macOS/Linux）

```bash theme={null}
curl -fsSL https://openclaw.ai/install.sh | bash
```

其他安裝方式可參考 OpenClaw 官方文檔：[Getting Started](https://docs.openclaw.ai/start/getting-started)。

### 2. 運行引導精靈

```bash theme={null}
openclaw onboard --install-daemon
```

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

### 3. 檢查 Gateway 與 Control UI

```bash theme={null}
openclaw gateway status
```

```bash theme={null}
openclaw dashboard
```

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

### 4. 定位配置檔

OpenClaw 的配置檔通常位於 `~/.openclaw/openclaw.json`，你可以在引導精靈生成的基礎上繼續修改。

<Tip>
  如果你把 OpenClaw 跑在專用服務帳號下，或希望自訂配置/狀態目錄，可以使用環境變數 `OPENCLAW_CONFIG_PATH`、`OPENCLAW_STATE_DIR`、`OPENCLAW_HOME`。詳細說明見官方文檔：[Environment Variables](https://docs.openclaw.ai/help/environment)。
</Tip>

## 🚀 使用 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 金鑰：

```bash theme={null}
export MIXROUTE_API_KEY="sk-your-mixroute-key"
```

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

```json theme={null}
{
  "models": {
    "mode": "merge",
    "providers": {
      "mixroute": {
        "baseUrl": "https://api.mixroute.ai/v1",
        "apiKey": "${MIXROUTE_API_KEY}",
        "api": "openai-completions",
        "models": [
          { "id": "gemini-3.5-flash", "name": "Gemini 3.5 Flash" },
          { "id": "kimi-k2.7-code", "name": "Kimi K2.7 Code" }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "mixroute/gemini-3.5-flash",
        "fallbacks": ["mixroute/kimi-k2.7-code"]
      },
      "models": {
        "mixroute/gemini-3.5-flash": { "alias": "flash" },
        "mixroute/kimi-k2.7-code": { "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.apiKey`  | MixRoute 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 或重新打開：

```bash theme={null}
openclaw dashboard
```

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

```bash theme={null}
openclaw models list
```

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

### 常見問題

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