Configuration reference

• plugins.entries.codex.config.codexPlugins.enabled：为 Codex harness 启用原生 Codex plugin/app 支持。默认值：false。
• plugins.entries.codex.config.codexPlugins.allow_all_plugins：将当前已认证 Codex 账户中所有可访问的 app 暴露给每个新的原生 Codex thread。默认值：false。
• plugins.entries.codex.config.codexPlugins.allow_destructive_actions：已配置插件 app 请求的默认破坏性操作策略。使用 true 可在不提示的情况下接受安全的 Codex 审批 schema，使用 false 拒绝这些请求，使用 "auto" 将 Codex 所需的审批路由到 OpenClaw 插件审批，或使用 "ask" 在没有持久化审批的情况下，对每个插件写入／破坏性操作进行提示。"ask" 模式会清除受影响 app 的持久化 Codex 按工具审批覆盖值，并在 Codex thread 启动前为该 app 选择人工审批审核者。默认值：true。
• plugins.entries.codex.config.codexPlugins.plugins.<key>.enabled：当全局 codexPlugins.enabled 同时为 true 时，启用已配置的插件条目。默认值：显式条目为 true。
• plugins.entries.codex.config.codexPlugins.plugins.<key>.marketplaceName：稳定的 marketplace 身份。每个已解析条目都必须与 pluginName 一起提供该字段。支持 Codex 已发现的任何有效 marketplace，包括 "openai-curated"、"openai-bundled"、"openai-primary-runtime"、"workspace-directory" 以及仓库本地 marketplace 身份。缺少任一身份字段的条目会被忽略。
• plugins.entries.codex.config.codexPlugins.plugins.<key>.pluginName：稳定的 Codex 插件身份，必须与 marketplaceName 一起提供。对于插件标识符带有 marketplace 限定的 marketplace，请使用 Codex 报告的确切身份。/codex plugins available 会列出可发现的身份，所有者或 operator.admin 可以使用 /codex plugins install <plugin>@<marketplace> 安装插件。
• plugins.entries.codex.config.codexPlugins.plugins.<key>.allow_destructive_actions：按插件设置的破坏性操作覆盖值。省略时使用全局 allow_destructive_actions 值。按插件设置的值接受相同的 true、false、"auto" 或 "ask" 策略。

​

桌面

{
  desktop: {
    host: {
      enabled: true,
      managed: true,
      // port: 5900, // Setting a port selects attach mode instead.
      // passwordFile: "/path/to/vnc-password.txt",
    },
  },
}

• desktop.host.enabled：Gateway 重启后，将此机器公布为桌面源。
• desktop.host.managed：仅限 Linux。在首次观察时延迟启动由 Gateway 管理、仅限回环地址的 TigerVNC/XFCE 桌面，并在桌面会话的保持时间结束后停止。默认值：false。
• desktop.host.port：127.0.0.1 上的回环 RFB 端口（默认值：5900）。
• desktop.host.passwordFile：附加模式下可选的 UTF-8 VNC 密码文件。未提供时，控制界面会提示输入 VNC 密码，并将其保存在浏览器内存中，直到该连接结束。管理模式始终创建自己的临时密码。

​

配对节点桌面

{
  desktop: {
    host: {
      enabled: true,
      port: 5900,
      // passwordFile: "/path/to/vnc-password.txt",
    },
  },
}

{
  gateway: {
    nodes: {
      commands: {
        allow: ["desktop.stream"],
        // deny: ["desktop.stream"], // deny always wins
      },
    },
  },
}

​

Gateway

