本页是 ~/.openclaw/openclaw.json 的完整字段参考。养龙虾时遇到不知道怎么配的字段来这里查就对了。格式为 JSON5（支持注释和尾随逗号），所有字段均为可选——OpenClaw 在字段缺失时使用安全默认值。任务导向的配置概览见配置文档。子系统的深度参考链接到各自的专用页面。

OpenClaw 配置参考：openclaw.json 所有字段完整说明

核心配置文件位于 ~/.openclaw/openclaw.json。格式为 JSON5（支持注释和尾随逗号），所有字段均为可选。运行 openclaw config schema 可打印当前 JSON Schema。

代理查询路径：使用 gateway 工具动作 config.schema.lookup 获取精确字段级文档和约束。任务导向配置指南见配置文档。

深度子参考链接：

记忆配置参考覆盖 agents.defaults.memorySearch.*、memory.qmd.*、memory.citations 及 plugins.entries.memory-core.config.dreaming
斜杠命令参考覆盖内置 + 捆绑命令目录
渠道配置覆盖 channels.*
智能体配置覆盖 agents.defaults.*、multiAgent.*、session.*、messages.*、talk.*
工具及自定义 Provider 配置覆盖工具策略、自定义 Provider、MCP 等
Codex 插件配置

配置键名（如 dmPolicy、mcp.sessionIdleTtlMs）保留英文不翻译。

Channels

每个渠道的配置项已移至专用页面，见配置 - 渠道。涵盖 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 等捆绑渠道（认证、访问控制、多账号、提及门控）。

Agent defaults, multi-agent, sessions, and messages

已移至专用页面，见配置 - 智能体。覆盖：

agents.defaults.*（工作区、模型、思考、心跳、记忆、媒体、技能、沙箱）
multiAgent.*（多智能体路由和绑定）
session.*（会话生命周期、压缩、修剪）
messages.*（消息投递、TTS、Markdown 渲染）
talk.*（Talk 模式）
- talk.consultThinkingLevel: Control UI Talk 实时咨询时整个 OpenClaw 智能体运行的思考级别覆盖
- talk.consultFastMode: 一键快速模式覆盖
- talk.speechLocale: iOS/macOS 语音识别可选的 BCP 47 语言区域 ID
- talk.silenceTimeoutMs: 未设置时使用平台默认静音窗口（macOS/Android 700 ms，iOS 900 ms）

Tools and custom providers

已移至专用页面，见配置 - 工具和自定义 Provider。涵盖工具策略、实验开关、Provider 支持的工具配置、自定义 Provider / base-URL 设置。

Models

Provider 定义、模型允许列表和自定义 Provider 设置见配置 - 工具和自定义 Provider。models 根节点还拥有全局模型目录行为。

json5

{
  models: {
    // 可选。默认 true。修改后需重启 Gateway。
    pricing: { enabled: false },
  },
}

models.mode: Provider 目录行为（merge 或 replace）
models.providers: 按 provider id 键化的自定义 Provider 映射
models.providers.*.localService: 可选的按需进程管理器，用于本地模型服务器。OpenClaw 探测配置的健康端点，需要时启动绝对路径的 command，等待就绪后发送模型请求。见本地模型服务
models.pricing.enabled: 控制后台定价启动（Gateway 就绪后开始）。false 时跳过 OpenRouter 和 LiteLLM 定价目录获取；配置的 models.providers.*.models[].cost 仍可用于本地成本估算

MCP

OpenClaw 管理的 MCP 服务器定义位于 mcp.servers，由嵌入式 Pi 和其他运行时适配器消费。openclaw mcp list、show、set、unset 命令管理此块，配置编辑时不连接目标服务器。

json5

{
  mcp: {
    // 可选。默认 600000 ms（10 分钟）。设为 0 禁用空闲逐出。
    sessionIdleTtlMs: 600000,
    servers: {
      docs: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-fetch"],
      },
      remote: {
        url: "https://example.com/mcp",
        transport: "streamable-http", // streamable-http | sse
        headers: {
          Authorization: "Bearer ${MCP_REMOTE_TOKEN}",
        },
        // 可选 Codex app-server 投影控制
        codex: {
          agents: ["main"],
          defaultToolsApprovalMode: "approve", // auto | prompt | approve
        },
      },
    },
  },
}

mcp.servers: 命名的 stdio 或远程 MCP 服务器定义。远程条目使用 transport: "streamable-http" 或 transport: "sse"；type: "http" 是 CLI 原生的别名，openclaw mcp set 和 openclaw doctor --fix 会将其规范化为 transport 字段
mcp.servers.<name>.codex: 可选的 Codex app-server 投影控制。仅适用于 Codex app-server 线程，不影响 ACP 会话、通用 Codex harness 配置或其他运行时适配器。非空 codex.agents 限制服务器仅针对列出的 OpenClaw 智能体 ID。空、空白或无效范围的 agent 列表在配置验证时被拒绝，运行时投影路径会跳过而不是全局生效。codex.defaultToolsApprovalMode 发出 Codex 原生的 default_tools_approval_mode。OpenClaw 在向 Codex 传递原生 mcp_servers 配置前会剥离 codex 块。省略 block 则保持服务器投影到每个 Codex app-server 智能体，并使用 Codex 默认的 MCP 审批行为
mcp.sessionIdleTtlMs: 会话范围捆绑 MCP 运行时的空闲 TTL。一次性嵌入式运行在结束时请求清理；此 TTL 是长期回退。修改 mcp.* 热生效：丢弃缓存会话 MCP 运行时，下次工具发现/使用时会重新创建。因此删除的 mcp.servers 条目会立即被清除，无需等待空闲 TTL

运行时行为见 MCP 和 CLI 后端。

Skills

json5

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn | bun
      allowUploadedArchives: false,
    },
    entries: {
      "image-lab": {
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // 或纯字符串
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

allowBundled: 可选的捆绑技能允许列表（管理的/工作区技能不受影响）
load.extraDirs: 额外的共享技能根目录（优先级最低）
load.allowSymlinkTargets: 技能符号链接可解析的可信真实目标根目录（当链接位于配置的源根之外时）
install.preferBrew: 启用时优先使用 Homebrew 安装器（当 brew 可用时），否则回退到其他安装器类型
install.nodeManager: 节点安装器偏好（npm | pnpm | yarn | bun）
install.allowUploadedArchives: 允许可信 operator.admin Gateway 客户端安装通过 skills.upload.* 分段的私有 zip 归档（默认 false）。仅启用上传归档路径；普通 ClawHub 安装不需要此设置
entries.<skillKey>.enabled: false 禁用技能，即使已捆绑/安装
entries.<skillKey>.apiKey: 便捷字段，用于声明主环境变量的技能（纯字符串或 SecretRef 对象）

Plugins

json5

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    bundledDiscovery: "allowlist",
    deny: [],
    load: {
      paths: ["~/Projects/oss/voice-call-plugin"],
    },
    entries: {
      "voice-call": {
        enabled: true,
        hooks: {
          allowPromptInjection: false,
        },
        config: { provider: "twilio" },
      },
    },
  },
}

