--- read_when: - 首次設定 OpenClaw - 尋找常見的設定模式 - 前往特定設定區段 summary: 設定概覽：常見工作、快速設定，以及完整參考的連結 title: 設定 x-i18n: generated_at: "2026-05-10T19:34:17Z" model: gpt-5.5 provider: openai source_hash: 023ce17d31ed16e061516a2026ac6c31fd8716548e230d27a7965b9a2d8c59c1 source_path: gateway/configuration.md workflow: 16 --- OpenClaw 會從 `~/.openclaw/openclaw.json` 讀取選用的 **JSON5** 設定。 作用中的設定路徑必須是一般檔案。OpenClaw 擁有的寫入不支援以符號連結形式配置的 `openclaw.json`； 原子寫入可能會取代該路徑，而不是保留符號連結。若你把設定保存在預設狀態目錄之外， 請將 `OPENCLAW_CONFIG_PATH` 直接指向真正的檔案。 如果檔案不存在，OpenClaw 會使用安全的預設值。新增設定的常見原因： - 連接頻道並控制誰可以傳訊息給機器人 - 設定模型、工具、沙盒或自動化（cron、hooks） - 調整工作階段、媒體、網路或 UI 請參閱[完整參考](/zh-TW/gateway/configuration-reference)了解所有可用欄位。 Agent 和自動化應在編輯設定前使用 `config.schema.lookup` 取得精確的欄位層級文件。 此頁面提供以任務為導向的指引；更完整的欄位地圖與預設值請參閱 [設定參考](/zh-TW/gateway/configuration-reference)。 **第一次設定？** 從 `openclaw onboard` 開始互動式設定，或查看 [設定範例](/zh-TW/gateway/configuration-examples)指南取得完整可複製貼上的設定。 ## 最小設定 ```json5 // ~/.openclaw/openclaw.json { agents: { defaults: { workspace: "~/.openclaw/workspace" } }, channels: { whatsapp: { allowFrom: ["+15555550123"] } }, } ``` ## 編輯設定 ```bash openclaw onboard # full onboarding flow openclaw configure # config wizard ``` ```bash openclaw config get agents.defaults.workspace openclaw config set agents.defaults.heartbeat.every "2h" openclaw config unset plugins.entries.brave.config.webSearch.apiKey ``` 開啟 [http://127.0.0.1:18789](http://127.0.0.1:18789)，並使用 **Config** 分頁。 Control UI 會根據即時設定 schema 轉譯表單，包含欄位 `title` / `description` 文件中繼資料，以及可用時的 Plugin 和頻道 schema， 並提供 **Raw JSON** 編輯器作為備用方式。對於深入檢視 UI 和其他工具， Gateway 也會公開 `config.schema.lookup`，用來取得一個以路徑為範圍的 schema 節點與其直接子項摘要。 直接編輯 `~/.openclaw/openclaw.json`。Gateway 會監看該檔案並自動套用變更（請參閱[熱重新載入](#config-hot-reload)）。 ## 嚴格驗證 OpenClaw 只接受完全符合 schema 的設定。未知鍵、格式錯誤的型別或無效值會導致 Gateway **拒絕啟動**。唯一的根層級例外是 `$schema`（字串），讓編輯器可以附加 JSON Schema 中繼資料。 `openclaw config schema` 會輸出 Control UI 與驗證使用的標準 JSON Schema。 `config.schema.lookup` 會為深入檢視工具取得單一以路徑為範圍的節點與子項摘要。 欄位 `title`/`description` 文件中繼資料會一路傳遞到巢狀物件、萬用字元 (`*`)、陣列項目 (`[]`) 以及 `anyOf`/ `oneOf`/`allOf` 分支。當 manifest registry 載入時，執行階段 Plugin 與頻道 schema 會合併進來。 驗證失敗時： - Gateway 不會啟動 - 只有診斷命令可用（`openclaw doctor`、`openclaw logs`、`openclaw health`、`openclaw status`） - 執行 `openclaw doctor` 查看確切問題 - 執行 `openclaw doctor --fix`（或 `--yes`）套用修復 Gateway 會在每次成功啟動後保留一份受信任的最後已知良好副本， 但啟動與熱重新載入不會自動還原它。如果 `openclaw.json` 驗證失敗（包含 Plugin 本地驗證），Gateway 啟動會失敗，或重新載入會被略過且目前執行階段會保留最後接受的設定。 執行 `openclaw doctor --fix`（或 `--yes`）以修復帶前綴/被覆寫的設定，或 還原最後已知良好副本。當候選設定包含已遮蔽的秘密佔位符，例如 `***` 時，會略過提升為最後已知良好。 ## 常見任務 每個頻道在 `channels.` 下都有自己的設定區段。設定步驟請參閱專屬頻道頁面： - [WhatsApp](/zh-TW/channels/whatsapp) - `channels.whatsapp` - [Telegram](/zh-TW/channels/telegram) - `channels.telegram` - [Discord](/zh-TW/channels/discord) - `channels.discord` - [Feishu](/zh-TW/channels/feishu) - `channels.feishu` - [Google Chat](/zh-TW/channels/googlechat) - `channels.googlechat` - [Microsoft Teams](/zh-TW/channels/msteams) - `channels.msteams` - [Slack](/zh-TW/channels/slack) - `channels.slack` - [Signal](/zh-TW/channels/signal) - `channels.signal` - [iMessage](/zh-TW/channels/imessage) - `channels.imessage` - [Mattermost](/zh-TW/channels/mattermost) - `channels.mattermost` 所有頻道共用相同的 DM 政策模式： ```json5 { channels: { telegram: { enabled: true, botToken: "123:abc", dmPolicy: "pairing", // pairing | allowlist | open | disabled allowFrom: ["tg:123"], // only for allowlist/open }, }, } ``` 設定主要模型與選用的備援模型： ```json5 { agents: { defaults: { model: { primary: "anthropic/claude-sonnet-4-6", fallbacks: ["openai/gpt-5.4"], }, models: { "anthropic/claude-sonnet-4-6": { alias: "Sonnet" }, "openai/gpt-5.4": { alias: "GPT" }, }, }, }, } ``` - `agents.defaults.models` 定義模型目錄，並作為 `/model` 的允許清單；`provider/*` 項目會將 `/model`、`/models` 和模型選擇器篩選到指定 provider，同時仍使用動態模型探索。 - 使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 新增允許清單項目，而不移除既有模型。除非傳入 `--replace`，否則會移除項目的純取代會被拒絕。 - 模型參照使用 `provider/model` 格式（例如 `anthropic/claude-opus-4-6`）。 - `agents.defaults.imageMaxDimensionPx` 控制 transcript/tool 圖片縮小（預設 `1200`）；較低的值通常會降低大量截圖執行中的 vision-token 使用量。 - 請參閱[模型 CLI](/zh-TW/concepts/models)了解如何在聊天中切換模型，並參閱[模型容錯移轉](/zh-TW/concepts/model-failover)了解授權輪替與備援行為。 - 自訂/自架 provider 請參閱參考中的[自訂 provider](/zh-TW/gateway/config-tools#custom-providers-and-base-urls)。 DM 存取權會透過 `dmPolicy` 依頻道控制： - `"pairing"`（預設）：未知傳送者會取得一次性配對碼以供核准 - `"allowlist"`：只允許 `allowFrom` 中的傳送者（或已配對允許儲存中的傳送者） - `"open"`：允許所有傳入 DM（需要 `allowFrom: ["*"]`） - `"disabled"`：忽略所有 DM 對於群組，請使用 `groupPolicy` + `groupAllowFrom` 或頻道專屬允許清單。 各頻道詳細資訊請參閱[完整參考](/zh-TW/gateway/config-channels#dm-and-group-access)。 群組訊息預設為**需要提及**。請為每個 Agent 設定觸發模式，並讓可見的聊天室回覆保持在預設 message-tool 路徑，除非你有意使用舊式自動最終回覆： ```json5 { messages: { visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere groupChat: { visibleReplies: "message_tool", // default; use "automatic" for legacy room replies }, }, agents: { list: [ { id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"], }, }, ], }, channels: { whatsapp: { groups: { "*": { requireMention: true } }, }, }, } ``` - **中繼資料提及**：原生 @-mentions（WhatsApp 點按提及、Telegram @bot 等） - **文字模式**：`mentionPatterns` 中的安全 regex 模式 - **可見回覆**：`messages.visibleReplies` 可以要求全域使用 message-tool 傳送；`messages.groupChat.visibleReplies` 會覆寫群組/頻道的設定。 - 可見回覆模式、各頻道覆寫與自我聊天模式請參閱[完整參考](/zh-TW/gateway/config-channels#group-chat-mention-gating)。 使用 `agents.defaults.skills` 作為共用基準，然後用 `agents.list[].skills` 覆寫特定 Agent： ```json5 { agents: { defaults: { skills: ["github", "weather"], }, list: [ { id: "writer" }, // inherits github, weather { id: "docs", skills: ["docs-search"] }, // replaces defaults { id: "locked-down", skills: [] }, // no skills ], }, } ``` - 省略 `agents.defaults.skills` 時，預設不限制 Skills。 - 省略 `agents.list[].skills` 時，會繼承預設值。 - 設定 `agents.list[].skills: []` 表示沒有 Skills。 - 請參閱 [Skills](/zh-TW/tools/skills)、[Skills 設定](/zh-TW/tools/skills-config)，以及 [設定參考](/zh-TW/gateway/config-agents#agents-defaults-skills)。 控制 gateway 對看似停滯的頻道進行重新啟動的積極程度： ```json5 { gateway: { channelHealthCheckMinutes: 5, channelStaleEventThresholdMinutes: 30, channelMaxRestartsPerHour: 10, }, channels: { telegram: { healthMonitor: { enabled: false }, accounts: { alerts: { healthMonitor: { enabled: true }, }, }, }, }, } ``` - 設定 `gateway.channelHealthCheckMinutes: 0` 可全域停用健康監控重新啟動。 - `channelStaleEventThresholdMinutes` 應大於或等於檢查間隔。 - 使用 `channels..healthMonitor.enabled` 或 `channels..accounts..healthMonitor.enabled`，可在不停用全域監控的情況下，停用單一頻道或帳號的自動重新啟動。 - 操作除錯請參閱[健康檢查](/zh-TW/gateway/health)，所有欄位請參閱[完整參考](/zh-TW/gateway/configuration-reference#gateway)。 在負載較高或低功耗主機上，給本機用戶端更多時間完成驗證前 WebSocket handshake： ```json5 { gateway: { handshakeTimeoutMs: 30000, }, } ``` - 預設值為 `15000` 毫秒。 - `OPENCLAW_HANDSHAKE_TIMEOUT_MS` 仍會優先用於一次性的服務或 shell 覆寫。 - 請優先修復啟動/事件迴圈停頓；此旋鈕適用於健康但暖機期間較慢的主機。 工作階段會控制對話連續性與隔離： ```json5 { session: { dmScope: "per-channel-peer", // recommended for multi-user threadBindings: { enabled: true, idleHours: 24, maxAgeHours: 0, }, reset: { mode: "daily", atHour: 4, idleMinutes: 120, }, }, } ``` - `dmScope`: `main`（共用）| `per-peer` | `per-channel-peer` | `per-account-channel-peer` - `threadBindings`：用於執行緒繫結工作階段路由的全域預設值（Discord 支援 `/focus`、`/unfocus`、`/agents`、`/session idle` 和 `/session max-age`）。 - 請參閱[工作階段管理](/zh-TW/concepts/session)，了解範圍設定、身分連結和傳送政策。 - 請參閱[完整參考](/zh-TW/gateway/config-agents#session)，了解所有欄位。 在隔離的沙箱執行階段中執行代理工作階段： ```json5 { agents: { defaults: { sandbox: { mode: "non-main", // off | non-main | all scope: "agent", // session | agent | shared }, }, }, } ``` 請先建置映像 - 若使用原始碼 checkout，請執行 `scripts/sandbox-setup.sh`；若使用 npm 安裝，請參閱[沙箱 § 映像與設定](/zh-TW/gateway/sandboxing#images-and-setup)中的內嵌 `docker build` 命令。 請參閱[沙箱](/zh-TW/gateway/sandboxing)以取得完整指南，並參閱[完整參考](/zh-TW/gateway/config-agents#agentsdefaultssandbox)了解所有選項。 relay 支援的推播在 `openclaw.json` 中設定。 在 Gateway 設定中設定： ```json5 { gateway: { push: { apns: { relay: { baseUrl: "https://relay.example.com", // Optional. Default: 10000 timeoutMs: 10000, }, }, }, }, } ``` 對應的 CLI： ```bash openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com ``` 這會做什麼： - 讓 Gateway 透過外部 relay 傳送 `push.test`、喚醒提示和重新連線喚醒。 - 使用由已配對 iOS App 轉送、以註冊為範圍的傳送授權。Gateway 不需要部署範圍的 relay token。 - 將每個 relay 支援的註冊繫結到 iOS App 配對的 Gateway 身分，因此另一個 Gateway 無法重用已儲存的註冊。 - 讓本機/手動 iOS 建置維持直接 APNs。relay 支援的傳送僅適用於透過 relay 註冊的官方發佈建置。 - 必須符合內建於官方/TestFlight iOS 建置的 relay base URL，讓註冊和傳送流量到達同一個 relay 部署。 端對端流程： 1. 安裝使用相同 relay base URL 編譯的官方/TestFlight iOS 建置。 2. 在 Gateway 上設定 `gateway.push.apns.relay.baseUrl`。 3. 將 iOS App 配對到 Gateway，並讓 node 與操作員工作階段都連線。 4. iOS App 擷取 Gateway 身分，使用 App Attest 加上 app receipt 向 relay 註冊，然後將 relay 支援的 `push.apns.register` payload 發佈到已配對的 Gateway。 5. Gateway 儲存 relay handle 和傳送授權，然後將它們用於 `push.test`、喚醒提示和重新連線喚醒。 操作注意事項： - 如果你將 iOS App 切換到不同的 Gateway，請重新連線 App，讓它可以發佈繫結到該 Gateway 的新 relay 註冊。 - 如果你發佈指向不同 relay 部署的新 iOS 建置，App 會重新整理其快取的 relay 註冊，而不是重用舊的 relay origin。 相容性注意事項： - `OPENCLAW_APNS_RELAY_BASE_URL` 和 `OPENCLAW_APNS_RELAY_TIMEOUT_MS` 仍可作為暫時的環境覆寫使用。 - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` 仍是僅限 loopback 的開發逃生口；不要在設定中保留 HTTP relay URL。 請參閱 [iOS App](/zh-TW/platforms/ios#relay-backed-push-for-official-builds) 了解端對端流程，並參閱[驗證與信任流程](/zh-TW/platforms/ios#authentication-and-trust-flow)了解 relay 安全模型。 ```json5 { agents: { defaults: { heartbeat: { every: "30m", target: "last", }, }, }, } ``` - `every`：期間字串（`30m`、`2h`）。設定為 `0m` 可停用。 - `target`：`last` | `none` | ``（例如 `discord`、`matrix`、`telegram` 或 `whatsapp`） - `directPolicy`：DM 風格 Heartbeat 目標使用 `allow`（預設）或 `block` - 請參閱 [Heartbeat](/zh-TW/gateway/heartbeat) 取得完整指南。 ```json5 { cron: { enabled: true, maxConcurrentRuns: 2, // cron dispatch + isolated cron agent-turn execution sessionRetention: "24h", runLog: { maxBytes: "2mb", keepLines: 2000, }, }, } ``` - `sessionRetention`：從 `sessions.json` 修剪已完成的隔離執行工作階段（預設 `24h`；設定 `false` 可停用）。 - `runLog`：依大小和保留行數修剪 `cron/runs/.jsonl`。 - 請參閱 [Cron 工作](/zh-TW/automation/cron-jobs)，了解功能概覽和 CLI 範例。 在 Gateway 上啟用 HTTP Webhook 端點： ```json5 { hooks: { enabled: true, token: "shared-secret", path: "/hooks", defaultSessionKey: "hook:ingress", allowRequestSessionKey: false, allowedSessionKeyPrefixes: ["hook:"], mappings: [ { match: { path: "gmail" }, action: "agent", agentId: "main", deliver: true, }, ], }, } ``` 安全性注意事項： - 將所有 hook/webhook payload 內容視為不受信任的輸入。 - 使用專用的 `hooks.token`；不要重用共用的 Gateway token。 - Hook 驗證僅限標頭（`Authorization: Bearer ...` 或 `x-openclaw-token`）；查詢字串 token 會被拒絕。 - `hooks.path` 不能是 `/`；請將 Webhook 入口保留在專用子路徑，例如 `/hooks`。 - 除非進行嚴格限定範圍的偵錯，否則請停用不安全內容繞過旗標（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`）。 - 如果啟用 `hooks.allowRequestSessionKey`，也請設定 `hooks.allowedSessionKeyPrefixes`，以限制呼叫者選取的工作階段金鑰。 - 對於 hook 驅動的代理，建議使用強大的現代模型層級和嚴格工具政策（例如僅限訊息傳遞，並在可能時加上沙箱）。 請參閱[完整參考](/zh-TW/gateway/configuration-reference#hooks)，了解所有 mapping 選項和 Gmail 整合。 使用獨立工作區和工作階段執行多個隔離代理： ```json5 { agents: { list: [ { id: "home", default: true, workspace: "~/.openclaw/workspace-home" }, { id: "work", workspace: "~/.openclaw/workspace-work" }, ], }, bindings: [ { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } }, { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } }, ], } ``` 請參閱[多代理](/zh-TW/concepts/multi-agent)和[完整參考](/zh-TW/gateway/config-agents#multi-agent-routing)，了解繫結規則和每代理存取設定檔。 使用 `$include` 組織大型設定： ```json5 // ~/.openclaw/openclaw.json { gateway: { port: 18789 }, agents: { $include: "./agents.json5" }, broadcast: { $include: ["./clients/a.json5", "./clients/b.json5"], }, } ``` - **單一檔案**：取代所屬物件 - **檔案陣列**：依序深度合併（後者優先） - **同層金鑰**：在 includes 之後合併（覆寫 included 值） - **巢狀 includes**：最多支援 10 層深度 - **相對路徑**：相對於執行 include 的檔案解析 - **OpenClaw 擁有的寫入**：當寫入只變更一個最上層區段，且該區段 由單一檔案 include 支援，例如 `plugins: { $include: "./plugins.json5" }`， OpenClaw 會更新該 included 檔案，並保持 `openclaw.json` 完整不變 - **不支援的寫入穿透**：root includes、include arrays，以及具有 同層覆寫的 includes，對 OpenClaw 擁有的寫入會以失敗關閉處理，而不是 攤平成設定 - **限制範圍**：`$include` 路徑必須解析到保存 `openclaw.json` 的目錄下。若要在多台機器或多個使用者之間共用樹狀結構，請將 `OPENCLAW_INCLUDE_ROOTS` 設為額外目錄的路徑清單（POSIX 上為 `:`，Windows 上為 `;`）， includes 可參照這些目錄。符號連結會被解析並重新檢查，因此如果路徑在字面上位於設定目錄中， 但其真實目標逃逸出每個允許的 root，仍會被拒絕。 - **錯誤處理**：針對缺少檔案、解析錯誤和循環 includes 提供清楚錯誤 ## 設定熱重新載入 Gateway 會監看 `~/.openclaw/openclaw.json` 並自動套用變更 - 大多數設定不需要手動重新啟動。 直接檔案編輯在驗證前會被視為不受信任。監看器會等待 編輯器暫存寫入/重新命名的變動穩定，讀取最終檔案，並拒絕 無效的外部編輯，不會重寫 `openclaw.json`。OpenClaw 擁有的設定 寫入會在寫入前使用相同 schema gate；破壞性覆寫，例如 移除 `gateway.mode` 或將檔案縮小超過一半，會被拒絕並 儲存為 `.rejected.*` 以供檢查。 如果你看到 `config reload skipped (invalid config)`，或啟動回報 `Invalid config`，請檢查設定、執行 `openclaw config validate`，然後執行 `openclaw doctor --fix` 進行修復。請參閱 [Gateway 疑難排解](/zh-TW/gateway/troubleshooting#gateway-rejected-invalid-config) 取得檢查清單。 ### 重新載入模式 | 模式 | 行為 | | ---------------------- | --------------------------------------------------------------------------------------- | | **`hybrid`**（預設） | 立即熱套用安全變更。對關鍵變更自動重新啟動。 | | **`hot`** | 只熱套用安全變更。需要重新啟動時記錄警告 - 由你處理。 | | **`restart`** | 任何設定變更都會重新啟動 Gateway，無論是否安全。 | | **`off`** | 停用檔案監看。變更會在下次手動重新啟動時生效。 | ```json5 { gateway: { reload: { mode: "hybrid", debounceMs: 300 }, }, } ``` ### 什麼會熱套用，什麼需要重新啟動 大多數欄位都會在不中斷服務的情況下熱套用。在 `hybrid` 模式中，需要重新啟動的變更會自動處理。 | 類別 | 欄位 | 需要重新啟動？ | | ------------------- | ----------------------------------------------------------------- | --------------- | | 頻道 | `channels.*`、`web`（WhatsApp）- 所有內建和 Plugin 頻道 | 否 | | 代理與模型 | `agent`、`agents`、`models`、`routing` | 否 | | 自動化 | `hooks`、`cron`、`agent.heartbeat` | 否 | | 工作階段與訊息 | `session`、`messages` | 否 | | 工具與媒體 | `tools`、`browser`、`skills`、`mcp`、`audio`、`talk` | 否 | | UI 與其他 | `ui`、`logging`、`identity`、`bindings` | 否 | | Gateway 伺服器 | `gateway.*`（port、bind、auth、tailscale、TLS、HTTP） | **是** | | 基礎架構 | `discovery`、`plugins` | **是** | `gateway.reload` 和 `gateway.remote` 是例外 - 變更它們**不會**觸發重新啟動。 ### 重新載入規劃 當你編輯透過 `$include` 參照的來源檔案時，OpenClaw 會從來源撰寫的版面規劃 重新載入，而不是從展平後的記憶體內視圖規劃。 這讓熱重載決策（熱套用或重新啟動）保持可預測，即使單一頂層區段 位於自己的 include 檔案中，例如 `plugins: { $include: "./plugins.json5" }`。如果來源版面不明確，重新載入規劃會保守失敗。 ## Config RPC（程式化更新） 對於透過 gateway API 寫入 config 的工具，建議使用此流程： - `config.schema.lookup` 用於檢查一個子樹（淺層 schema 節點 + 子項摘要） - `config.get` 用於擷取目前快照與 `hash` - `config.patch` 用於部分更新（JSON merge patch：物件合併、`null` 刪除、陣列取代） - 只有當你打算取代整個 config 時才使用 `config.apply` - `update.run` 用於明確自我更新並重新啟動；當重新啟動後的工作階段應執行一個後續回合時，請包含 `continuationMessage` - `update.status` 用於檢查最新的更新重新啟動 sentinel，並在重新啟動後驗證執行中的版本 Agent 應將 `config.schema.lookup` 視為取得精確欄位層級文件與限制的第一站。 當需要更廣泛的 config 對照表、預設值或專屬子系統參考連結時，請使用 [Configuration reference](/zh-TW/gateway/configuration-reference)。 控制平面寫入（`config.apply`、`config.patch`、`update.run`）會依 `deviceId+clientIp` 限制為每 60 秒 3 個請求。重新啟動請求會合併，接著在重新啟動週期之間強制執行 30 秒冷卻時間。 `update.status` 是唯讀的，但屬於 admin 範圍，因為重新啟動 sentinel 可能包含更新步驟摘要與命令輸出尾端。 部分 patch 範例： ```bash openclaw gateway call config.get --params '{}' # capture payload.hash openclaw gateway call config.patch --params '{ "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }", "baseHash": "" }' ``` `config.apply` 和 `config.patch` 都接受 `raw`、`baseHash`、`sessionKey`、 `note` 和 `restartDelayMs`。當 config 已存在時，兩個方法都需要 `baseHash`。 ## 環境變數 OpenClaw 會從父程序加上下列來源讀取 env var： - 目前工作目錄中的 `.env`（如果存在） - `~/.openclaw/.env`（全域 fallback） 這兩個檔案都不會覆寫既有 env var。你也可以在 config 中設定 inline env var： ```json5 { env: { OPENROUTER_API_KEY: "sk-or-...", vars: { GROQ_API_KEY: "gsk-..." }, }, } ``` 如果啟用且預期的 key 尚未設定，OpenClaw 會執行你的登入 shell，並只匯入缺少的 key： ```json5 { env: { shellEnv: { enabled: true, timeoutMs: 15000 }, }, } ``` 對應的 env var：`OPENCLAW_LOAD_SHELL_ENV=1` 使用 `${VAR_NAME}` 在任何 config 字串值中參照 env var： ```json5 { gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } }, models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } }, } ``` 規則： - 只匹配大寫名稱：`[A-Z_][A-Z0-9_]*` - 缺少或空白的 var 會在載入時擲出錯誤 - 使用 `$${VAR}` 逸出以輸出字面值 - 可在 `$include` 檔案內運作 - Inline 替換：`"${BASE}/v1"` → `"https://api.example.com/v1"` 對於支援 SecretRef 物件的欄位，你可以使用： ```json5 { models: { providers: { openai: { apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" } }, }, }, skills: { entries: { "image-lab": { apiKey: { source: "file", provider: "filemain", id: "/skills/entries/image-lab/apiKey", }, }, }, }, channels: { googlechat: { serviceAccountRef: { source: "exec", provider: "vault", id: "channels/googlechat/serviceAccount", }, }, }, } ``` SecretRef 詳細資訊（包含 `env`/`file`/`exec` 的 `secrets.providers`）位於 [Secrets Management](/zh-TW/gateway/secrets)。 支援的憑證路徑列於 [SecretRef Credential Surface](/zh-TW/reference/secretref-credential-surface)。 完整優先順序與來源請參閱 [Environment](/zh-TW/help/environment)。 ## 完整參考 如需完整逐欄位參考，請參閱 **[Configuration Reference](/zh-TW/gateway/configuration-reference)**。 --- _相關：[Configuration Examples](/zh-TW/gateway/configuration-examples) · [Configuration Reference](/zh-TW/gateway/configuration-reference) · [Doctor](/zh-TW/gateway/doctor)_ ## 相關 - [Configuration reference](/zh-TW/gateway/configuration-reference) - [Configuration examples](/zh-TW/gateway/configuration-examples) - [Gateway runbook](/zh-TW/gateway)