---
title: "理解配置結構"
description: "理解 OpenClaw 配置結構：openclaw.json、JSON5、strict schema、熱載入、last-known-good、環境變數和金鑰邊界。"
verifiedAt: "2026-05-06"
---

OpenClaw 的主配置檔案是 `~/.openclaw/openclaw.json`。它不是“所有欄位都填滿才專業”的大表，而是 Gateway、Agent、Channel、tools、models、sandbox、automation 的執行契約。

> [!NOTE]
> **這一章用 13 分鐘換什麼**：你會知道什麼時候該用 onboarding、Control UI、`openclaw config set`、直接編輯檔案；也會知道配置壞了為什麼 Gateway 會拒絕啟動，而不是“先湊合跑”。

## 1. 先把配置理解成執行契約

`openclaw.json` 管的不是一個功能，而是多組邊界：


- Agent：workspace、skills、模型、bootstrap、sandbox。
- Channel：WhatsApp、Telegram、Discord、Slack 等入口。
- Session：不同人、不同群、不同賬號的上下文隔離。
- Tools 和 plugins：Agent 能呼叫哪些能力。
- Gateway：埠、認證、Control UI、日誌、熱載入。
- Automation：heartbeat、cron、hooks。

如果檔案不存在，OpenClaw 會使用 safe defaults（安全預設值）。真正需要配置，通常是因為你要接渠道、控訪問、設模型、開 sandbox、調 session 或加自動化。

```mermaid
flowchart TD
    Config["openclaw.json"]
    Gateway["Gateway 基礎設施"]
    Agent["Agent 工作單元"]
    Channel["Channel 訊息入口"]
    Tools["Tools / Plugins"]
    Automation["Automation"]
    Security["訪問與金鑰邊界"]

    Config --> Gateway
    Config --> Agent
    Config --> Channel
    Config --> Tools
    Config --> Automation
    Config --> Security

    style Config fill:#e0f2fe,stroke:#0284c7,stroke-width:2px
    style Security fill:#fee2e2,stroke:#ef4444,stroke-width:2px
    style Agent fill:#dcfce7,stroke:#22c55e,stroke-width:2px
```

> [!IMPORTANT]
> **最小配置不是空配置的反面**：最小配置只表達當前需要的意圖。每多一個欄位，就多一個排障點和安全邊界。

## 2. `openclaw.json` 必須是真實檔案

官方最新配置文件特別強調：active config path 必須是 regular file（普通檔案）。把 `~/.openclaw/openclaw.json` 做成 symlink（符號連結）不適合 OpenClaw 自己寫配置，因為 atomic write（原子寫入）可能替換路徑，而不是保留 symlink。

如果你把配置放在預設狀態目錄之外，應該用：

```bash
OPENCLAW_CONFIG_PATH=/path/to/real/openclaw.json
```

| 做法 | 結果 |
|------|------|
| 預設 `~/.openclaw/openclaw.json` | 新手首選，最少出錯 |
| `OPENCLAW_CONFIG_PATH` 指向真實檔案 | 適合多例項或服務化部署 |
| symlink 到其他位置 | 不推薦，OpenClaw-owned writes 可能替換連結 |

> [!WARNING]
> **不要把同步系統放在配置寫入路徑中間**：如果你想跨機器同步配置，先搞清誰負責寫檔案、誰負責同步、誰負責回復。入門階段先用預設路徑。

## 3. 新手怎麼改配置

官方提供幾種入口：`openclaw onboard`、`openclaw configure`、`openclaw config get/set/unset`、Control UI，以及直接編輯檔案。

推薦順序：

1. 第一次用 onboarding。
2. 小改動用 `openclaw config set`。
3. 想看結構用 Control UI。
4. 需要查欄位約束時用 `openclaw config schema` 或 `config.schema.lookup`。
5. 已經理解 schema 時再直接編輯 JSON5。

```bash
openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset plugins.entries.brave.config.webSearch.apiKey
```

Control UI 會從 live config schema 渲染表單，還能顯示欄位 `title` / `description` 等 docs metadata。對 Agent 或自動化工具來說，`config.schema.lookup` 是寫配置前的第一站。