加载自 ~/.openclaw/extensions、<workspace>/.openclaw/extensions 以及 plugins.load.paths
发现接受原生 OpenClaw 插件以及兼容的 Codex bundles 和 Claude bundles（包括无清单的 Claude 默认布局 bundles）
配置更改需要重启 Gateway
allow: 可选允许列表（仅加载列出的插件）。deny 胜出
bundledDiscovery: 新配置默认 "allowlist"，因此非空 plugins.allow 也会限制捆绑 Provider 插件，包括 web-search 运行时 Provider。Doctor 会为迁移的旧允许列表配置写入 "compat"，以保留现有捆绑 Provider 行为，直到你选择加入
plugins.entries.<id>.apiKey: 插件级 API 密钥便捷字段（插件支持时）
plugins.entries.<id>.env: 插件作用域环境变量映射
plugins.entries.<id>.hooks.allowPromptInjection: false 时核心阻止 before_prompt_build 并忽略来自旧 before_agent_start 提示变异字段，同时保留 modelOverride 和 providerOverride。适用于原生插件钩子和支持的 bundle 提供的钩子目录
plugins.entries.<id>.hooks.allowConversationAccess: true 时受信任的非捆绑插件可以读取类型化钩子中的原始对话内容，例如 llm_input、llm_output、before_model_resolve、before_agent_reply、before_agent_run、before_agent_finalize、agent_end
plugins.entries.<id>.subagent.allowModelOverride: 明确信任此插件请求每次运行的 provider 和 model 覆盖用于后台子智能体运行
plugins.entries.<id>.subagent.allowedModels: 可选允许列表，用于受信任子智能体覆盖的规范 provider/model 目标。仅在你有意允许任何模型时使用 "*"
plugins.entries.<id>.llm.allowModelOverride: 明确信任此插件请求 api.runtime.llm.complete 的模型覆盖
plugins.entries.<id>.llm.allowedModels: 可选允许列表，用于受信任插件 LLM 补全覆盖的规范 provider/model 目标。仅在你有意允许任何模型时使用 "*"
plugins.entries.<id>.llm.allowAgentIdOverride: 明确信任此插件对非默认智能体 ID 运行 api.runtime.llm.complete
plugins.entries.<id>.config: 插件定义的配置对象（可用原生 OpenClaw 插件 schema 验证）
渠道插件账户/运行时设置位于 channels.<id>，应由拥有插件的 manifest channelConfigs 元数据描述，不由中央 OpenClaw 选项注册表定义

Codex harness plugin config

捆绑的 codex 插件拥有原生 Codex app-server harness 设置，位于 plugins.entries.codex.config。完整配置表面见 Codex harness 参考，运行时模型见 Codex harness。

codexPlugins 仅适用于选择原生 Codex harness 的会话。它不会为 Pi、普通 OpenAI Provider 运行、ACP 会话绑定或任何非 Codex harness 启用 Codex 插件。

json5

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          codexPlugins: {
            enabled: true,
            allow_destructive_actions: true,
            plugins: {
              "google-calendar": {
                enabled: true,
                marketplaceName: "openai-curated",
                pluginName: "google-calendar",
                allow_destructive_actions: false,
              },
            },
          },
        },
      },
    },
  },
}

plugins.entries.codex.config.codexPlugins.enabled: 启用 Codex harness 的原生 Codex 插件/应用支持。默认 false
plugins.entries.codex.config.codexPlugins.allow_destructive_actions: 迁移插件应用引发时的默认破坏性操作策略。默认 true
plugins.entries.codex.config.codexPlugins.plugins.<key>.enabled: 全局 codexPlugins.enabled 也为 true 时启用迁移插件条目。默认 true
plugins.entries.codex.config.codexPlugins.plugins.<key>.marketplaceName: 稳定的市场标识。V1 仅支持 "openai-curated"
plugins.entries.codex.config.codexPlugins.plugins.<key>.pluginName: 迁移后的稳定 Codex 插件标识，例如 "google-calendar"
plugins.entries.codex.config.codexPlugins.plugins.<key>.allow_destructive_actions: 每插件破坏性操作覆盖。省略时使用全局 allow_destructive_actions

codexPlugins.enabled 是全局启用指令。迁移写入的显式插件条目是持久安装和修复资格集。不支持 plugins["*"]，没有 install 开关，并且 marketplacePath 值故意不作为配置字段，因为它们特定于主机。

app/list 就绪检查缓存一小时，过期后异步刷新。Codex 线程应用配置在 Codex harness 会话建立时计算，而非每次轮次；更改原生插件配置后使用 /new、/reset 或重启 Gateway。

plugins.entries.firecrawl.config.webFetch: Firecrawl web-fetch Provider 设置
- apiKey: Firecrawl API 密钥（接受 SecretRef）。回退到 plugins.entries.firecrawl.config.webSearch.apiKey、旧 tools.web.fetch.firecrawl.apiKey 或 FIRECRAWL_API_KEY 环境变量
- baseUrl: Firecrawl API 基础 URL（默认 https://api.firecrawl.dev；自托管覆盖必须针对私有/内部端点）
- onlyMainContent: 仅提取页面主要内容（默认 true）
- maxAgeMs: 最大缓存年龄，毫秒（默认 172800000 / 2 天）
- timeoutSeconds: 抓取请求超时秒数（默认 60）
plugins.entries.xai.config.xSearch: xAI X Search（Grok web search）设置
- enabled: 启用 X Search Provider
- model: 用于搜索的 Grok 模型，例如 "grok-4-1-fast"
plugins.entries.memory-core.config.dreaming: 记忆 dreaming 设置。阶段和阈值见 Dreaming
- enabled: 主 dreaming 开关（默认 false）
- frequency: 每次完整 dreaming 扫描的 cron 节奏（默认 "0 3 * * *"）
- model: 可选的 Dream Diary 子智能体模型覆盖。需要 plugins.entries.memory-core.subagent.allowModelOverride: true；配合 allowedModels 限制目标。模型不可用错误会使用会话默认模型重试一次；信任或允许列表失败不会静默回退
- 阶段策略和阈值是实现细节（非用户面向配置键）
完整记忆配置见记忆配置参考：
- agents.defaults.memorySearch.*
- memory.backend
- memory.citations
- memory.qmd.*
- plugins.entries.memory-core.config.dreaming
启用的 Claude bundle 插件还可以从 settings.json 贡献嵌入式 Pi 默认值；OpenClaw 将其作为清理后的智能体设置应用，而非原始 OpenClaw 配置补丁
plugins.slots.memory: 选择活动的记忆插件 ID，或 "none" 禁用记忆插件
plugins.slots.contextEngine: 选择活动的上下文引擎插件 ID；默认 "legacy"，除非你安装并选择另一个引擎

见插件。

Commitments

commitments 控制推断的后续记忆：OpenClaw 可以从对话轮次中检测 check-in 并通过心跳运行交付。

commitments.enabled: 启用隐藏的 LLM 提取、存储和心跳交付，用于推断的后续承诺。默认 false
commitments.maxPerDay: 每个智能体会话在滚动日内交付的最大推断后续承诺数。默认 3

见推断承诺。

Browser

json5

