設定

每個頻道在 `channels.<provider>` 下有自己的設定區段。各頻道的設定步驟請參閱專屬頁面：

- [WhatsApp](/docs/channels/whatsapp) — `channels.whatsapp`
- [Telegram](/docs/channels/telegram) — `channels.telegram`
- [Discord](/docs/channels/discord) — `channels.discord`
- [Slack](/docs/channels/slack) — `channels.slack`
- [Signal](/docs/channels/signal) — `channels.signal`
- [iMessage](/docs/channels/imessage) — `channels.imessage`
- [Google Chat](/docs/channels/googlechat) — `channels.googlechat`
- [Mattermost](/docs/channels/mattermost) — `channels.mattermost`
- [MS Teams](/docs/channels/msteams) — `channels.msteams`

所有頻道共用相同的 DM 策略模式：

```json5
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // 僅用於 allowlist/open
    },
  },
}
```

設定主要模型和可選的備援：

```json5
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"],
      },
      models: {
        "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
        "openai/gpt-5.2": { alias: "GPT" },
      },
    },
  },
}
```

- `agents.defaults.models` 定義模型目錄，同時也是 `/model` 的白名單。
- Model ref 使用 `provider/model` 格式（例如 `anthropic/claude-opus-4-6`）。
- `agents.defaults.imageMaxDimensionPx` 控制 transcript/工具圖片的降尺寸（預設 `1200`）；較低值通常能減少截圖密集場景的 vision token 用量。
- 參閱 [Models CLI](/docs/concepts/models) 了解在對話中切換模型，以及 [Model Failover](/docs/concepts/model-failover) 了解驗證輪替和備援行為。
- 自訂或自建提供者請參閱設定參考中的[自訂提供者](/docs/gateway/configuration-reference#custom-providers-and-base-urls)。

DM 存取由各頻道的 `dmPolicy` 控制：

- `"pairing"`（預設）：未知發送者會收到一次性配對碼等待核准
- `"allowlist"`：只有 `allowFrom`（或已配對的允許儲存）中的發送者
- `"open"`：允許所有 DM（需要 `allowFrom: ["*"]`）
- `"disabled"`：忽略所有 DM

群組用 `groupPolicy` + `groupAllowFrom` 或頻道專屬的白名單。

更多細節請參閱[完整參考](/docs/gateway/configuration-reference#dm-and-group-access)。

群組訊息預設**需要 mention**。可按 agent 設定 mention 模式：

```json5
{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}
```

- **Metadata mentions**：平台原生 @mention（WhatsApp 點選 mention、Telegram @bot 等）
- **文字模式**：`mentionPatterns` 中的 regex 模式
- 參閱[完整參考](/docs/gateway/configuration-reference#group-chat-mention-gating)了解 per-channel 覆寫和自聊模式。

Sessions 控制對話的連續性和隔離：

```json5
{
  session: {
    dmScope: "per-channel-peer",  // 建議用於多使用者
    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`：thread 綁定 session 路由的全域預設值（Discord 支援 `/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）。
- 參閱 [Session 管理](/docs/concepts/session) 了解範圍、身份連結和發送策略。
- 參閱[完整參考](/docs/gateway/configuration-reference#session)了解所有欄位。

在隔離的 Docker 容器中執行 agent sessions：

```json5
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}
```

先建置映像檔：`scripts/sandbox-setup.sh`

參閱 [沙箱](/docs/gateway/sandboxing) 取得完整指南，以及[完整參考](/docs/gateway/configuration-reference#sandbox)了解所有選項。

Relay 推播在 `openclaw.json` 中設定。

在 gateway 設定中加入：

```json5
{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          // 可選。預設：10000
          timeoutMs: 10000,
        },
      },
    },
  },
}
```

CLI 等效指令：

```bash
openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com
```

這個設定的作用：

- 讓 gateway 可以透過外部 relay 發送 `push.test`、喚醒通知和重連喚醒。
- 使用由配對的 iOS app 轉發的 registration 範圍發送授權。Gateway 不需要全域 relay token。
- 將每個 relay 註冊綁定到 iOS app 配對的 gateway 身份，其他 gateway 無法重用已存的註冊。
- 本地/手動 iOS 版本繼續使用直接 APNs。Relay 推播只適用於透過 relay 註冊的官方分發版本。
- 必須與官方/TestFlight iOS 版本編譯時內嵌的 relay base URL 一致。

端到端流程：

1. 安裝使用相同 relay base URL 編譯的官方/TestFlight iOS 版本。
2. 在 gateway 上設定 `gateway.push.apns.relay.baseUrl`。
3. 將 iOS app 與 gateway 配對，讓 node 和 operator sessions 都連線。
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 來源。

相容性說明：

- `OPENCLAW_APNS_RELAY_BASE_URL` 和 `OPENCLAW_APNS_RELAY_TIMEOUT_MS` 仍可作為臨時環境變數覆寫。
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` 仍是僅限 loopback 的開發用 escape hatch；不要在設定中持久化 HTTP relay URL。