{
  gateway: {
    mode: "local", // 本地 | 远程
    port: 18789,
    bind: "loopback",
    publicOrigin: "https://gateway.example.com",
    auth: {
      mode: "token", // 无 | 令牌 | 密码 | 可信代理
      token: "your-token",
      // password: "your-password", // 或 OPENCLAW_GATEWAY_PASSWORD
      // trustedProxy: { userHeader: "x-forwarded-user" }, // 适用于 mode=trusted-proxy；见 /gateway/trusted-proxy-auth
      allowTailscale: true,
      identityScopes: {
        "[email protected]": ["operator.admin"],
      },
      rateLimit: {
        maxAttempts: 10,
        windowMs: 60000,
        lockoutMs: 300000,
        exemptLoopback: true,
      },
    },
    tailscale: {
      mode: "off", // 关闭 | 提供服务 | 漏斗
      resetOnExit: false,
    },
    controlUi: {
      enabled: true,
      basePath: "/openclaw",
      // root: "dist/control-ui",
      // toolTitles: false, // 为工具调用启用面向 AI 用途的标题（会消耗实用模型令牌）
      // embedSandbox: "scripts", // strict | scripts | trusted
      // allowExternalEmbedUrls: false, // 危险：允许绝对路径的外部 http(s) 嵌入 URL
      // allowedOrigins: ["https://control.example.com"], // 非回环 Control UI 必需
      // dangerouslyAllowHostHeaderOriginFallback: false, // 危险：Host 标头来源回退模式
    },
    cliAgents: {
      enabled: false, // 实验功能：在模型选择器中显示可创建会话的 CLI 会话目标
    },
    terminal: {
      enabled: false,
      // shell: "/bin/zsh",
    },
    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: {
        // 静默进行同主机配对和访问权限升级。默认：启用。
        // 设置为 false 后，每台设备都必须经过明确批准。
        autoApproveLocal: true,
        // 可选。默认未设置/禁用。
        autoApproveCidrs: ["192.168.1.0/24", "fd00:1234:5678::/64"],
        // 经 SSH 验证的自动批准。默认：启用（true）。
        // 设置为 false 仅禁用 SSH 验证；不会影响上面的
        // autoApproveCidrs。若要仅手动进行节点配对，请设置为 false 并且
        // 取消设置 autoApproveCidrs。传入对象可进行调整：{ user, identity,
        // timeoutMs, cidrs }。
        sshVerify: true,
      },
      commands: {
        allow: ["canvas.navigate"],
        deny: ["system.run"],
      },
    },
    tools: {
      // 额外的 /tools/invoke HTTP 拒绝项
      deny: ["browser"],
      // 从默认 HTTP 拒绝列表中移除工具，适用于 owner/admin 调用者
      allow: ["gateway"],
    },
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          timeoutMs: 10000,
        },
      },
    },
  },
}

​

OpenAI 兼容端点

• 管理员 HTTP RPC：默认作为 admin-http-rpc 插件关闭。启用该插件以注册 POST /api/v1/admin/rpc。参见 管理员 HTTP RPC。
• Chat Completions：默认禁用。使用 gateway.http.endpoints.chatCompletions.enabled: true 启用。
• Responses API：gateway.http.endpoints.responses.enabled。
• Responses URL 输入加固：
  • 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 origin 设置；见 可信代理认证）。

​

多实例隔离

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

​

gateway.tls