{
  browser: {
    enabled: true,
    evaluateEnabled: true,
    defaultProfile: "user",
    ssrfPolicy: {
      // dangerouslyAllowPrivateNetwork: true, // 仅对受信任的私有网络访问选择启用
      // allowPrivateNetwork: true, // 旧别名
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    tabCleanup: {
      enabled: true,
      idleMinutes: 120,
      maxTabsPerSession: 8,
      sweepMinutes: 5,
    },
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: {
        cdpPort: 18801,
        color: "#0066CC",
        executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
      },
      user: { driver: "existing-session", attachOnly: true, color: "#00AA00" },
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
    color: "#FF4500",
    // headless: false,
    // noSandbox: false,
    // extraArgs: [],
    // executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    // attachOnly: false,
  },
}

evaluateEnabled: false 禁用 act:evaluate 和 wait --fn
tabCleanup 在空闲时间后会回收跟踪的主智能体标签页，或当会话超过其容量时。设 idleMinutes: 0 或 maxTabsPerSession: 0 禁用这些单独的清理模式
ssrfPolicy.dangerouslyAllowPrivateNetwork 未设置时禁用，因此浏览器导航默认保持严格
仅当你有意信任私有网络浏览器导航时才设置 ssrfPolicy.dangerouslyAllowPrivateNetwork: true
在严格模式下，远程 CDP profile 端点 (profiles.*.cdpUrl) 在可达性/发现检查期间受同样的私有网络阻止
ssrfPolicy.allowPrivateNetwork 作为旧别名仍受支持
严格模式下使用 ssrfPolicy.hostnameAllowlist 和 ssrfPolicy.allowedHostnames 进行显式例外
远程 profile 是只附加的（start/stop/reset 禁用）
profiles.*.cdpUrl 接受 http://、https://、ws://、wss://。当你希望 OpenClaw 发现 /json/version 时使用 HTTP(S)；当你的 Provider 给出直接 DevTools WebSocket URL 时使用 WS(S)
remoteCdpTimeoutMs 和 remoteCdpHandshakeTimeoutMs 适用于远程和 attachOnly CDP 可达性以及标签页打开请求。管理的回环 profile 保持本地 CDP 默认值
如果外部管理的 CDP 服务通过回环可达，设置该 profile 的 attachOnly: true；否则 OpenClaw 会将回环端口视为本地管理的浏览器 profile，并可能报告本地端口所有权错误
existing-session profile 使用 Chrome MCP 而非 CDP，可以附加到选定主机或通过连接的浏览器节点
existing-session profile 可以设置 userDataDir 以定位特定的基于 Chromium 的浏览器 profile，如 Brave 或 Edge
existing-session profile 保持当前 Chrome MCP 路由限制：快照/引用驱动的操作而不是 CSS 选择器定位、单文件上传钩子、无对话框超时覆盖、无 wait --load networkidle、无 responsebody、PDF 导出、下载拦截或批量操作
本地管理的 openclaw profile 自动分配 cdpPort 和 cdpUrl；仅对远程 CDP 显式设置 cdpUrl
本地管理的 profile 可以设置 executablePath 以覆盖全局 browser.executablePath 用于该 profile。例如在一个 profile 中用 Chrome 运行，在另一个中用 Brave
本地管理的 profile 使用 browser.localLaunchTimeoutMs 用于 Chrome CDP HTTP 发现（进程启动后），以及 browser.localCdpReadyTimeoutMs 用于启动后 CDP websocket 就绪。在较慢的主机上提高这些值，如果 Chrome 启动成功但就绪检查竞争启动时间。两个值必须是正整数，最高到 120000 ms；无效配置值被拒绝
自动检测顺序：如果基于 Chromium 的默认浏览器 → Chrome → Brave → Edge → Chromium → Chrome Canary
browser.executablePath 和 browser.profiles.<name>.executablePath 都接受 ~ 和 ~/... 用于你的 OS 主目录，在 Chromium 启动前展开。每 profile userDataDir 在 existing-session profile 上也会展开波浪号
控制服务：仅回环（端口派生自 gateway.port，默认 18791）
extraArgs 向本地 Chromium 启动添加额外启动标志（例如 --disable-gpu、窗口大小或调试标志）

UI

json5

{
  ui: {
    seamColor: "#FF4500",
    assistant: {
      name: "OpenClaw",
      avatar: "CB", // 表情符号、短文本、图片 URL 或 data URI
    },
  },
}

seamColor: 原生应用 UI 铬色底色（Talk Mode 气泡色调等）
assistant: Control UI 身份覆盖。回退到活动智能体身份

Gateway

json5

{
  gateway: {
    mode: "local", // local | remote
    port: 18789,
    bind: "loopback",
    auth: {
      mode: "token", // none | token | password | trusted-proxy
      token: "your-token",
      // password: "your-password", // 或 OPENCLAW_GATEWAY_PASSWORD
      // trustedProxy: { userHeader: "x-forwarded-user" }, // 用于 mode=trusted-proxy; 见 /openclaw/gateway/trusted-proxy-auth
      allowTailscale: true,
      rateLimit: {
        maxAttempts: 10,
        windowMs: 60000,
        lockoutMs: 300000,
        exemptLoopback: true,
      },
    },
    tailscale: {
      mode: "off", // off | serve | funnel
      resetOnExit: false,
    },
    controlUi: {
      enabled: true,
      basePath: "/openclaw",
      // root: "dist/control-ui",
      // embedSandbox: "scripts", // strict | scripts | trusted
      // allowExternalEmbedUrls: false, // dangerous: 允许绝对外部 http(s) 嵌入 URL
      // chatMessageMaxWidth: "min(1280px, 82%)", // 可选的分组聊天消息最大宽度
      // allowedOrigins: ["https://control.example.com"], // 非回环 Control UI 需要
      // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的 Host-header origin 回退模式
      // allowInsecureAuth: false,
      // dangerouslyDisableDeviceAuth: false,
    },
    remote: {
      url: "ws://127.0.0.1:18789",
      transport: "ssh", // ssh | direct
      token: "your-token",
      // password: "your-password",
    },
    trustedProxies: ["10.0.0.1"],
    // 可选。默认 false。
    allowRealIpFallback: false,
    nodes: {
      pairing: {
        // 可选。默认未设置/禁用。
        autoApproveCidrs: ["192.168.1.0/24", "fd00:1234:5678::/64"],
      },
      allowCommands: ["canvas.navigate"],
      denyCommands: ["system.run"],
    },
    tools: {
      // 额外的 /tools/invoke HTTP 拒绝
      deny: ["browser"],
      // 从默认 HTTP 拒绝列表移除工具
      allow: ["gateway"],
    },
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          timeoutMs: 10000,
        },
      },
    },
  },
}

Gateway 字段详情

