配置 — 网关

{
  gateway: {
    mode: "local", // local | remote
    port: 18789,
    bind: "loopback",
    publicOrigin: "https://gateway.example.com",
    auth: {
      mode: "token", // none | token | password | trusted-proxy
      token: "your-token",
      // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD
      // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth
      allowTailscale: true,
      identityScopes: {
        "admin@example.com": ["operator.admin"],
      },
      rateLimit: {
        maxAttempts: 10,
        windowMs: 60000,
        lockoutMs: 300000,
        exemptLoopback: true,
      },
    },
    // Optional person-level access policy for team Gateway deployments.
    roles: {
      default: "guest",
      definitions: {
        maintainer: {
          sessions: { others: "write" }, // none | view | suggest | write
          agents: ["roboclaw"],
          scopes: ["operator.read", "operator.write", "operator.approvals"],
        },
        guest: {
          sessions: { others: "view" },
          agents: ["roboclaw"],
          scopes: ["operator.read", "operator.write"],
          sandbox: "required", // inherit (default) | required
        },
      },
    },
    tailscale: {
      mode: "off", // off | serve | funnel
    },
    controlUi: {
      enabled: true,
      basePath: "/openclaw",
      // experimental: { customPlugins: false }, // Labs: native UI from user-installed plugins
      // environment: { label: "edge", color: "amber" },
      // communityInvite: true, // show the sidebar Discord invitation unless dismissed
      // root: "dist/control-ui",
      // github: { token: { source: "store", provider: "default", id: "CONTROL_UI_GITHUB" } },
      // embedSandbox: "scripts", // strict | scripts | trusted
      // allowExternalEmbedUrls: false, // dangerous: allow absolute external http(s) embed URLs
      // automaticallyFetchFavicons: true, // SSRF-guarded link favicon fetches
      // allowedOrigins: ["https://control.example.com"], // optional override of publicOrigin
      // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode
    },
    uploads: {
      enabled: true, // set false to reject client file/image uploads
    },
    cliAgents: {
      enabled: true, // show create-capable CLI session targets in the model picker
    },
    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"],
    // Optional. Default false.
    allowRealIpFallback: false,
    nodes: {
      pairing: {
        // Silent same-host pairing and access upgrades. Default: enabled.
        // Set false to require explicit approval for every device.
        autoApproveLocal: true,
        // Optional. Default unset/disabled.
        autoApproveCidrs: ["192.168.1.0/24", "fd00:1234:5678::/64"],
        // SSH-verified auto-approval. Default: enabled (true).
        // Set false to disable SSH verification only; this does not affect
        // autoApproveCidrs above. For manual-only node pairing, set false AND
        // unset autoApproveCidrs. Pass an object to tune: { user, identity,
        // timeoutMs, cidrs }.
        sshVerify: true,
      },
      commands: {
        allow: ["canvas.navigate"],
        deny: ["system.run"],
      },
    },
    tools: {
      // Additional /tools/invoke HTTP denies
      deny: ["browser"],
      // Remove tools from the default HTTP deny list for owner/admin callers
      allow: ["gateway"],
    },
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          timeoutMs: 10000,
        },
      },
    },
  },
}

  目录提供者也可以宣告支持基于终端的会话创建。该方法仅在 `cliAgents.enabled` 开启、网关终端可用，且所选提供者暴露了该能力时可用。调用者需提供 `cwd`；如有需要，请先使用 `worktrees.create` 创建新的工作树，因为终端启动时不会自动创建工作树。