{
  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：在网关监听器上启用 TLS 终止（HTTPS/WSS）（默认：false）。
• autoGenerate：未配置显式文件时，自动生成本地自签名证书/密钥对；仅供本地/开发环境使用。生成的文件会在不覆盖现有路径的情况下发布，并且在文件系统支持时同步其父目录；不支持目录刷新时会发出结构化的持久性降级警告。
• certPath：TLS 证书文件的文件系统路径。
• keyPath：TLS 私钥文件的文件系统路径；请限制其访问权限。
• caPath：可选的 CA 证书包路径，用于客户端验证或自定义信任链。

​

gateway.reload

{
  gateway: {
    reload: {
      mode: "hybrid", // off | hybrid
    },
  },
}

• mode：控制配置编辑在运行时的应用方式。
  • "off"：忽略实时编辑；更改需要显式重启。
  • "hybrid"（默认）：在进程内应用可热更新的更改，然后在更改需要重启时执行重启。

​

云工作器环境

​

Crabbox 配置

{
  cloudWorkers: {
    profiles: {
      production: {
        provider: "crabbox",
        install: "bundle", // 默认值；仅对已发布的 gateway 版本使用 "npm"。
        settings: {
          provider: "aws",
          class: "standard",
          ttl: "24h",
          idleTimeout: "60m",
          // 可选的绝对路径。默认为同级 ../crabbox/bin/crabbox，然后查找 PATH。
          binary: "/usr/local/bin/crabbox",
        },
      },
    },
  },
}

• settings.provider（必需）：通过 --provider 传入的 Crabbox 后端。请使用其 inspect 输出包含 SSH 端点的后端；aws 会选择直接 AWS 后端。
• settings.class（必需）：通过 --class 传入的 Crabbox 机器类别。
• settings.ttl 和 settings.idleTimeout（必需）：作为提供商侧故障保护措施，通过 --ttl 和 --idle-timeout 传入的正数 Go duration 字符串。
• settings.binary：可选的 Crabbox 可执行文件绝对路径。如果未设置，OpenClaw 会依次检查同级的 Crabbox checkout、PATH 中的可执行文件，最后调用 crabbox，因此缺少 CLI 时仍会显示为可见的提供商错误。

​

静态 SSH 开发配置

{
  cloudWorkers: {
    profiles: {
      development: {
        provider: "static-ssh",
        settings: {
          host: "worker.example.test",
          port: 22,
          user: "openclaw",
          hostKey: "ssh-ed25519 <base64-public-host-key>",
          keyRef: {
            source: "env",
            provider: "default",
            id: "OPENCLAW_WORKER_SSH_KEY",
          },
        },
      },
    },
  },
}

• profiles：具有非空、去除首尾空白的 id 的命名工作器配置。每个配置选择一个由插件注册的提供商。
• provider：非空的工作器提供商 id。示例使用内置的 crabbox 提供商和 QA Lab 的 static-ssh 提供商。
• install：工作器安装方式。"bundle"（默认）会传输包含 Gateway 已安装构建版本的内容哈希 bundle，并支持已发布、开发中及未发布的版本。"npm" 是针对未修改的打包发行版的可选优化；它会从公共 npm registry 安装 openclaw@<exact gateway version>，绝不会安装 latest。
• 配置时会自动选择捆绑的提供商插件，但显式禁用和 plugins.allow 仍然适用。配置允许列表时，请包含提供商 id（例如 crabbox）。外部提供商插件还必须安装并显式启用。
• settings：由提供商管理的有界 JSON。所选插件定义并验证其中的键；对于包含机密的值，请使用 SecretRef 对象。静态 SSH 提供商要求 host、user、hostKey 和 keyRef；port 默认为 22。hostKey 必须是从已知主机或其他受信任渠道获取的一行 OpenSSH 公共主机密钥（algorithm base64），且不得带有选项前缀。

​

钩子

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: true,
    allowedSessionKeyPrefixes: ["hook:", "hook:gmail:"],
    allowedAgentIds: ["hooks", "main"],
    presets: ["gmail"],
    transformsDir: "~/.openclaw/hooks/transforms",
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        // 在 agents.entries 下为此代理配置受限的工具
        // 配置文件和沙箱，然后再将不受信任的内容路由给它。
        agentId: "hooks",
        wakeMode: "now",
        name: "Gmail",
        sessionKey: "hook:gmail:{{messages[0].id}}",
        sessionMode: "persistent",
        messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}",
        deliver: true,
        channel: "last",
        model: "openai/gpt-5.6-sol",
      },
    ],
  },
}

• hooks.enabled=true 需要一个非空的 hooks.token。
• hooks.token 应与活动的 Gateway 共享密钥认证（gateway.auth.token / OPENCLAW_GATEWAY_TOKEN 或 gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD）不同；当检测到复用时，启动日志会输出非致命的安全警告。
• openclaw security audit 会将 hook/Gateway 认证复用标记为严重问题，包括仅在审计时提供的 Gateway 密码认证（--auth password --password <password>）。运行 openclaw doctor --fix 可轮换持久化的复用 hooks.token，然后更新外部 hook 发送方以使用新的 hook token。
• hooks.path 不能是 /；请使用专用子路径，例如 /hooks。
• 如果 hooks.allowRequestSessionKey=true，请限制 hooks.allowedSessionKeyPrefixes（例如 ["hook:"]）。
• 如果某个 mapping 或 preset 使用了模板化的 sessionKey，请设置 hooks.allowedSessionKeyPrefixes 和 hooks.allowRequestSessionKey=true。静态 mapping key 不需要该显式开启。