mode: local（运行 gateway）或 remote（连接到远程 gateway）。Gateway 拒绝在 local 模式下以外启动
port: 单个多路复用端口用于 WS + HTTP。优先级：--port > OPENCLAW_GATEWAY_PORT > gateway.port > 18789
bind: auto、loopback（默认）、lan（0.0.0.0）、tailnet（仅 Tailscale IP）或 custom
旧绑定别名：使用 gateway.bind 绑定模式值（auto、loopback、lan、tailnet、custom），而非主机别名（0.0.0.0、127.0.0.1、localhost、::、::1）
Docker 注意：默认 loopback 绑定在容器内部监听 127.0.0.1。使用 Docker 桥接网络 (-p 18789:18789) 时流量到达 eth0，因此 gateway 不可达。使用 --network host，或设置 bind: "lan"（或 bind: "custom" 并 customBindHost: "0.0.0.0"）以监听所有接口
认证：默认必需。非回环绑定需要 gateway 认证。这通常意味着共享 token/password 或具有 gateway.auth.mode: "trusted-proxy" 的、识别身份的反向代理。Onboarding 向导默认生成 token
如果同时配置了 gateway.auth.token 和 gateway.auth.password（包括 SecretRef），显式设置 gateway.auth.mode 为 token 或 password。当两者都配置且 mode 未设置时，启动和服务安装/修复流程会失败
gateway.auth.mode: "none"：显式无认证模式。仅用于受信任的本地回环设置；onboarding 提示故意不提供此选项
gateway.auth.mode: "trusted-proxy"：将浏览器/用户认证委托给识别身份的反向代理，并信任 gateway.trustedProxies 中的身份标头（见受信任代理认证）。此模式默认期望非回环代理源；同主机回环反向代理需要显式 gateway.auth.trustedProxy.allowLoopback = true。内部同主机调用者可以使用 gateway.auth.password 作为本地直接回退；gateway.auth.token 与受信任代理模式保持互斥
gateway.auth.allowTailscale：true 时，Tailscale Serve 身份标头可以满足 Control UI/WebSocket 认证（通过 tailscale whois 验证）。HTTP API 端点不使用 Tailscale 标头认证；它们遵循 gateway 的正常 HTTP 认证模式。此无 token 流程假设 gateway 主机受信任。默认 true 当 tailscale.mode = "serve"
gateway.auth.rateLimit：可选的失败认证限流器。按客户端 IP 和认证作用域独立跟踪。阻止的尝试返回 429 + Retry-After
- 在异步 Tailscale Serve Control UI 路径上，相同 {scope, clientIp} 的失败尝试在失败写入前被序列化。因此相同客户端的并发错误尝试可能触发限流器，而不是两者都作为纯不匹配通过
- gateway.auth.rateLimit.exemptLoopback 默认 true；当你有意让 localhost 流量也被限流时（用于测试设置或严格代理部署）设为 false
浏览器来源的 WS 认证尝试总是被限流，且回环豁免禁用（针对基于浏览器的 localhost 暴力攻击的深度防御）
在回环上，那些浏览器来源的锁定按规范化的 Origin 值隔离，因此一个 localhost 来源的重复失败不会自动锁定另一个来源
tailscale.mode: serve（仅 tailnet，回环绑定）或 funnel（公开，需要认证）
tailscale.preserveFunnel: 当 true 且 tailscale.mode = "serve" 时，OpenClaw 在启动前检查 tailscale funnel status，如果外部配置的 Funnel 路由已覆盖 gateway 端口则跳过重新应用 Serve。默认 false
controlUi.allowedOrigins: Gateway WebSocket 连接的显式浏览器来源允许列表。公开的非回环浏览器来源需要。私有同源 LAN/Tailnet UI 从回环、RFC1918/链路本地、.local、.ts.net 或 Tailscale CGNAT 主机加载被接受，无需启用 Host-header 回退
controlUi.chatMessageMaxWidth: 可选的 Control UI 分组聊天消息最大宽度。接受约束的 CSS 宽度值，如 960px、82%、min(1280px, 82%)、calc(100% - 2rem)
controlUi.dangerouslyAllowHostHeaderOriginFallback: 危险模式，启用 Host-header origin 回退用于有意依赖 Host-header origin 策略的部署
remote.transport: ssh（默认）或 direct（ws/wss）。对于 direct，remote.url 必须是 wss:// 用于公开主机；纯文本 ws:// 仅对回环、LAN、链路本地、.local、.ts.net 和 Tailscale CGNAT 主机接受
remote.remotePort: 远程 SSH 主机上的 gateway 端口。默认 18789；当本地隧道端口与远程 gateway 端口不同时使用此设置
gateway.remote.token / .password 是远程客户端凭证字段。它们本身不配置 gateway 认证
gateway.push.apns.relay.baseUrl: 用于官方/TestFlight iOS 构建的外部 APNs 中继的 HTTPS URL，这些构建将中继支持的注册发布到 gateway。此 URL 必须与编译到 iOS 构建中的中继 URL 匹配
gateway.push.apns.relay.timeoutMs: gateway 到中继的发送超时毫秒。默认 10000
中继支持的注册委托给特定的 gateway 身份。配对的 iOS 应用获取 gateway.identity.get，将该身份包含在中继注册中，并将注册作用域的发送授权转发给 gateway。另一个 gateway 无法重用该存储的注册
OPENCLAW_APNS_RELAY_BASE_URL / OPENCLAW_APNS_RELAY_TIMEOUT_MS：上面中继配置的临时环境覆盖
OPENCLAW_APNS_RELAY_ALLOW_HTTP=true：仅开发用途，用于回环 HTTP 中继 URL。生产环境中继 URL 应使用 HTTPS
gateway.handshakeTimeoutMs: 预认证 Gateway WebSocket 握手超时毫秒。默认 15000。OPENCLAW_HANDSHAKE_TIMEOUT_MS 拥有更高优先级。在加载或低功耗主机上增加此值，此处本地客户端可以连接，同时启动预热仍在进行
gateway.channelHealthCheckMinutes: 渠道健康监视器间隔分钟。设为 0 禁用全局健康监视器重启。默认 5
gateway.channelStaleEventThresholdMinutes: 过时套接字阈值分钟。保持大于等于 gateway.channelHealthCheckMinutes。默认 30
gateway.channelMaxRestartsPerHour: 每小时每渠道/账户的健康监视器最大重启次数。默认 10
channels.<provider>.healthMonitor.enabled: 每渠道选择退出健康监视器重启，同时保持全局监视器启用
channels.<provider>.accounts.<accountId>.healthMonitor.enabled: 多账号渠道的每账户覆盖。设置后优先于渠道级覆盖
本地 gateway 调用路径只有在 gateway.auth.* 未设置时才可以使用 gateway.remote.* 作为回退
如果 gateway.auth.token / gateway.auth.password 显式配置为 SecretRef 且解析失败，解析会失败关闭（无远程回退掩码）
trustedProxies: 终止 TLS 或注入转发客户端标头的反向代理 IP。仅列出你控制的代理。回环条目对于同主机代理/本地检测设置（如 Tailscale Serve 或本地反向代理）仍然有效，但不会使回环请求有资格使用 gateway.auth.mode: "trusted-proxy"
allowRealIpFallback: true 时 gateway 在 X-Forwarded-For 缺失时接受 X-Real-IP。默认 false 以实现失败关闭行为
gateway.nodes.pairing.autoApproveCidrs: 可选的 CIDR/IP 允许列表，用于自动批准首次节点设备配对（无请求作用域）。未设置时禁用。这不自动批准 operator/浏览器/Control UI/WebChat 配对，也不自动批准角色、作用域、元数据或公钥升级
gateway.nodes.allowCommands / gateway.nodes.denyCommands: 声明的节点命令的全局允许/拒绝塑造，在配对和平台允许列表评估之后。使用 allowCommands 选择加入危险节点命令如 camera.snap、camera.clip、screen.record；denyCommands 移除一个命令，即使平台默认或显式允许会包含它。节点更改其声明的命令列表后，拒绝并重新批准该设备配对，以便 gateway 存储更新的命令快照
gateway.tools.deny: 为 HTTP POST /tools/invoke 额外阻止的工具名称（扩展默认拒绝列表）
gateway.tools.allow: 从默认 HTTP 拒绝列表移除工具名称

OpenAI-compatible endpoints

Admin HTTP RPC：默认关闭，作为 admin-http-rpc 插件。启用插件以注册 POST /api/v1/admin/rpc。见Admin HTTP RPC
Chat Completions：默认禁用。启用 gateway.http.endpoints.chatCompletions.enabled: true
Responses API：gateway.http.endpoints.responses.enabled
Responses URL-input hardening：
- gateway.http.endpoints.responses.maxUrlParts
- gateway.http.endpoints.responses.files.urlAllowlist
- gateway.http.endpoints.responses.images.urlAllowlist 空允许列表视为未设置；使用 gateway.http.endpoints.responses.files.allowUrl=false 和/或 gateway.http.endpoints.responses.images.allowUrl=false 禁用 URL 获取
可选响应强化标头：
- gateway.http.securityHeaders.strictTransportSecurity（仅为你控制的 HTTPS 来源设置；见受信任代理认证）

Multi-instance isolation

在一台主机上运行多个 gateway，使用唯一端口和状态目录：

bash

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001

便捷标志：--dev（使用 ~/.openclaw-dev + 端口 19001），--profile <name>（使用 ~/.openclaw-<name>）。

见多 Gateway。

`gateway.tls`

json5

{
  gateway: {
    tls: {
      enabled: false,
      autoGenerate: false,
      certPath: "/etc/openclaw/tls/server.crt",
      keyPath: "/etc/openclaw/tls/server.key",
      caPath: "/etc/openclaw/tls/ca-bundle.crt",
    },
  },
}

enabled: 在 gateway 监听器启用 TLS 终止（HTTPS/WSS）（默认 false）
autoGenerate: 无显式文件配置时自动生成本地自签名证书/密钥对；仅用于本地/开发用途
certPath: TLS 证书文件路径
keyPath: TLS 私钥文件路径；保持权限限制
caPath: 可选的客户端验证或自定义信任链的 CA 包路径

`gateway.reload`

json5

{
  gateway: {
    reload: {
      mode: "hybrid", // off | restart | hot | hybrid
      debounceMs: 500,
      deferralTimeoutMs: 300000,
    },
  },
}