- `terminal.enabled`：管理员作用域的操作员终端。默认值：`true`；设为 `false` 可选择退出。该终端会在所选代理工作区中启动主机 PTY，继承网关进程环境，并且对于 `sandbox.mode: "all"` 的代理会被拒绝。更改热生效：禁用会关闭已连接、已分离及对话拥有的会话，并取消待处理的打开请求；重新启用则允许创建新会话。请重新加载已打开的 Control UI 页面，以获取更新的内容安全策略。
- `terminal.shell`：可选的 Shell 可执行文件。未设置时，OpenClaw 在 Unix 上使用 `$SHELL`，在 Windows 上使用 `%ComSpec%`。更改会热生效于新打开的终端；现有终端将继续运行其原来的 Shell。
- `terminal.detachedSessionTimeoutSeconds`：终端会话在其连接断开（页面重新加载、笔记本休眠）后存活的时长，期间仍可通过 `terminal.attach` 重新连接，并回放最近输出。默认值：`300`。设为 `0` 可在连接断开时立即终止会话。更改会对现有分离会话热生效，使用其原始断开时间计算；已过期的会话立即关闭，而已连接终端继续运行。分离会话会继续运行其命令，因此在共享或暴露的主机上请调短此值。
- `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，公网主机的 `remote.url` 必须为 `wss://`；明文 `ws://` 仅接受用于回环、局域网、链路本地、`.local`、`.ts.net` 和 Tailscale CGNAT 主机。
- `remote.url`：远程客户端端点。在 macOS SSH 模式下，其回环端口会独立于 `gateway.port` 选择本地隧道端口。
- `remote.remotePort`：远程 SSH 主机上的网关端口。macOS 隧道会回退到 `remote.url` 中的端口，然后是 `18789`；当隧道与目标端口不同时，请显式设置此值。
- `remote.tlsFingerprint`：远程 `wss://` 网关的预期 SHA-256 证书指纹。macOS 应用会将其同时应用于操作员/控制连接和伴生节点连接。没有显式值时，macOS 仅在常规系统信任成功后记录首次使用固定。
- `remote.sshHostKeyPolicy`：macOS SSH 隧道的主机密钥策略。`strict` 是默认值，要求使用已受信任的密钥。`openssh` 是对受管别名的有效 OpenSSH 配置的明确选择加入；使用前请检查匹配的用户和系统 SSH 设置。macOS 应用和 `configure-remote` 在更改目标时会将此策略重置为 `strict`，除非再次明确选择加入。
- `gateway.remote.token` / `.password` 是远程客户端凭据字段。它们本身不会配置网关认证。
- `gateway.push.apns.relay.baseUrl`：外部 APNs 中继的基础 HTTPS URL，在基于中继的 iOS 构建向网关发布注册后使用。公开的 App Store 构建使用托管的 OpenClaw 中继。自定义中继 URL 必须匹配一条刻意独立的 iOS 构建/部署路径，该路径的中继 URL 指向该中继。
- `gateway.push.apns.relay.timeoutMs`：网关到中继的发送超时时间（毫秒）。默认值为 `10000`。
- 基于中继的注册会委托给特定的网关身份。配对的 iOS 应用会获取 `gateway.identity.get`，将该身份包含在中继注册中，并将注册作用域的发送授权转发给网关。其他网关无法重用该存储的注册。
- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：上述中继配置的临时环境变量覆盖。
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅限开发的应急出口，用于回环 HTTP 中继 URL。生产环境的中继 URL 应保持使用 HTTPS。
- `OPENCLAW_HANDSHAKE_TIMEOUT_MS`：可选的环境变量覆盖，用于内置的网关 WebSocket 预认证握手超时。
- `channels.<provider>.healthMonitor.enabled`：按渠道选择退出健康监控重启，同时保持全局监控启用。
- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`：多账户渠道的按账户覆盖。设置后，它优先于渠道级别的覆盖。
- 本地网关调用路径仅可在 `gateway.auth.*` 未设置时使用 `gateway.remote.*` 作为回退。
- 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置但无法解析，则解析失败即关闭（不进行远程回退掩盖）。
- `trustedProxies`：终止 TLS 或注入转发客户端头的反向代理 IP。只列出您控制的代理。回环条目对于同主机代理/本地检测设置（例如 Tailscale Serve 或本地反向代理）仍然有效，但它们**不会**使回环请求有资格获得 `gateway.auth.mode: "trusted-proxy"`。
- `allowRealIpFallback`：当为 `true` 时，如果缺少 `X-Forwarded-For`，网关将接受 `X-Real-IP`。默认 `false`，以保证失败即关闭的行为。
- `gateway.nodes.pairing.autoApproveLocal`：静默批准来自受信任本地连接的配对、角色升级和作用域升级（默认值：`true`）。作用域升级还要求连接本身证明具备本地级别凭据（认证模式 `none` 或共享令牌/密码）；Tailscale、受信任代理和设备令牌连接会将其已配对作用域保留为持久上限。设为 `false` 可要求对每台设备进行显式批准；仅元数据的重连刷新仍然自动进行。
- `gateway.nodes.pairing.autoApproveCidrs`：可选的 CIDR/IP 允许列表，用于自动批准首次节点设备配对（不请求任何作用域）。未设置时禁用。它不会自动批准操作员/浏览器/Control UI/WebChat 配对，也不会自动批准角色、作用域、元数据或公钥升级。
- `gateway.nodes.pairing.sshVerify`：首次节点设备配对的 SSH 验证自动批准（默认：启用）。网关会 SSH 回连配对主机（BatchMode 模式、严格主机密钥），并且仅在 `openclaw node identity` 设备密钥完全匹配时批准。与 `autoApproveCidrs` 具有相同的资格下限；探测仅限于私有/CGNAT 源地址，除非 `cidrs` 覆盖了它们。设为 `false` 可禁用，或设为 `{ user, identity, timeoutMs, cidrs }` 进行调整。参见[节点配对](pairing.md#ssh-verified-device-auto-approval-default)。
- `gateway.nodes.commands.allow` / `gateway.nodes.commands.deny`：在配对和平台允许列表评估之后，对已声明节点命令的全局允许/拒绝整形。`commands.allow` 是对分类命令（如 `camera.snap`、`camera.clip`、`codex.exec-server.stdio.v1`、`screen.record`、`health.summary`、`sms.search` 和 `sms.send`）的持久启用；`commands.deny` 会移除某个命令，即使平台默认或显式允许原本会包含它。在已配对设备或已注册云节点上进行 Codex 远程执行，还要求每次 exec-server 尝试都获得一次单独的关键一次性批准；持久允许列表永远不会授予该批准。桌面共享（`desktop.stream`）、计算机控制和移动 UI 控制则依赖节点本地启用加上配对。桌面共享在桌面节点上默认启用，并仍受显式拒绝条目约束。iOS 健康权限、Android 短信权限和网关命令授权相互独立。网关命令策略更改在默认重载模式下会热生效于已连接节点，而不会授予额外的配对批准。当节点更改其声明的命令列表时，请重新连接该节点并批准新的命令请求，以便网关存储扩展后的命令面。
- `gateway.tools.deny`：为 HTTP `POST /tools/invoke` 额外阻止的工具名称（扩展默认拒绝列表）。
- `gateway.tools.allow`：为所有者/管理员调用者从默认 HTTP 拒绝列表中移除工具名称。
  这不会将携带身份的 `operator.write` 调用者升级为所有者/管理员访问权限；
  `cron`、`gateway` 和 `nodes` 即使被允许列出，对非所有者调用者仍不可用。

{
  gateway: {
    uploads: { enabled: false },
  },
}

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

{
  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",
    },
  },
}

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