• POST /hooks/wake → { text, mode?: "now"|"next-heartbeat" }
• POST /hooks/agent → { message, name?, agentId?, sessionKey?, sessionMode?, wakeMode?, deliver?, channel?, to?, accountId?, model?, thinking?, timeoutSeconds? }
  • 请求负载中的 sessionKey 仅在 hooks.allowRequestSessionKey=true 时接受（默认值：false）。
  • sessionMode 默认为 "isolated"。"persistent" 会复用已解析的会话，并要求请求中显式提供 sessionKey、hooks.allowRequestSessionKey=true，以及非空的 hooks.allowedSessionKeyPrefixes。
  • 直接公告投递同时要求提供具体的 channel 和 to；只提供其中一个会在运行调度前失败。
  • accountId 会选择一个已配置且启用的账户进行直接公告投递，并要求同时提供 channel 和 to；无效选择会在运行开始前返回 400。
  • 对于仅完成通知的 hook，可省略两个投递字段；也可以设置 deliver: false 以忽略提供的目标数据。
  • 请求最多等待 15 秒以进入运行器，而不会等待运行完成。200 表示代理运行器已进入。
  • 运行前失败会返回 { ok: false, error, runId }：无效的投递坐标或账户选择返回 400，会话接入冲突返回 409，其他准备失败返回 502，15 秒接入期限到期返回 503。超时的排队任务会被取消，之后不会启动。
• POST /hooks/<name> → 通过 hooks.mappings 解析
  • 模板渲染的 mapping sessionKey 值会被视为外部提供的值，同样要求 hooks.allowRequestSessionKey=true。
  • 映射的 agent 操作使用相同的接入等待机制，并返回 200／400／409／502／503 结果。

​

Gmail 集成

• 内置 Gmail preset 使用 sessionKey: "hook:gmail:{{messages[0].id}}"。
• 此按消息分配的密钥会隔离会话上下文，但不会隔离工具或工作区访问权限。没有设置 agentId 的自定义 mapping 时，preset 会使用默认代理。
• 对于不受信任的收件箱，请将 Gmail 路由到专用的读取代理，并根据每个代理的沙箱和工具策略限制该代理。如果读取代理必须通知主代理，请使用 tools.agentToAgent限制交接。有关推荐的威胁模型和模型层级，请参阅提示注入。
• 设置向导会配置 Gmail 传输，但不会创建读取代理或所需的会话密钥策略。对于不受信任的邮件，请在运行设置前应用完整的受限 Gmail 读取代理配置。
• 如果保留按消息路由，请设置 hooks.allowRequestSessionKey: true，并将 hooks.allowedSessionKeyPrefixes 限制为匹配 Gmail 命名空间的前缀，例如 ["hook:", "hook:gmail:"]。
• 如果需要 hooks.allowRequestSessionKey: false，请使用静态 sessionKey 覆盖 preset，而不是使用模板化的默认值。

{
  hooks: {
    gmail: {
      account: "[email protected]",
      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: "openai/gpt-5.6-sol",
      thinking: "high",
    },
  },
}

• 配置完成后，Gateway 会在启动时自动启动 gog gmail watch serve。设置 OPENCLAW_SKIP_GMAIL_WATCHER=1 可禁用。
• 不要在 Gateway 旁边再单独运行一个 gog gmail watch serve。

​

Canvas 插件宿主

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

• 通过网关端口经 HTTP 提供智能体可编辑的 HTML/CSS/JS 和 A2UI：
  • http://<gateway-host>:<gateway.port>/__openclaw__/canvas/
  • http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/
• 仅本地可访问：保持 gateway.bind: "loopback"（默认）。
• 非 loopback 绑定：canvas 路由需要网关认证（token/password/trusted-proxy），与其他网关 HTTP 接口相同。
• Node WebView 通常不会发送认证头；当节点完成配对并连接后，网关会为 canvas/A2UI 访问公开按节点范围限定的能力 URL。
• 能力 URL 绑定到当前激活的节点 WS 会话，并会快速过期。不使用基于 IP 的回退。
• 在提供的 HTML 中注入实时重载客户端。
• 在目录为空时自动创建入门版 index.html。
• 也会在 /__openclaw__/a2ui/ 提供 A2UI。
• 更改需要重启网关。
• 对于大型目录或 EMFILE 错误，请禁用实时重载。

​

发现

​

mDNS（Bonjour）

{
  discovery: {
    mdns: {
      mode: "minimal", // 最小 | 完整 | 关闭
    },
  },
}