mode: 控制配置编辑如何在运行时应用
- "off": 忽略实时编辑；更改需要显式重启
- "restart": 配置更改时总是重启 gateway 进程
- "hot": 不重启进程应用更改
- "hybrid"（默认）: 先尝试热重载；如果需要则回退到重启
debounceMs: 配置更改应用前的去抖窗口 ms（非负整数）
deferralTimeoutMs: 可选的最大等待时间 ms，用于等待进行中的操作完成，然后强制重启或渠道热重载。省略以使用默认有界等待（300000）；设为 0 以无限等待并记录周期性的待处理警告

Hooks

json5

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    maxBodyBytes: 262144,
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: true,
    allowedSessionKeyPrefixes: ["hook:", "hook:gmail:"],
    allowedAgentIds: ["hooks", "main"],
    presets: ["gmail"],
    transformsDir: "~/.openclaw/hooks/transforms",
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "hooks",
        wakeMode: "now",
        name: "Gmail",
        sessionKey: "hook:gmail:&#123;&#123;messages[0].id&#125;&#125;",
        messageTemplate: "From: &#123;&#123;messages[0].from&#125;&#125;\nSubject: &#123;&#123;messages[0].subject&#125;&#125;\n&#123;&#123;messages[0].snippet&#125;&#125;",
        deliver: true,
        channel: "last",
        model: "openai/gpt-5.4-mini",
      },
    ],
  },
}

认证：Authorization: Bearer <token> 或 x-openclaw-token: <token>。查询字符串钩子 token 被拒绝。

验证和安全注意事项：

hooks.enabled=true 需要非空 hooks.token
hooks.token 必须与 gateway.auth.token 不同；重用 Gateway token 被拒绝
hooks.path 不能是 /；使用专用子路径如 /hooks
如果 hooks.allowRequestSessionKey=true，限制 hooks.allowedSessionKeyPrefixes（例如 ["hook:"]）
如果映射或预设使用模板化的 sessionKey，设置 hooks.allowedSessionKeyPrefixes 和 hooks.allowRequestSessionKey=true。静态映射键不需要此选择加入

端点：

POST /hooks/wake → { text, mode?: "now"|"next-heartbeat" }
POST /hooks/agent → { message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }
- 来自请求 payload 的 sessionKey 仅在 hooks.allowRequestSessionKey=true 时接受（默认 false）
POST /hooks/<name> → 通过 hooks.mappings 解析
- 模板渲染的映射 sessionKey 值被视为外部提供，也需要 hooks.allowRequestSessionKey=true

映射详情

match.path 匹配 /hooks 后的子路径（例如 /hooks/gmail → gmail）
match.source 为通用路径匹配 payload 字段
模板如 {{messages[0].subject}} 从 payload 读取
transform 可以指向返回钩子操作的 JS/TS 模块
- transform.module 必须是相对路径，并保持在 hooks.transformsDir 内（绝对路径和遍历被拒绝）
- 保持 hooks.transformsDir 在 ~/.openclaw/hooks/transforms 下；工作区技能目录被拒绝。如果 openclaw doctor 报告此路径无效，将转换模块移动到钩子转换目录，或移除 hooks.transformsDir
agentId 路由到特定智能体；未知 ID 回退到默认
allowedAgentIds: 限制显式路由（* 或省略 = 允许所有，[] = 拒绝所有）
defaultSessionKey: 无显式 sessionKey 的钩子智能体运行的可选固定会话键
allowRequestSessionKey: 允许 /hooks/agent 调用者和模板驱动的映射会话键设置 sessionKey（默认 false）
allowedSessionKeyPrefixes: 可选的前缀允许列表用于显式 sessionKey 值（请求 + 映射），例如 ["hook:"]。当任何映射或预设使用模板化的 sessionKey 时成为必需
deliver: true 将最终回复发送到渠道；channel 默认 last
model 为此钩子运行覆盖 LLM（如果设置了模型目录则必须被允许）

Gmail integration

内置 Gmail 预设使用 sessionKey: "hook:gmail:{{messages[0].id}}"
如果保持该每消息路由，设置 hooks.allowRequestSessionKey: true 并限制 hooks.allowedSessionKeyPrefixes 以匹配 Gmail 命名空间，例如 ["hook:", "hook:gmail:"]
如果需要 hooks.allowRequestSessionKey: false，使用静态 sessionKey 覆盖预设，而非模板化的默认值

json5

{
  hooks: {
    gmail: {
      account: "openclaw@gmail.com",
      topic: "projects/<project-id>/topics/gog-gmail-watch",
      subscription: "gog-gmail-watch-push",
      pushToken: "shared-push-token",
      hookUrl: "http://127.0.0.1:18789/hooks/gmail",
      includeBody: true,
      maxBytes: 20000,
      renewEveryMinutes: 720,
      serve: { bind: "127.0.0.1", port: 8788, path: "/" },
      tailscale: { mode: "funnel", path: "/gmail-pubsub" },
      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
      thinking: "off",
    },
  },
}

Gateway 配置后自动启动 gog gmail watch serve。设置 OPENCLAW_SKIP_GMAIL_WATCHER=1 禁用
不要与 Gateway 一起单独运行 gog gmail watch serve

Canvas plugin host

json5

{
  plugins: {
    entries: {
      canvas: {
        config: {
          host: {
            root: "~/.openclaw/workspace/canvas",
            liveReload: true,
            // enabled: false, // 或 OPENCLAW_SKIP_CANVAS_HOST=1
          },
        },
      },
    },
  },
}

在 Gateway 端口下通过 HTTP 提供智能体可编辑的 HTML/CSS/JS 和 A2UI：
- http://<gateway-host>:<gateway.port>/__openclaw__/canvas/
- http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/
仅本地：保持 gateway.bind: "loopback"（默认）
非回环绑定：canvas 路由需要 Gateway 认证（token/password/trusted-proxy），与其他 Gateway HTTP 表面相同
节点 WebView 通常不发送认证标头；配对并连接后，Gateway 会广告节点作用域的能力 URL 用于 canvas/A2UI 访问
能力 URL 绑定到活动的节点 WS 会话并快速过期。不使用基于 IP 的回退
向提供的 HTML 注入实时重载客户端
空目录时自动创建起始 index.html
也在 /__openclaw__/a2ui/ 提供 A2UI
更改需要重启 Gateway
对于大目录或 EMFILE 错误禁用实时重载

Discovery

mDNS (Bonjour)

json5

{
  discovery: {
    mdns: {
      mode: "minimal", // minimal | full | off
    },
  },
}

minimal（捆绑 bonjour 插件启用时的默认值）：从 TXT 记录省略 cliPath + sshPort
full：包含 cliPath + sshPort；LAN 多播广告仍然需要捆绑的 bonjour 插件启用
off：抑制 LAN 多播广告而不更改插件启用状态
捆绑的 bonjour 插件在 macOS 主机上自动启动，在 Linux、Windows 和容器化 Gateway 部署中选择加入
主机名默认使用系统主机名（当它是有效 DNS 标签时），回退到 openclaw。使用 OPENCLAW_MDNS_HOSTNAME 覆盖

Wide-area (DNS-SD)

json5

{
  discovery: {
    wideArea: { enabled: true },
  },
}

在 ~/.openclaw/dns/ 下写入单播 DNS-SD 区域。用于跨网络发现，配合 DNS 服务器（推荐 CoreDNS）+ Tailscale split DNS。

设置：openclaw dns setup --apply

Environment

`env` (inline env vars)

json5

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

内联环境变量仅在进程环境缺少该键时应用
.env 文件：CWD .env + ~/.openclaw/.env（两者都不会覆盖现有变量）
shellEnv: 从你的登录 shell 配置文件导入缺失的预期键
完整优先级见环境文档

Env var substitution

在任何配置字符串中使用 ${VAR_NAME} 引用环境变量：

json5

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

仅匹配大写名称：[A-Z_][A-Z0-9_]*
缺失/空变量会在配置加载时抛出错误
使用 $${VAR} 转义以获得字面 ${VAR}
与 $include 一起工作