參閱 [iOS App](/docs/platforms/ios#relay-backed-push-for-official-builds) 了解端到端流程，以及 [驗證與信任流程](/docs/platforms/ios#authentication-and-trust-flow) 了解 relay 安全模型。

```json5
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}
```

- `every`：duration 字串（`30m`、`2h`）。設 `0m` 停用。
- `target`：`last` | `whatsapp` | `telegram` | `discord` | `none`
- `directPolicy`：`allow`（預設）或 `block`——控制 DM 型心跳目標
- 參閱 [心跳](/docs/gateway/heartbeat) 取得完整指南。

```json5
{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}
```

- `sessionRetention`：從 `sessions.json` 清除已完成的隔離 cron 執行 session（預設 `24h`；設 `false` 停用）。
- `runLog`：按大小和保留行數清理 `cron/runs/<jobId>.jsonl`。
- 參閱 [Cron 工作](/docs/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 內容都應視為不受信任的輸入。
- 除非做精確範圍的除錯，否則不要啟用 unsafe-content bypass flag（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`）。
- hook 驅動的 agent 建議使用較強的現代模型層級和嚴格的工具策略（例如僅訊息加上沙箱）。

參閱[完整參考](/docs/gateway/configuration-reference#hooks)了解所有 mapping 選項和 Gmail 整合。

在一個 Gateway 中運行多個隔離的 agent：

```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" } },
  ],
}
```

參閱 [Multi-Agent](/docs/concepts/multi-agent) 和[完整參考](/docs/gateway/configuration-reference#multi-agent-routing)了解綁定規則和 per-agent 存取 profile。

用 `$include` 組織大型設定：

```json5
// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/a.json5", "./clients/b.json5"],
  },
}
```

- **單一檔案**：取代包含它的物件
- **檔案陣列**：按順序深度合併（後者優先）
- **同層鍵**：在 include 之後合併（覆寫 include 的值）
- **巢狀 include**：支援最多 10 層深度
- **相對路徑**：相對於包含它的檔案解析
- **錯誤處理**：缺失檔案、解析錯誤和循環 include 都有清楚的錯誤訊息

驗證 + 寫入完整設定並在一步內重啟 Gateway。

> **警告：** `config.apply` 會取代**整個設定**。部分更新請用 `config.patch`，單一鍵用 `openclaw config set`。

參數：

- `raw`（字串）— 完整設定的 JSON5 payload
- `baseHash`（可選）— 來自 `config.get` 的設定 hash（設定已存在時必填）
- `sessionKey`（可選）— 重啟後喚醒 ping 的 session key
- `note`（可選）— 重啟哨兵的備註
- `restartDelayMs`（可選）— 重啟前的延遲（預設 2000）

重啟請求在已有待處理/進行中的重啟時會合併，重啟週期間有 30 秒的冷卻期。

```bash
openclaw gateway call config.get --params '{}'  # 記下 payload.hash
openclaw gateway call config.apply --params '{
  "raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }",
  "baseHash": "<hash>",
  "sessionKey": "agent:main:whatsapp:direct:+15555550123"
}'
```

將部分更新合併到現有設定中（JSON merge patch 語義）：

- 物件遞迴合併
- `null` 刪除鍵
- 陣列整個取代

參數：

- `raw`（字串）— 只包含要變更的鍵的 JSON5
- `baseHash`（必填）— 來自 `config.get` 的設定 hash
- `sessionKey`、`note`、`restartDelayMs` — 同 `config.apply`

重啟行為同 `config.apply`：待處理的重啟會合併，重啟週期間有 30 秒冷卻期。

```bash
openclaw gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
  "baseHash": "<hash>"
}'
```

如果啟用且預期的鍵沒有設定，OpenClaw 會執行你的登入 shell 並只匯入缺少的鍵：

{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}

環境變數等效：OPENCLAW_LOAD_SHELL_ENV=1

在任何設定字串值中用 ${VAR_NAME} 引用環境變數：

{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}

規則：

• 只匹配大寫名稱：[A-Z_][A-Z0-9_]*
• 缺失或空白的變數在載入時拋出錯誤
• 用 $${VAR} 跳脫得到字面值
• 在 $include 檔案中也有效
• 行內替換："${BASE}/v1" → "https://api.example.com/v1"

對於支援 SecretRef 物件的欄位，你可以使用：

{
  models: {
    providers: {
      openai: { apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" } },
    },
  },
  skills: {
    entries: {
      "nano-banana-pro": {
        apiKey: {
          source: "file",
          provider: "filemain",
          id: "/skills/entries/nano-banana-pro/apiKey",
        },
      },
    },
  },
  channels: {
    googlechat: {
      serviceAccountRef: {
        source: "exec",
        provider: "vault",
        id: "channels/googlechat/serviceAccount",
      },
    },
  },
}

SecretRef 的細節（包括 secrets.providers 的 env/file/exec）請參閱 Secrets 管理。 支援的憑證路徑列表請參閱 SecretRef Credential Surface。