配置基础

OpenClaw 从 $OPENCLAW_CONFIG_PATH（默认：~/.openclaw/openclaw.json）读取可选的 JSON5 配置。如果文件不存在，则使用较为安全的默认值，包括默认工作区 ~/.openclaw/workspace。

非回环绑定需要有效的网关认证路径：共享密钥认证（token 或密码），或位于正确配置且可识别身份的反向代理之后的 gateway.auth.mode: "trusted-proxy"。

{
  gateway: {
    bind: "lan",
    auth: {
      mode: "token",
      token: "replace-me",
    },
  },
}

• gateway.remote.token / .password 本身不会启用本地网关认证；本地调用路径仅在 gateway.auth.* 未设置时，才能将 gateway.remote.* 用作回退。
• 对于密码认证，设置 gateway.auth.mode: "password" 以及 gateway.auth.password（或 OPENCLAW_GATEWAY_PASSWORD）。
• 如果通过 SecretRef 显式配置了 gateway.auth.token / .password 但无法解析，则解析会以失败关闭（不会有远程回退遮蔽）。
• 共享密钥的 Control UI 设置通过 connect.params.auth.token 或 connect.params.auth.password（存储在应用/UI 设置中）进行认证。Tailscale Serve 或 trusted-proxy 等携带身份的模式改用请求头——避免将共享密钥放在 URL 中。
• 使用 gateway.auth.mode: "trusted-proxy" 时，同主机回环反向代理需要显式设置 gateway.auth.trustedProxy.allowLoopback = true，并在 gateway.trustedProxies 中添加回环条目。

OpenClaw 默认强制执行网关认证，包括回环地址。如果未配置显式认证路径，启动时会解析为 token 模式，并为该次启动生成一个仅运行时有效的 token，因此本地 WS 客户端必须进行认证。这会阻止其他本地进程调用 Gateway。

在全新的回环启动中，Gateway 会在 /readyz 之前准备好标准的同用户 CLI 设备凭据，因此普通的 openclaw CLI 调用无需持久化生成的 token 即可完成认证。其他客户端仍需要显式共享密钥或已批准的设备配对。

当客户端需要在重启后保持稳定密钥时，请显式配置 gateway.auth.token、gateway.auth.password、OPENCLAW_GATEWAY_TOKEN 或 OPENCLAW_GATEWAY_PASSWORD。你也可以选择密码模式，或为可识别身份的反向代理选择 trusted-proxy。如需开放回环，请显式设置 gateway.auth.mode: "none"。openclaw doctor --generate-gateway-token 可随时生成 token。

Gateway 会监听配置并支持热重载：gateway.reload.mode: "hybrid"（默认）会热应用安全更改，并在关键更改时重启。off 会禁用配置重载；之前的 hot 和 restart 模式已退役。大多数 tools.*、agents.* 策略、session.* 和 messages.* 更改会立即生效，完全无需重载操作；gateway.* 的绑定/端口更改需要重启。

web_fetch 无需 API 密钥即可工作。web_search 取决于你选择的提供商：

Grok 还可以复用来自模型认证的 xAI OAuth（openclaw onboard --auth-choice xai-oauth）。

推荐：运行 openclaw configure --section web 并选择一个提供商。

{
  plugins: {
    entries: {
      brave: {
        config: {
          webSearch: {
            apiKey: "BRAVE_API_KEY_HERE",
          },
        },
      },
    },
  },
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "brave",
        maxResults: 5,
      },
      fetch: {
        enabled: true,
        provider: "firecrawl", // optional; omit for auto-detect
      },
    },
  },
}

特定提供商的网页搜索配置位于 plugins.entries.<plugin>.config.webSearch.* 下。旧的 tools.web.search.* 提供商路径出于兼容性仍会加载，但不应用于新配置。Firecrawl 的网页抓取回退配置位于 plugins.entries.firecrawl.config.webFetch.* 下。

• 允许列表：添加 web_search/web_fetch/x_search，或使用 group:web 一次性启用全部三项。
• web_fetch 默认启用。
• 如果省略 tools.web.fetch.provider，OpenClaw 会根据可用凭据自动检测第一个可用的抓取回退提供商；官方 Firecrawl 插件即提供该回退。
• 守护进程从 ~/.openclaw/.env（或服务环境）读取环境变量。

文档：Web 工具。

config.apply 会替换整个配置；如果传入的是部分对象，则会移除所有其他配置。

当前的 OpenClaw 能保护大多数意外覆盖：

• OpenClaw 自身的配置写入会在写入前校验变更后的完整配置。
• 无效或破坏性的 OpenClaw 自身写入会被拒绝，并保存为 openclaw.json.rejected.*。
• 当整体结果校验通过时，启动过程可以在符合条件的单文件配置中迁移确定性的旧版键，并将之前的配置保留在 .bak 轮换中。其他无效编辑会导致启动失败关闭；热重载会跳过无效编辑，而不重写 openclaw.json。
• openclaw doctor --fix 负责该启动迁移之外的修复，可以恢复上次已知的良好配置，并将被拒绝的文件保存为 openclaw.json.clobbered.*。

常见模式：一个网关（例如 Raspberry Pi）加上节点和智能体。

• 网关（中心）：拥有渠道（Signal/WhatsApp）、路由、会话。
• 节点（设备）：Mac/iOS/Android 作为外设连接，并暴露本地工具，如 system.run 和 camera；Mac 还可以在原生面板中展示托管的 widget。
• 智能体（Worker）：为特殊角色（例如运维 vs 个人数据）提供独立的“大脑”/工作区。
• 子智能体：从主智能体派生出后台工作以实现并行处理。
• TUI：连接到网关并切换智能体/会话。

文档：节点、远程访问、多智能体路由、子智能体、TUI。

可以：

{
  browser: { headless: true },
  agents: {
    defaults: {
      sandbox: { browser: { headless: true } },
    },
  },
}

默认值为 false（有头模式）。无头模式在某些网站上更有可能触发反机器人检查（X/Twitter 经常屏蔽无头会话）。它使用相同的 Chromium 引擎，适用于大多数自动化任务；主要区别是没有可见的浏览器窗口（如需视觉效果，请使用截图）。参见 浏览器。

将 browser.executablePath 设置为你 Brave 可执行文件的路径（或任何基于 Chromium 的浏览器），然后重启网关。参见 浏览器。