Secrets

Secret refs 是累加的：纯文本值仍然有效。

`SecretRef`

使用一个对象形状：

json5

{ source: "env" | "file" | "exec", provider: "default", id: "..." }

验证：

provider 模式：^[a-z][a-z0-9_-]{0,63}$
source: "env" id 模式：^[A-Z][A-Z0-9_]{0,127}$
source: "file" id：绝对 JSON 指针（例如 "/providers/openai/apiKey"）
source: "exec" id 模式：^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$
source: "exec" id 不能包含 . 或 .. 以斜杠分隔的路径段（例如 a/../b 被拒绝）

支持的凭证表面

规范矩阵：SecretRef 凭证表面
secrets apply 目标支持的 openclaw.json 凭证路径
auth-profiles.json refs 包含在运行时解析和审计覆盖中

Secret providers config

json5

{
  secrets: {
    providers: {
      default: { source: "env" }, // 可选的显式 env provider
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json",
        timeoutMs: 5000,
      },
      vault: {
        source: "exec",
        command: "/usr/local/bin/openclaw-vault-resolver",
        passEnv: ["PATH", "VAULT_ADDR"],
      },
    },
    defaults: {
      env: "default",
      file: "filemain",
      exec: "vault",
    },
  },
}

注意事项：

file provider 支持 mode: "json" 和 mode: "singleValue"（id 在 singleValue 模式下必须为 "value"）
文件和控制提供者路径在无法进行 Windows ACL 验证时失败关闭。仅对不可验证的受信任路径设置 allowInsecurePath: true
exec provider 需要绝对 command 路径，并使用 stdin/stdout 上的协议 payload
默认情况下，符号链接命令路径被拒绝。设置 allowSymlinkCommand: true 以允许符号链接路径，同时验证解析后的目标路径
如果配置了 trustedDirs，受信任目录检查适用于解析后的目标路径
exec 子环境最小；显式使用 passEnv 传递所需变量
Secret refs 在激活时解析为内存快照，然后请求路径仅读取快照
活动表面过滤在激活期间应用：启用表面的未解析 refs 会使启动/重载失败，而非活动表面会被跳过并附带诊断信息

Auth storage

json5

{
  auth: {
    profiles: {
      "anthropic:default": { provider: "anthropic", mode: "api_key" },
      "anthropic:work": { provider: "anthropic", mode: "api_key" },
      "openai-codex:personal": { provider: "openai-codex", mode: "oauth" },
    },
    order: {
      anthropic: ["anthropic:default", "anthropic:work"],
      "openai-codex": ["openai-codex:personal"],
    },
  },
}

每智能体配置文件存储在 <agentDir>/auth-profiles.json
auth-profiles.json 支持值级 refs（keyRef 用于 api_key，tokenRef 用于 token），用于静态凭证模式
旧的扁平 auth-profiles.json 映射如 { "provider": { "apiKey": "..." } } 不是运行时格式；openclaw doctor --fix 会将其重写为规范的 provider:default API-key 配置文件，并带有 .legacy-flat.*.bak 备份
OAuth 模式配置文件（auth.profiles.<id>.mode = "oauth"）不支持 SecretRef 支持的 auth-profile 凭证
静态运行时凭证来自内存解析快照；发现旧静态 auth.json 条目时被清理
旧 OAuth 从 ~/.openclaw/credentials/oauth.json 导入
见OAuth 文档
Secrets 运行时行为和 audit/configure/apply 工具：见Secrets Management

`auth.cooldowns`

json5

{
  auth: {
    cooldowns: {
      billingBackoffHours: 5,
      billingBackoffHoursByProvider: { anthropic: 3, openai: 8 },
      billingMaxHours: 24,
      authPermanentBackoffMinutes: 10,
      authPermanentMaxMinutes: 60,
      failureWindowHours: 24,
      overloadedProfileRotations: 1,
      overloadedBackoffMs: 0,
      rateLimitedProfileRotations: 1,
    },
  },
}

billingBackoffHours: 当配置文件因真实计费/信用不足错误失败时的基本回退小时数（默认 5）。即使 401/403 响应，显式计费文本仍可能落在此处，但提供者特定的文本匹配器保持作用域在拥有它们的提供者内（例如 OpenRouter Key limit exceeded）。可重试的 HTTP 402 使用窗口或组织/工作区消费限制消息保留在 rate_limit 路径中
billingBackoffHoursByProvider: 可选的每提供者覆盖计费回退小时数
billingMaxHours: 计费回退指数增长的上限小时数（默认 24）
authPermanentBackoffMinutes: 高置信度 auth_permanent 失败的基本回退分钟数（默认 10）
authPermanentMaxMinutes: auth_permanent 回退增长的上限分钟数（默认 60）
failureWindowHours: 用于回退计数器的滚动窗口小时数（默认 24）
overloadedProfileRotations: 过载错误的最大相同提供者 auth-profile 轮换次数，超过后切换到模型回退（默认 1）。提供者繁忙形状如 ModelNotReadyException 落在此处
overloadedBackoffMs: 重试过载提供者/profile 轮换前的固定延迟（默认 0）
rateLimitedProfileRotations: 速率限制错误的最大相同提供者 auth-profile 轮换次数，超过后切换到模型回退（默认 1）。该速率限制桶包括提供者形状文本如 Too many concurrent requests、ThrottlingException、concurrency limit reached、workers_ai ... quota limit exceeded 和 resource exhausted

Logging

json5

{
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log",
    consoleLevel: "info",
    consoleStyle: "pretty", // pretty | compact | json
    redactSensitive: "tools", // off | tools
    redactPatterns: ["\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1"],
  },
}

默认日志文件：/tmp/openclaw/openclaw-YYYY-MM-DD.log
设置 logging.file 以获得稳定路径
consoleLevel 在 --verbose 时提升到 debug
maxFileBytes: 轮换前最大活动日志文件大小（正整数；默认 104857600 = 100 MB）。OpenClaw 在活动文件旁保留最多五个编号归档
redactSensitive / redactPatterns: 尽力而为的掩码，用于控制台输出、文件日志、OTLP 日志记录和持久化的会话转录文本。redactSensitive: "off" 仅禁用此通用日志/转录策略；UI/工具/诊断安全表面在发出前仍会编辑机密

Diagnostics

json5

{
  diagnostics: {
    enabled: true,
    flags: ["telegram.*"],
    stuckSessionWarnMs: 30000,
    stuckSessionAbortMs: 300000,
    memoryPressureSnapshot: false,

    otel: {
      enabled: false,
      endpoint: "https://otel-collector.example.com:4318",
      tracesEndpoint: "https://traces.example.com/v1/traces",
      metricsEndpoint: "https://metrics.example.com/v1/metrics",
      logsEndpoint: "https://logs.example.com/v1/logs",
      protocol: "http/protobuf", // http/protobuf | grpc
      headers: { "x-tenant-id": "my-org" },
      serviceName: "openclaw-gateway",
      traces: true,
      metrics: true,
      logs: false,
      sampleRate: 1.0,
      flushIntervalMs: 5000,
      captureContent: {
        enabled: false,
        inputMessages: false,
        outputMessages: false,
        toolInputs: false,
        toolOutputs: false,
        systemPrompt: false,
      },
    },

    cacheTrace: {
      enabled: false,
      filePath: "~/.openclaw/logs/cache-trace.jsonl",
      includeMessages: true,
      includePrompt: true,
      includeSystem: true,
    },
  },
}