## 4. strict schema 不是限制，是保護

OpenClaw 只接受完全匹配 schema 的配置。未知欄位、型別錯誤、非法值都會讓 Gateway 拒絕啟動；根級例外只有 `$schema` 字串，方便編輯器掛 JSON Schema metadata。

這聽起來嚴格，但對一個能呼叫工具、接訊息、處理金鑰的系統來說，這是保護。

| 配置錯誤 | OpenClaw 的處理 |
|------|------|
| 未知欄位 | 拒絕啟動或拒絕 reload |
| 型別不對 | 拒絕啟動或拒絕 reload |
| plugin-local validation 失敗 | reload 跳過，當前 runtime 保持最後一次接受的配置 |
| 明顯 destructive clobber | 儲存為 `.rejected.*` 供檢查 |
| redacted secret 示例值參與候選 | 不提升為 last-known-good |

配置校驗失敗時，優先跑：

```bash
openclaw doctor
openclaw config validate
openclaw doctor --fix
```

> [!TIP]
> **last-known-good 不是自動魔法**：Gateway 會保留成功啟動後的可信副本，但啟動和熱載入失敗時不會無腦自動恢復。你仍然要看診斷，再決定是否用 `doctor --fix` 修復或恢復。

## 5. 最小配置只表達最小意圖

官方最小例子通常表達兩個核心意圖：給 Agent 一個 workspace，給某個 channel 一個受控入口。

```json5
{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
  },
  channels: {
    telegram: {
      enabled: true,
      botToken: "${TELEGRAM_BOT_TOKEN}",
      dmPolicy: "pairing",
    },
  },
}
```

這不是“推薦照抄上線”的完整配置。真實使用時，你還要根據平臺文件配置 token、allowlist、DM policy、群組策略、session、tools 和模型。

新手每次改配置前先問：

- 我接的是哪個渠道。
- 誰可以發訊息給它。
- 群組是否必須 mention。
- Agent 在哪個 workspace 工作。
- 這個入口能用哪些 tools 和 skills。
- 這次改動能不能單獨驗證。

## 6. 熱載入和重啟怎麼理解

Gateway 會監聽 `openclaw.json`，很多配置可以自動應用。預設 reload mode 是 `hybrid`：安全改動熱應用，關鍵基礎設施改動自動重啟。

| 型別 | 示例 | 是否通常需要重啟 |
|------|------|------|
| 業務配置 | channels、agents、models、hooks、cron、heartbeat、session、tools、skills | 否 |
| Gateway 入口 | port、bind、auth、TLS、HTTP server | 是 |
| 基礎設施 | discovery、canvasHost、plugins | 是 |
| reload / remote 自身 | `gateway.reload`、`gateway.remote` | 特殊例外 |

常見 reload mode：

| 模式 | 行為 |
|------|------|
| `hybrid` | 預設；安全改動熱應用，關鍵改動自動重啟 |
| `hot` | 只熱應用安全改動；需要重啟時只記錄 warning |
| `restart` | 任意配置變化都重啟 Gateway |
| `off` | 不監聽檔案變化，下次手動重啟生效 |

新手只要記住：儲存檔案不等於已經生效。要看 logs、health、doctor 和 Gateway 狀態。

## 7. 金鑰不要寫進公開配置

OpenClaw 會讀取父程序環境變數，也會讀取當前工作目錄 `.env` 和 `~/.openclaw/.env`。這些檔案不會覆蓋已經存在的環境變數。

配置字串裡可以引用環境變數：

```json5
{
  gateway: {
    auth: {
      token: "${OPENCLAW_GATEWAY_TOKEN}",
    },
  },
}
```

但環境變數引用不是加密。涉及 token、API key、Gateway auth、模型 key、OAuth 時，不要把明文寫進教程倉、公開 workspace 或截圖裡。

| 內容 | 該放哪裡 |
|------|------|
| 示例欄位結構 | 公開文件可以寫 |
| 假佔位符 | 公開文件可以寫 |
| 真 API key / token | 環境變數、私有憑據或 `~/.openclaw/` |
| OAuth / auth profiles / sessions | 不進 workspace git，不進公開倉 |

