设置

OpenClaw reads an optional JSON5 config from ~/.openclaw/openclaw.json (comments + trailing commas allowed).

如果文件缺失，OpenClaw 使用安全的默认值。您通常只需要配置来：

• restrict who can trigger the bot (channels.whatsapp.allowFrom, channels.telegram.allowFrom, etc.)
• 群组的 allowlist 和 mention 挙動（示示例：channels.whatsapp.groups、channels.telegram.groups、channels.discord.guilds、agents.list[].groupChat）。
• customize message prefixes (messages)
• 代理 workspace 的设置（agents.defaults.workspace / agents.list[].workspace）。

配置文件是 ~/.openclaw/openclaw.json，使用 JSON5（不是严格的 JSON）。

For small changes, prefer incremental updates (e.g., config.patch) over full replacement.

OpenClaw 只接受完全匹配模式的配置。未知键、格式错误的类型或无效值会导致网关拒绝启动以确保安全。

验证在失败如果执行了：

• Gateway 但起動不会执行。
• 只允许诊断命令（例如：openclaw doctor、openclaw logs、openclaw health、openclaw status）。
• openclaw doctor 在原因确认执行。
• openclaw doctor --fix（或 --yes）在迁移/修复適用执行。

除非您明确选择 --fix/--yes，否则 Doctor 永远不会写入更改。

Gateway 是 UI 编辑器向可在 config.schema 作为 JSON Schema 提供执行。

The Control UI renders a form from this schema, with a **Raw JSON** editor as an escape hatch.

插件可以注册 schema + UI 提示（标签、分组、敏感字段），以便客户端可以渲染更好的表单，而无需硬编码配置知识。

Use config.apply to validate + write the full config and restart the Gateway in one step.

Warning: config.apply replaces the entire config. If you want to change only a few keys, use config.patch or openclaw config set. Keep a backup of ~/.openclaw/openclaw.json.

参数：

• raw（string）：设置全体的 JSON5
• baseHash (optional) — config hash from config.get (required when a config already exists)
• sessionKey（任意）：重启後在 ping 执行最后一个会话 key
• note (optional) — note to include in the restart sentinel
• restartDelayMs（任意）：重启上一个遅延（默认 2000）

例（gateway call）：

openclaw gateway call config.get --params '{}' # capture payload.hash
openclaw gateway call config.apply --params '{
  "raw": "{\n  agents: { defaults: { workspace: \"~/.openclaw/workspace\" } }\n}\n",
  "baseHash": "<hash-from-config.get>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123",
  "restartDelayMs": 1000
}'

config.patch 在既存设置在部分钟更新合并执行。

合并补丁的挙動：

• 对象是再帰的在合并执行。
• null deletes a key
• arrays replace

Params:

• raw (string) — JSON5 payload containing just the keys to change
• baseHash（必须）：config.get 的 hash
• sessionKey（任意）：重启後在 ping 执行最后一个会话 key
• note (optional) — note to include in the restart sentinel
• restartDelayMs（任意）：重启上一个遅延（默认 2000）

例：

openclaw gateway call config.get --params '{}' # capture payload.hash
openclaw gateway call config.patch --params '{
  "raw": "{\n  channels: { telegram: { groups: { \"*\": { requireMention: false } } } }\n}\n",
  "baseHash": "<hash-from-config.get>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123",
  "restartDelayMs": 1000
}'

设置工作区并将 WhatsApp 私信限制为允许列表：

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

使用 $include 指令将配置拆分为多个文件。这对于以下情况很有用：

• 大机那设置整理（示示例：客户端每个代理定義）。
• 环境間在共通设置分钟享。
• 機密设置分钟離。

例：

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

OpenClaw 从父进程（shell、launchd/systemd、CI 等）读取环境变量。此外，它还加载：

• .env from the current working directory (if present)
• ~/.openclaw/.env（$OPENCLAW_STATE_DIR/.env）全局回退作为読见入见。
• .env 是既存的环境变量上写机不会执行。

您也可以在配置中提供内联环境变量。这些仅在进程环境缺少该键时应用（相同的非覆盖规则）：

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}

优先级和源是 /environment 请参阅。

您可以在任何配置字符串值中使用 ${{VAR_NAME}} 语法直接引用环境变量。变量在配置加载时、验证之前进行替换。

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

Rules:

• 大文字的 env 名仅：[A-Z_][A-Z0-9_]*
• 欠落/空的 env 是読见入见错误变为。
• Escape with $${{VAR}} to output a literal ${{VAR}}
• Works with $include (included files also get substitution)

OpenClaw stores per-agent auth profiles (OAuth + API keys) in:

• 主文件：<agentDir>/auth-profiles.json
• 旧导入：$OPENCLAW_STATE_DIR/credentials/oauth.json
• 代理目录可以通过 OPENCLAW_AGENT_DIR（首选）或 PI_CODING_AGENT_DIR（旧版）覆盖。

OAuth 的全体流程和保存布局是 /concepts/oauth 参照。

• 大机那更改前在 ~/.openclaw/openclaw.json 备份。
• 使用日志修订来避免泄露机密（logging.redactSensitive）。
• 复数代理在是代理単位的 sandbox/tools policy 使有。多代理 sandbox 和工具 参照。