enabled: 仪表输出主开关（默认 true）
flags: 启用定向日志输出的标志字符串数组（支持通配符如 "telegram.*" 或 "*"）
stuckSessionWarnMs: 无进度年龄阈值 ms，用于将长时间运行的处理会话分类为 session.long_running、session.stalled 或 session.stuck。回复、工具、状态、块和 ACP 进度重置计时器；重复的 session.stuck 诊断在未更改时回退
stuckSessionAbortMs: 无进度年龄阈值 ms，在此之后符合条件的停滞活动工作可能被中止排空以恢复。未设置时，OpenClaw 使用更安全的扩展嵌入式运行窗口，至少 5 分钟和 3x stuckSessionWarnMs
memoryPressureSnapshot: 当内存压力达到 critical 时捕获编辑后的 OOM 前稳定性快照（默认 false）。设置为 true 以在保持正常内存压力事件的同时添加稳定性包文件扫描/写入
otel.enabled: 启用 OpenTelemetry 导出管道（默认 false）。完整配置、信号目录和隐私模型见 OpenTelemetry export
otel.endpoint: OTel 导出的收集器 URL
otel.tracesEndpoint / otel.metricsEndpoint / otel.logsEndpoint: 可选的信号专用 OTLP 端点。设置时它们会覆盖该信号的 otel.endpoint
otel.protocol: "http/protobuf"（默认）或 "grpc"
otel.headers: 随 OTel 导出请求发送的额外 HTTP/gRPC 元数据标头
otel.serviceName: 资源属性的服务名称
otel.traces / otel.metrics / otel.logs: 启用 trace、metrics 或 log 导出
otel.sampleRate: trace 采样率 0-1
otel.flushIntervalMs: 周期性遥测刷新间隔 ms
otel.captureContent: 选择加入的原始内容捕获用于 OTEL span 属性。默认关闭。布尔 true 捕获非系统消息/工具内容；对象形式允许显式启用 inputMessages、outputMessages、toolInputs、toolOutputs 和 systemPrompt
OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental: 环境切换，用于最新的实验性 GenAI span Provider 属性。默认情况下 span 保持旧的 gen_ai.system 属性以确保兼容性；GenAI metrics 使用有界的语义属性
OPENCLAW_OTEL_PRELOADED=1: 环境切换，用于已注册全局 OpenTelemetry SDK 的主机。OpenClaw 然后跳过插件拥有的 SDK 启动/关闭，同时保持诊断监听器活动
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT、OTEL_EXPORTER_OTLP_METRICS_ENDPOINT 和 OTEL_EXPORTER_OTLP_LOGS_ENDPOINT: 信号专用端点环境变量，当匹配的配置键未设置时使用
cacheTrace.enabled: 为嵌入式运行记录缓存 trace 快照（默认 false）
cacheTrace.filePath: 缓存 trace JSONL 的输出路径（默认 $OPENCLAW_STATE_DIR/logs/cache-trace.jsonl）
cacheTrace.includeMessages / includePrompt / includeSystem: 控制 cache trace 输出中包含哪些内容（全部默认 true）

Update

json5

{
  update: {
    channel: "stable", // stable | beta | dev
    checkOnStart: true,

    auto: {
      enabled: false,
      stableDelayHours: 6,
      stableJitterHours: 12,
      betaCheckIntervalHours: 1,
    },
  },
}

channel: 用于 npm/git 安装的发布渠道 - "stable"、"beta" 或 "dev"
checkOnStart: 当 gateway 启动时检查 npm 更新（默认 true）
auto.enabled: 启用包安装的后台自动更新（默认 false）
auto.stableDelayHours: stable 渠道自动应用的最小延迟小时数（默认 6；最大 168）
auto.stableJitterHours: 额外的 stable 渠道推出分散窗口小时数（默认 12；最大 168）
auto.betaCheckIntervalHours: beta 渠道检查运行频率小时数（默认 1；最大 24）

ACP

json5

{
  acp: {
    enabled: true,
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "main",
    allowedAgents: ["main", "ops"],
    maxConcurrentSessions: 10,

    stream: {
      coalesceIdleMs: 50,
      maxChunkChars: 1000,
      repeatSuppression: true,
      deliveryMode: "live", // live | final_only
      hiddenBoundarySeparator: "paragraph", // none | space | newline | paragraph
      maxOutputChars: 50000,
      maxSessionUpdateChars: 500,
    },

    runtime: {
      ttlMinutes: 30,
    },
  },
}

enabled: 全局 ACP 功能开关（默认 true；设为 false 隐藏 ACP 调度和 spawn 能力）
dispatch.enabled: ACP 会话轮次调度的独立开关（默认 true）。设为 false 保持 ACP 命令可用同时阻止执行
backend: 默认 ACP 运行时后端 ID（必须匹配已注册的 ACP 运行时插件）。先安装后端插件，如果设置了 plugins.allow 请包含后端插件 ID（例如 acpx），否则 ACP 后端不会加载
defaultAgent: 当 spawn 未指定显式目标时的回退 ACP 目标智能体 ID
allowedAgents: ACP 运行时会话允许的智能体 ID 列表；空表示无额外限制
maxConcurrentSessions: 同时活动的最大 ACP 会话数
stream.coalesceIdleMs: 流式文本的空闲刷新窗口 ms
stream.maxChunkChars: 在分割流式块投影前的最大块大小
stream.repeatSuppression: 每轮抑制重复的状态/工具行（默认 true）
stream.deliveryMode: "live" 增量流式；"final_only" 缓冲直到轮次终端事件
stream.hiddenBoundarySeparator: 隐藏工具事件后在可见文本前的分隔符（默认 "paragraph"）
stream.maxOutputChars: 每 ACP 轮次投影的最大助手输出字符数
stream.maxSessionUpdateChars: 投影的 ACP 状态/更新行的最大字符数
stream.tagVisibility: 标签名称到布尔可见性覆盖的记录，用于流式事件
runtime.ttlMinutes: ACP 会话工作者在符合条件的清理前空闲 TTL 分钟数
runtime.installCommand: 可选安装命令，在引导 ACP 运行时环境时运行

CLI

json5

{
  cli: {
    banner: {
      taglineMode: "off", // random | default | off
    },
  },
}

cli.banner.taglineMode 控制横幅标语样式：
- "random"（默认）: 旋转有趣/季节性标语
- "default": 固定中性标语（All your chats, one OpenClaw.）
- "off": 无标语文本（横幅标题/版本仍显示）
隐藏整个横幅（不只是标语），设置环境变量 OPENCLAW_HIDE_BANNER=1

Wizard

CLI 引导设置流程（onboard、configure、doctor）写入元数据：

json5

{
  wizard: {
    lastRunAt: "2026-01-01T00:00:00.000Z",
    lastRunVersion: "2026.1.4",
    lastRunCommit: "abc1234",
    lastRunCommand: "configure",
    lastRunMode: "local",
  },
}

Identity

见智能体默认值中的 agents.list 身份字段。

Bridge (legacy, removed)

当前构建不再包含 TCP 桥接。节点通过 Gateway WebSocket 连接。bridge.* 键已不在配置 schema 中（验证失败直到移除；openclaw doctor --fix 可以剥离未知键）。

旧桥接配置（历史参考）

json

{
  "bridge": {
    "enabled": true,
    "port": 18790,
    "bind": "tailnet",
    "tls": {
      "enabled": true,
      "autoGenerate": true
    }
  }
}

Cron

json5

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2, // cron 分发 + 隔离的 cron 智能体轮次执行
    webhook: "https://example.invalid/legacy", // 用于存储的 notify:true 作业的弃用回退
    webhookToken: "replace-with-dedicated-token", // 出站 webhook 认证的可选 bearer token
    sessionRetention: "24h", // 持续时间字符串或 false
    runLog: {
      maxBytes: "2mb", // 默认 2_000_000 字节
      keepLines: 2000, // 默认 2000
    },
  },
}

sessionRetention: 完成隔离 cron 运行时会话在从 sessions.json 修剪前保留多久。也控制已归档删除的 cron 转录本的清理。默认 24h；设为 false 禁用
runLog.maxBytes: 每次运行日志文件 (cron/runs/<jobId>.jsonl) 在修剪前的最大大小。默认 2_000_000 字节
runLog.keepLines: 运行日志修剪触发时保留的最新行数。默认 2000
webhookToken: 用于 cron webhook POST 投递的 bearer token（delivery.mode = "webhook"），如果省略则不发送 auth 标头
webhook: 弃用的旧回退 webhook URL（http/https），仅用于仍有 notify: true 的存储作业