> [!CAUTION]
> **金鑰缺失導致啟動失敗通常是好事**：不要為了“先跑起來”把空 key 或真 key 隨便寫進公開配置。失敗比洩露更容易修。

## 8. 配置壞了先做什麼

配置壞了不要先刪檔案重來。官方診斷入口包括 doctor、logs、health、status、config validate。

推薦排障順序：

1. 看 Gateway 是否還能啟動診斷命令。
2. 執行 `openclaw config validate`。
3. 執行 `openclaw doctor`。
4. 看日誌裡具體 schema path。
5. 需要自動修復時再跑 `openclaw doctor --fix`。
6. 回復最近一次配置改動。
7. 只修一個欄位，再驗證。

如果你一次改了十個欄位，就很難判斷真正壞在哪裡。

```mermaid
flowchart TD
    Broken["配置出錯"]
    Validate["openclaw config validate"]
    Doctor["openclaw doctor"]
    Logs["openclaw logs"]
    Fix["openclaw doctor --fix"]
    Small["只修一個欄位"]
    Status["openclaw gateway status"]

    Broken --> Validate
    Validate --> Doctor
    Doctor --> Logs
    Logs --> Fix
    Fix --> Small
    Small --> Status

    style Broken fill:#fee2e2,stroke:#ef4444,stroke-width:2px
    style Small fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
    style Status fill:#dcfce7,stroke:#22c55e,stroke-width:2px
```

## 9. 新手常見坑

- 直接複製完整配置，裡面的欄位自己並不理解。
- 把配置檔案做成 symlink，又讓 OpenClaw 自己寫配置。
- 把明文金鑰放進 `openclaw.json`。
- 以為 workspace 是安全沙箱。
- 配置 `open` 入口後沒有 session 和 tools 限制。
- 儲存檔案後不看 reload 日誌。
- 一次改十幾個欄位，導致診斷沒有錨點。

## 10. 怎麼判斷配置健康

健康標準：

- `openclaw doctor` 沒有關鍵配置錯誤。
- `openclaw health` 能反映 Gateway 當前狀態。
- 每個 channel 都有明確訪問控制。
- 每個 Agent 都有明確 workspace。
- 金鑰來自環境變數或安全憑據，不在公開檔案裡。
- 改動範圍小，能透過日誌解釋為什麼生效。

配置的目標是讓 OpenClaw 可執行、可審計、可恢復，而不是把所有欄位填滿。

> [!TIP]
> **穩定配置靠“一改一驗”**：每次只改一個意圖，立刻跑 validate、doctor 或 health；不要把 channel、Agent、模型和遠端訪問混在一次提交裡。

## 11. 本章自檢

1. 為什麼不建議把 `openclaw.json` 做成 symlink？
2. strict schema 校驗失敗時，Gateway 會怎麼處理？
3. 哪些配置通常熱載入，哪些通常需要重啟？

> [!IMPORTANT]
> **過關標準**：你能用一句話說清 —— “OpenClaw 配置不是越多越好，而是用 schema、熱載入和診斷命令把執行邊界變得可驗證。”

## 12. 接下來去哪

<Cards>
  <Card href="/zh-Hant/docs/openclaw/official/00-getting-started/workspace" title="配置 Agent Workspace" description="配置檔案講執行契約，workspace 講 Agent 長期工作現場。" />
  <Card href="/zh-Hant/docs/openclaw/official/01-gateway-runtime/gateway-configuration" title="Gateway 配置" description="繼續深入 reload、health、doctor 和 Gateway 自身配置。" />
  <Card href="/zh-Hant/docs/openclaw/official/01-gateway-runtime/agents" title="Agent 配置" description="繼續看 workspace、repoRoot、skills allowlist、agentDir 和多 Agent 路由邊界。" />
</Cards>

## 13. 官方資料

- [Configuration](https://docs.openclaw.ai/gateway/configuration)
- [Configuration reference](https://docs.openclaw.ai/gateway/configuration-reference)
- [Configuration examples](https://docs.openclaw.ai/gateway/configuration-examples)
- [Secrets management](https://docs.openclaw.ai/gateway/secrets)
- [Environment variables](https://docs.openclaw.ai/help/environment)