• minimal（默认）：从 TXT 记录中省略 cliPath + sshPort。
• full：包含 cliPath + sshPort；局域网组播广播仍需要启用捆绑的 bonjour 插件。
• off：禁止局域网组播广播，但不改变插件启用状态。
• 捆绑的 bonjour 插件会在 macOS 主机上自动启动，在 Linux、Windows 和容器化 Gateway 部署中则需要选择启用。
• 当系统主机名是有效的 DNS 标签时，默认使用该主机名，否则回退为 openclaw。可通过 OPENCLAW_MDNS_HOSTNAME 覆盖。
• OPENCLAW_DISABLE_BONJOUR=1 将直接禁用 mDNS 广播，并覆盖 discovery.mdns.mode。

​

广域（DNS-SD）

{
  discovery: {
    wideArea: { domain: "openclaw.internal" },
  },
}

​

环境

​

env（内联环境变量）

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

• 只有当进程环境中缺少该键时，才会应用内联环境变量。
• .env 文件：CWD .env + ~/.openclaw/.env（都不会覆盖已有变量）。
• shellEnv：从你的登录 shell 配置文件中导入缺失的预期键。
• 完整优先级请参见 环境。

​

环境变量替换

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

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

​

密钥

​

SecretRef

{ source: "env" | "file" | "exec" | "store", 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 Pointer（例如 "/providers/openai/apiKey"）
• source: "exec" id 模式：^[A-Za-z0-9][A-Za-z0-9._:/#-]{0,255}$（支持 AWS 风格的 secret#json_key 选择器）
• source: "exec" 的 id 不能包含 . 或 .. 这样的斜杠分隔路径段（例如 a/../b 会被拒绝）

​

支持的凭据范围

• 规范矩阵：SecretRef 凭据范围
• secrets apply 目标是受支持的 openclaw.json 凭据路径。
• auth-profiles.json 引用会包含在运行时解析和审计覆盖范围内。

​

密钥提供方配置

{
  secrets: {
    providers: {
      default: { source: "env" }, // 可选的显式 env 提供方
      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 提供方支持 mode: "json" 和 mode: "singleValue"（在 singleValue 模式下，id 必须为 "value"）。
• Windows ACL 验证不可用时，文件和 exec 提供方路径会默认拒绝。请使用 OpenClaw 可以验证其 ACL 的路径；提供方级别不支持绕过此限制。
• exec 提供方要求使用绝对 command 路径，并通过标准输入/标准输出使用协议载荷。
• 符号链接命令路径会被拒绝。请改为配置解析后的绝对二进制文件路径。
• 如果配置了 trustedDirs，命令路径必须位于已批准的目录内。
• exec 子进程环境默认最小化；请使用 passEnv 显式传递所需变量。
• 密钥引用会在激活时解析为内存中的快照，之后请求路径仅读取该快照。
• 激活期间会应用活动范围过滤：启用范围内无法解析的引用会导致启动/重新加载失败，而非活动范围会跳过并记录诊断信息。

​

认证存储

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

• 每个 agent 的配置文件存储在 <agentDir>/auth-profiles.json。
• auth-profiles.json 支持值级引用（api_key 使用 keyRef，token 使用 tokenRef），适用于静态凭据模式。
• 旧式扁平 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。
• 密钥运行时行为以及 audit/configure/apply 工具： 密钥管理。

​

审计

{
  logging: {
    audit: {
      enabled: true,
      executionIdentity: false,
      messages: "off", // 关闭 | 直接 | 全部
    },
  },
}

• enabled：记录新的审计事件（默认值：true）。账本默认启用，因为只有在事件发生后才启用的审计跟踪无法解释该事件。设置为 false 后，Gateway 重启时将停止插入新事件；现有记录会继续可读，直到过期。重新启用后会从该时间点恢复记录——空缺部分不会补录。
• executionIdentity：保留受限的归因上下文，以便进行精确的执行检查（默认值：false）。此隐私敏感元数据在全新安装和升级时均处于禁用状态。收集该元数据需要 enabled: true；使用 openclaw config set logging.audit.executionIdentity true，然后重启 Gateway。没有对应的环境变量别名。
• messages：消息元数据范围（默认值："off"）。"direct" 仅记录已知的直接对话。"all" 还会记录群组、频道和未知的对话类型。两种模式都不会包含内容，并会在可以进行关联的情况下使用安装本地的密钥伪名替换原始标识符。这些是关联辅助信息，而非匿名化措施；状态数据库会存储派生密钥，但 RPC 和 CLI 导出不会包含该密钥。

​

日志记录

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

• 默认日志文件：/tmp/openclaw/openclaw-YYYY-MM-DD.log；命名配置文件使用 /tmp/openclaw/openclaw-<profile>-YYYY-MM-DD.log。
• 设置 logging.file 以使用稳定路径。
• 使用 --verbose 时，consoleLevel 会提升为 debug。
• consoleStyle："pretty" 或 "json"。之前的 "compact" 值已弃用；openclaw doctor --fix 会将其映射为 "pretty"。
• maxFileBytes：轮换前活动日志文件的最大字节数（正整数；默认值：104857600 = 100 MB）。OpenClaw 会在活动文件旁最多保留五个带编号的归档文件。
• redactPatterns：用于尽力遮盖控制台输出、文件日志、OTLP 日志记录以及持久化会话记录文本的正则表达式。设置此项会替换日志和会话记录输出的内置默认模式，因此请包含你仍希望使用的默认模式；省略它们还会关闭表单正文和结构化身份验证标头的遮盖。工具负载遮盖是独立的，并且始终会将你的模式与默认模式合并。
• 遮盖始终启用，且不再可配置。openclaw doctor --fix 会从旧版配置文件中移除已弃用的开关；运行时始终对日志和会话记录应用 tools 模式的遮盖。UI、工具和诊断安全界面会独立于此策略遮盖机密信息。

​

诊断

{
  diagnostics: {
    enabled: true,
    flags: ["telegram.*"],

    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",
      headers: { "x-tenant-id": "my-org" },
      serviceName: "openclaw-gateway",
      traces: true,
      metrics: true,
      logs: false,
      logsExporter: "otlp",
      sampleRate: 1.0,
      flushIntervalMs: 5000,
      captureContent: false,
    },

    cacheTrace: {
      enabled: false,
    },
  },
}

• enabled：检测输出的主开关（默认值：true）。
• flags：启用定向日志输出的标志字符串数组（支持 "telegram.*" 或 "*" 等通配符）。
• otel.enabled：启用 OpenTelemetry 导出管道（默认值：false）。完整配置、信号目录和隐私模型请参阅 OpenTelemetry 导出。
• otel.endpoint：OTel 导出的收集器 URL。
• otel.tracesEndpoint / otel.metricsEndpoint / otel.logsEndpoint：可选的按信号区分的 OTLP 端点。设置后，仅对相应信号覆盖 otel.endpoint。
• otel.protocol："http/protobuf"（默认值）。gRPC 导出已停用；运行 openclaw doctor --fix 可修复已持久化的旧值，或获取特定来源的手动编辑指导。
• otel.headers：随 OTel 导出请求发送的额外 HTTP 请求标头。
• otel.serviceName：资源属性中的服务名称。
• otel.traces / otel.metrics / otel.logs：启用追踪、指标或日志导出。
• otel.logsExporter：日志导出目标："otlp"（默认值）、"stdout"（每行标准输出一个 JSON 对象）或 "both"。
• otel.sampleRate：0-1 之间的追踪采样率。
• otel.flushIntervalMs：遥测数据定期刷新的间隔（单位：毫秒）。
• otel.captureContent：选择性启用 OTEL span 属性中的内容捕获。默认关闭。true 会捕获非系统可见的消息、工具和工具定义内容，以及 OTLP 日志正文；供应商内部的思考负载仍会被排除。
• OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental：启用最新实验性 GenAI 推理 span 形态的环境开关，包括使用 {gen_ai.operation.name} {gen_ai.request.model} 作为 span 名称、使用 CLIENT span 类型，以及使用 gen_ai.provider.name 替代旧版 gen_ai.system。默认情况下，为保持兼容性，span 仍使用 openclaw.model.call 和 gen_ai.system；GenAI 指标使用有界语义属性。
• OPENCLAW_OTEL_PRELOADED=1：适用于已注册全局 OpenTelemetry SDK 的主机的环境开关。启用后，OpenClaw 会跳过由插件负责的 SDK 启动和关闭，同时保持诊断监听器处于活动状态。
• OTEL_EXPORTER_OTLP_TRACES_ENDPOINT、OTEL_EXPORTER_OTLP_METRICS_ENDPOINT 和 OTEL_EXPORTER_OTLP_LOGS_ENDPOINT：当对应配置项未设置时使用的按信号区分的端点环境变量。
• OTEL_EXPORTER_OTLP_TRACES_PROTOCOL、OTEL_EXPORTER_OTLP_METRICS_PROTOCOL 和 OTEL_EXPORTER_OTLP_LOGS_PROTOCOL：当 otel.protocol 未设置时使用的按信号区分的协议回退值。每个变量都会针对相应信号覆盖 OTEL_EXPORTER_OTLP_PROTOCOL。
• OTEL_EXPORTER_OTLP_PROTOCOL：当 otel.protocol 和对应的按信号区分的变量均未设置时使用的共享协议回退值。仅支持 http/protobuf。协议验证按信号隔离，因此不受支持的解析值会禁用相应信号的 OTLP 导出器，而不会阻止其他受支持的同级信号。Doctor 不会重写环境变量。
• cacheTrace.enabled：记录嵌入式运行的缓存追踪快照（默认值：false）。

​

更新

{
  update: {
    channel: "stable", // 稳定版 | 扩展稳定版 | 测试版 | 开发版
    checkOnStart: true,

    auto: {
      enabled: false,
    },
  },
}

• channel：发布渠道——"stable"、"extended-stable"、"beta" 或 "dev"。扩展稳定版仅适用于软件包：前台命令负责安装，而网关可以发出只读更新提示。
• checkOnStart：网关启动时检查 npm 更新（默认值：true）。选择扩展稳定版时，同样使用只读提示和 24 小时提示计划。
• auto.enabled：为稳定版和测试版软件包安装，以及开发版 Git 安装启用后台自动更新任务（默认值：false）。扩展稳定版永远不会自动应用更新。

​

ACP

{
  acp: {
    enabled: true,
    dispatch: { enabled: true },
    backend: "acpx",
    fallbacks: ["acpx-secondary"],
    defaultAgent: "main",
    allowedAgents: ["main", "ops"],
    stream: {
      repeatSuppression: true,
      deliveryMode: "live", // 实时 | 仅最终结果
    },
  },
}

• enabled：全局 ACP 功能开关（默认值：true；设置为 false 可隐藏 ACP 调度和生成入口）。
• dispatch.enabled：ACP 会话轮次调度的独立开关（默认值：true）。设置为 false 可保留 ACP 命令，同时阻止执行。
• backend：默认 ACP 运行时后端 ID（必须与已注册的 ACP 运行时插件匹配）。 请先安装后端插件；如果设置了 plugins.allow，请将后端插件 ID（例如 acpx）加入其中，否则 ACP 后端将不会加载。
• fallbacks：备用 ACP 后端 ID 的有序列表。当主后端在产生任何输出之前因看似暂时性的错误（不可用、受到速率限制、配额耗尽或过载）而过早失败时，将按顺序尝试这些后端。每个条目都必须与已注册的 ACP 运行时插件后端匹配。
• defaultAgent：生成操作未指定明确目标时使用的备用 ACP 目标代理 ID。
• allowedAgents：允许用于 ACP 运行时会话的代理 ID 白名单；为空表示不施加额外限制。
• stream.repeatSuppression：抑制每个轮次中重复的状态/工具行（默认值：true）。
• stream.deliveryMode："live" 逐步流式传输；"final_only" 缓冲内容，直到轮次终止事件发生。
• stream.tagVisibility：流式事件中各标签名称对应布尔可见性覆盖设置的记录。
• runtime.installCommand：可选的安装命令，用于在引导 ACP 运行时环境时执行。

​

向导

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

• wizard.accessMode：在引导式入门开始时选择的发现授权。"full"（推荐）允许设置流程自动查找 AI 应用、密钥和本地运行时；"guarded" 会让设置流程在查找周边信息前先询问一次，并提供手动配置选项。
• wizard.appRecommendations 默认为 true。将其设置为 false，可在引导式或经典入门过程中禁用已安装应用推荐，并阻止 Gateway 访问 device.apps。Node 主机仍需启用单独的、默认关闭的已安装应用共享标志，之后才会发布该命令。

​

身份

​

桥接（旧版，已移除）

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

​

自动化（cron）

{
  cron: {
    enabled: true,
    triggers: {
      enabled: true,
    },
    webhookToken: "replace-with-dedicated-token", // 可选，用于出站 webhook 身份验证的 bearer 令牌
    webhookSsrfPolicy: {
      allowedHostnames: ["127.0.0.1"], // 可选，用于受信任接收方的精确例外
    },
    sessionRetention: "24h", // 时长字符串（“0h”表示禁用）或 false
  },
}

• enabled：执行已存储的自动化任务（默认：true）。设置为 false 可暂停所有自动化执行，而不会删除任务。
• triggers.enabled：同时运行事件驱动的自动化触发器（默认：false）。
• sessionRetention：在清理 SQLite 会话行之前，保留已完成的隔离自动化运行会话的时长。也控制已归档的已删除自动化记录的清理。默认值：24h；设置为 false 或 "0h" 等零时长可禁用（负时长无效）。
• 运行历史记录会自动为每个任务保留最新的 2000 条终止状态记录。丢失的记录仍会保留其 24 小时的清理窗口。
• webhookToken：用于自动化 webhook POST 投递（delivery.mode = "webhook"）的 bearer 令牌；如果省略，则不会发送身份验证标头。
• webhookSsrfPolicy：适用于主要 webhook、完成 webhook、失败目标 webhook 和失败告警 webhook 的共享出站 SSRF 策略。省略时会阻止私有／内部目标。优先使用精确的 allowedHostnames；仅对受信任的私有网络接收方使用 dangerouslyAllowPrivateNetwork: true。针对特定虚假 IP 范围的代理标志为 allowRfc2544BenchmarkRange 和 allowIpv6UniqueLocalRange。

​

cron.failureAlert

{
  cron: {
    failureAlert: {
      enabled: false,
      after: 2,
      cooldownMs: 3600000,
      includeSkipped: false,
      mode: "announce",
      channel: "last",
      to: "channel:C1234567890",
      accountId: "main",
    },
  },
}

• enabled：为自动化任务启用失败告警（默认：false）。
• after：触发告警前所需的连续失败次数（正整数，最小值：1；默认值：2）。
• cooldownMs：同一任务重复告警之间的最小毫秒数（非负整数；默认值：3600000）。
• includeSkipped：将连续跳过的运行计入告警阈值（默认：false）。跳过的运行会单独跟踪，不会影响执行错误退避。
• mode：投递模式——"announce" 通过频道消息发送；"webhook" 将请求发送到 to 中的目标。目标数据足够时，默认为 "announce"。
• channel：播报投递的频道覆盖值。"last" 会复用最后一个已知的投递频道。
• to：显式的播报目标或 webhook URL。使用 webhook 模式时必需。
• accountId：可选的账户或频道 ID，用于限定告警投递范围。
• 每个任务的 delivery.failureDestination 会覆盖这些全局目标字段。
• 当全局和任务级失败目标均未设置时，已经通过 announce 投递的任务会在失败时回退到其主要播报目标。
• delivery.failureDestination 仅支持 sessionTarget="isolated" 的任务，除非该任务的主要 delivery.mode 为 "webhook"。

​

媒体模型模板变量

​

配置包含（$include）

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

• 单个文件：替换包含它的对象。
• 文件数组：按顺序进行深度合并（后者覆盖前者）。
• 同级键：在包含内容之后进行合并（覆盖包含的值）。
• 嵌套包含：最多 10 层。
• 路径：相对于包含文件解析，但必须位于顶层配置目录（openclaw.json 的 dirname）内。只有在解析后仍位于该边界内时，才允许使用绝对路径或 ../ 形式。设置 OPENCLAW_INCLUDE_ROOTS（绝对路径）可允许使用配置目录之外的其他根目录。
• 限制：路径在解析前后都不得包含空字节，且长度必须严格小于 4096 个字符；每个被包含的文件上限为 2 MB。
• 仅更改单个顶层部分且该部分由单个文件包含提供支持的 OpenClaw 写入操作，会直接写入该被包含的文件。例如，plugins install 会更新 plugins: { $include: "./plugins.json5" } 对应的 plugins.json5，并保持 openclaw.json 不变。
• 根包含、包含数组以及带有同级覆盖项的包含，对于 OpenClaw 写入操作均为只读；这些写入操作会安全失败，而不会将配置扁平化。
• 错误：对于文件缺失、解析错误、循环包含、路径格式无效和长度超限，会提供明确的错误消息。

​

相关

• 配置
• 配置示例
• 诊断工具