`cron.retry`

json5

{
  cron: {
    retry: {
      maxAttempts: 3,
      backoffMs: [30000, 60000, 300000],
      retryOn: ["rate_limit", "overloaded", "network", "timeout", "server_error"],
    },
  },
}

maxAttempts: 一次性作业在瞬态错误时的最大重试次数（默认 3；范围 0-10）
backoffMs: 每次重试尝试的回退延迟数组 ms（默认 [30000, 60000, 300000]；1-10 个条目）
retryOn: 触发重试的错误类型 - "rate_limit"、"overloaded"、"network"、"timeout"、"server_error"。省略以重试所有瞬态类型

仅适用于一次性 cron 作业。重复作业使用单独的错误处理。

`cron.failureAlert`

json5

{
  cron: {
    failureAlert: {
      enabled: false,
      after: 3,
      cooldownMs: 3600000,
      includeSkipped: false,
      mode: "announce",
      accountId: "main",
    },
  },
}

enabled: 启用 cron 作业的失败告警（默认 false）
after: 告警触发前的连续失败次数（正整数，最小 1）
cooldownMs: 相同作业的重复告警之间的最小毫秒数（非负整数）
includeSkipped: 将连续跳过运行计入告警阈值（默认 false）。跳过运行单独跟踪，不影响执行错误回退
mode: 投递模式 - "announce" 通过渠道消息发送；"webhook" 发布到配置的 webhook
accountId: 可选的范围告警投递的账户或渠道 ID

`cron.failureDestination`

json5

{
  cron: {
    failureDestination: {
      mode: "announce",
      channel: "last",
      to: "channel:C1234567890",
      accountId: "main",
    },
  },
}

所有作业 cron 失败通知的默认目标
mode: "announce" 或 "webhook"；当有足够目标数据时默认 "announce"
channel: 用于 announce 投递的渠道覆盖。"last" 重用最后一个已知投递渠道
to: 显式 announce 目标或 webhook URL。webhook 模式必需
accountId: 可选投递账户覆盖
每作业 delivery.failureDestination 覆盖此全局默认值
当既没有全局也没有每作业失败目标设置时，已经通过 announce 投递的作业会在失败时回退到那个主要 announce 目标
delivery.failureDestination 仅支持 sessionTarget="isolated" 作业，除非作业的主要 delivery.mode 是 "webhook"

见 Cron 作业。隔离 cron 执行作为后台任务跟踪。

Media model template variables

在 tools.media.models[].args 中展开的模板占位符：

变量	描述
`{{Body}}`	完整入站消息正文
`{{RawBody}}`	原始正文（无历史/发送者包装）
`{{BodyStripped}}`	去除群组提及后的正文
`{{From}}`	发送者标识符
`{{To}}`	目标标识符
`{{MessageSid}}`	渠道消息 ID
`{{SessionId}}`	当前会话 UUID
`{{IsNewSession}}`	新会话创建时为 `"true"`
`{{MediaUrl}}`	入站媒体伪 URL
`{{MediaPath}}`	本地媒体路径
`{{MediaType}}`	媒体类型（image/audio/document/…）
`{{Transcript}}`	音频转录本
`{{Prompt}}`	用于 CLI 条目的解析媒体提示
`{{MaxChars}}`	用于 CLI 条目的解析最大输出字符数
`{{ChatType}}`	`"direct"` 或 `"group"`
`{{GroupSubject}}`	群组主题（尽力而为）
`{{GroupMembers}}`	群组成员预览（尽力而为）
`{{SenderName}}`	发送者显示名称（尽力而为）
`{{SenderE164}}`	发送者电话号码（尽力而为）
`{{Provider}}`	提供者提示（whatsapp、telegram、discord 等）

Config includes (`$include`)

将配置拆分为多个文件：

json5

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

合并行为：

单个文件：替换包含该键的对象
文件数组：按顺序深层合并（后者覆盖前者）
兄弟键：包含后合并（覆盖包含的值）
嵌套包含：最多 10 层深度
路径：相对于包含的文件解析，但必须保持在顶级配置目录内（openclaw.json 的 dirname）。允许绝对路径/../ 形式，只要它们仍解析到该边界内
OpenClaw 拥有的 writes 只更改一个由单个文件包含支持的顶级部分，会写入到该包含文件。例如，plugins install 更新 plugins: { $include: "./plugins.json5" } 在 plugins.json5 中，而 openclaw.json 保持完整
根包含、包含数组和带兄弟覆盖的包含对于 OpenClaw 拥有的 writes 是只读的；这些 writes 会失败关闭，而不是扁平化配置
错误：对缺失文件、解析错误和循环包含有清晰的消息

关联：配置 · 配置示例 · Doctor

常见问题

配置文件路径是什么？

~/.openclaw/openclaw.json。也可以使用 OPENCLAW_CONFIG_PATH 环境变量覆盖。

所有字段都要写吗？不写会怎样？

所有字段都是可选的。OpenClaw 有安全的默认值。你通常只需要配置渠道 token 和 gateway 认证就能跑起来。运行 openclaw onboard 可以交互式生成最小配置。

修改配置后需要重启 Gateway 吗？

大多数更改需要重启 openclaw gateway restart。部分配置（如 mcp.* 更改）热生效。渠道配置、插件配置、钩子配置都需要重启 Gateway。

OpenClaw 配置参考：openclaw.json 所有字段完整说明 ​

Channels ​

Agent defaults, multi-agent, sessions, and messages ​

Tools and custom providers ​

Models ​

MCP ​

Skills ​

Plugins ​

Codex harness plugin config ​

Commitments ​

Browser ​

UI ​

Gateway ​

OpenAI-compatible endpoints ​

Multi-instance isolation ​

gateway.tls ​

gateway.reload ​

Hooks ​

Gmail integration ​

Canvas plugin host ​

Discovery ​

mDNS (Bonjour) ​

Wide-area (DNS-SD) ​

Environment ​

env (inline env vars) ​

Env var substitution ​

Secrets ​

SecretRef ​

支持的凭证表面 ​

Secret providers config ​

Auth storage ​

auth.cooldowns ​

Logging ​

Diagnostics ​

Update ​

ACP ​

CLI ​

Wizard ​

Identity ​

Bridge (legacy, removed) ​

Cron ​

cron.retry ​

cron.failureAlert ​

cron.failureDestination ​

Media model template variables ​

Config includes ($include) ​

常见问题 ​

配置文件路径是什么？ ​

所有字段都要写吗？不写会怎样？ ​

修改配置后需要重启 Gateway 吗？ ​

OpenClaw 配置参考：openclaw.json 所有字段完整说明

Channels

Agent defaults, multi-agent, sessions, and messages

Tools and custom providers

Models

MCP

Skills

Plugins

Codex harness plugin config

Commitments

Browser

UI

Gateway

OpenAI-compatible endpoints

Multi-instance isolation

`gateway.tls`

`gateway.reload`

Hooks

Gmail integration

Canvas plugin host

Discovery

mDNS (Bonjour)

Wide-area (DNS-SD)

Environment

`env` (inline env vars)

Env var substitution

Secrets

`SecretRef`

支持的凭证表面

Secret providers config

Auth storage

`auth.cooldowns`

Logging

Diagnostics

Update

ACP

CLI

Wizard

Identity

Bridge (legacy, removed)

Cron

`cron.retry`

`cron.failureAlert`

`cron.failureDestination`

Media model template variables

Config includes (`$include`)

常见问题

配置文件路径是什么？

所有字段都要写吗？不写会怎样？

修改配置后需要重启 Gateway 吗？