跳转至

配置 — 网关

gateway.* 下的网关运行时键。

完整的键索引及其他顶级配置域,请参阅 配置参考。

网关

{
  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",
      assignments: {
        byGithubLogin: { octocat: "maintainer" },
      },
      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 community 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,
        },
      },
    },
  },
}
网关字段详细信息
  • mode:local(运行网关)或 remote(连接远程网关)。除非设置为 local,否则网关拒绝启动。
  • port:本地网关绑定端口,复用 WS + HTTP。它不用于选择 macOS SSH 隧道端口。优先级:--port > OPENCLAW_GATEWAY_PORT > gateway.port > 18789。
  • publicOrigin:可选的网关外部可达 HTTPS 源,不含路径、查询参数或凭据。在本地开发期间,仅接受字面环回主机(localhost、127.0.0.1 或 [::1])的 HTTP。按请求方区分的 MCP OAuth 需要此值,并使用 <publicOrigin>/oauth/mcp/callback 作为其回调 URL。Slack 会话卡片操作、插件生成的查看器链接以及指向 Control UI 的聊天深度链接也使用此源。当省略 gateway.controlUi.allowedOrigins 时,它提供浏览器源允许列表。当 Control UI 在反向代理路径前缀下提供服务时,请单独设置 gateway.controlUi.basePath。
  • bind:auto、loopback(默认)、lan(0.0.0.0)、tailnet(Tailscale IPv4 可用时使用,否则使用 loopback)或 custom(一个 IPv4 地址)。解析后的 tailnet 地址以及除 127.0.0.1 或 0.0.0.0 之外的任何 custom 地址都要求在同一端口上监听 127.0.0.1 以服务同主机客户端;如果任一监听器无法绑定,则启动失败。非环回暴露仍仅限于所选接口。
  • 旧版绑定别名:请在 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,因此网关不可达。请使用 --network host,或将 bind 设置为 "lan"(或使用 customBindHost: "0.0.0.0" 的 bind: "custom")以监听所有接口。
  • 认证(Auth):默认为必需。非环回绑定需要网关认证。实际上,这意味着共享令牌/密码,或使用 gateway.auth.mode: "trusted-proxy" 的识别身份的反向代理。引导向导默认会生成一个令牌。
  • 如果同时配置了 gateway.auth.token 和 gateway.auth.password(包括 SecretRefs),请将 gateway.auth.mode 显式设置为 token 或 password。当两者都已配置且 mode 未设置时,启动和服务安装/修复流程将失败。
  • gateway.auth.mode: "none":显式无认证模式。仅用于可信的本地环回设置;引导提示故意不提供此选项。
  • gateway.auth.mode: "trusted-proxy":将浏览器/用户认证委托给识别身份的反向代理,并信任来自 gateway.trustedProxies 的身份标头(参见 可信代理认证)。此模式默认期望非环回代理源;同主机环回反向代理需要显式设置 gateway.auth.trustedProxy.allowLoopback = true。同主机内部调用方可以使用 gateway.auth.password 作为本地直接回退;gateway.auth.token 与 trusted-proxy 模式保持互斥。
  • gateway.auth.allowTailscale:当为 true 时,Tailscale Serve 身份标头可以满足 Control UI/WebSocket 认证(通过 tailscale whois 验证)。HTTP API 端点不使用该 Tailscale 标头认证;它们遵循网关正常的 HTTP 认证模式。这种无令牌流程假定网关主机是可信的。当 tailscale.mode = "serve" 时默认为 true。
  • gateway.auth.identityScopes:将经过验证的 trusted-proxy 用户或 Tailscale WhoIs 登录映射到仅限连接的 operator 作用域。邮箱键不区分大小写匹配;其他身份精确匹配。对于 trusted-proxy Control UI 连接,x-openclaw-scopes 为设备注册或升级请求以及最终的设备加身份会话作用域设定上限。授权不会创建或修改配对记录。令牌、密码和无认证连接没有经过验证的身份,也不会获得任何授权。
  • gateway.roles:可选的命名 operator 角色,适用于团队网关上的已认证用户个人资料。每个定义都指定 sessions.others(none、view、suggest 或 write)、允许的会话创建和代理运行 agents("*" 或代理 ID 数组),以及一个封闭的 scopes 上限,该上限也适用于身份认证的 HTTP 请求和已签名的 Control UI 插件授权。可选的 sandbox 默认为 "inherit",或设置为 "required" 以强制对在该角色下创建的会话进行沙箱化,即使代理的沙箱模式为 "off"。此要求由已认证的创建者记录一次,不能通过角色更新或会话变更来更改,并且不影响现有会话。要求沙箱的用户无法启动主机执行会话,包括通过邀请;不可用的沙箱后端会失败关闭,提权或主机目标覆盖无法逃逸。管理员作用域的 users.setRole 网关方法分配或清除个人资料的角色,并立即断开其活动客户端,以便它们以当前权限重新连接。在配置角色时,身份认证的 operator 会话不会收到可重复使用的、与人员无关的设备/引导令牌,且无身份的设备令牌或引导令牌 operator 认证将被拒绝;请通过 trusted-proxy 或其他受支持的已验证身份重新连接。assignments.byGithubLogin 在用户首次登录前将不区分大小写的 GitHub 登录映射到已定义的角色;有效的显式个人资料分配优先,然后是匹配的缓存 GitHub 身份,最后是 default。无效或重复的规范化登录以及未知的角色名称将被拒绝;没有缓存 GitHub 身份的个人资料不匹配。default 是必需的,并且必须指定一个已配置的定义。users.list 保留显式的 role,并添加 effectiveRole 和 roleSource(assigned、githubLogin 或 default)。sessions.others: "none" 还会拒绝网关范围内的 usage.cost;审计诊断和其他 operator.write 控制平面能力仍然是共享域表面,而非敌对租户隔离。省略 roles 会保持现有的单人部署和共享密钥部署不变。参见 Operator 作用域。
  • gateway.roles.definitions.<role>.accessPolicyPlugin:可选的精确插件 ID,其注册的网关访问策略必须授权受此角色约束的人员。例如,默认访客角色可以要求 "visitor-access",而独立分配的员工角色则省略此字段。当插件缺失或禁用、其清单缺失或格式错误、加载失败或策略未提供当前权限时,网关会拒绝该角色的访问。当插件不可用时,该引用仍然是有效配置,因此独立员工和网关所有者可以修复它。省略此字段不会增加插件依赖。
  • gateway.roles.definitions.<name>.modelPolicy:可选的模型上限,适用于角色的请求、排队工作和子任务。使用 {} 时,允许的模型遵循指定源代理的主模型和备用模型。sourceAgent 选择该代理;allow 替换成员资格,deny 排除已解析的模型引用、别名或尾部系列模式,如 provider/restricted-*。空的 allow 会拒绝所有模型。启用配置重载后,仅涉及现有角色模型策略的编辑在提交时无需重启网关即可生效:使用已移除模型的请求会被取消,而允许的模型和不相关的工作继续运行。其他角色更改会热应用并重新连接客户端以使用当前权限,包括与模型策略编辑组合时。现有的手动模型规则仍然适用;省略的角色模型策略和 System 访问保持不变。参见 命名 operator 角色。
  • 角色定义、代理信任、身份作用域、Tailscale 身份验证以及可信代理策略均可热应用。超出模型策略的更改会使现有客户端以当前权限重新连接;但以下情况除外:仅另一登录的身份授权发生更改,或其自身作用域集合仅被重新排序时,已验证的 WebSocket 登录会保留其连接和已接受的运行。对其自身已解析授权的更改会撤销保留的和委派的工作;恢复授权不会重新激活该权限。挂起中的握手和写入无法保留已撤销的访问权限。认证模式更改仍需要重启 Gateway。

    • 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(公开,需要认证)。 OpenClaw 将该路由作为前台占用持有,因此除非路由处于活动状态,否则启动会失败;当 Gateway 停止时,路由会被释放。不支持命名 Tailscale Services,因为 Tailscale CLI 仅允许它们作为持久后台路由存在。
    • tailscale.preserveFunnel:已弃用的迁移保护开关。当 true 且 tailscale.mode = "serve" 时,OpenClaw 会在启动时重新应用 Serve 之前检查 tailscale funnel status。如果无法检查该状态,启动会在普通 Gateway 监听器打开之前失败。仍指向普通 Gateway 端口的外部 Funnel 不会获得受管入口的溯源信息。OpenClaw 会保持外部路由不变并发出警告。该路由只能通过显式配置的 gateway.trustedProxies 来源(具有有效的转发客户端地址)使用通用代理归属;受 Gateway 保护的路由随后需要配置认证,而聚合检查和插件认证的 webhook 则保留各自的响应和认证策略。首先配置 gateway.auth.password(优先使用 SecretRef)或 OPENCLAW_GATEWAY_PASSWORD,并将 gateway.auth.mode 设置为 password。然后运行 openclaw config set gateway.tailscale.mode funnel,接着运行 openclaw config unset gateway.tailscale.preserveFunnel。默认值为 false。
    • controlUi.experimental.customPlugins:允许由用户安装的插件(包括本地开发插件)提供原生浏览器 UI。默认值:false。可通过 Settings → Labs → Custom plugin UI 启用,或将此布尔值设置为 true。原生 UI 使用已登录操作员的 Gateway 权限运行,因此请仅为受信任的插件启用。关闭该设置后,已启用的捆绑插件的原生 UI 仍然可用;后端插件 API、普通插件加载、沙箱化仪表板小部件和 MCP Apps 不受影响。更改会热应用,并刷新已连接浏览器标签页中的插件视图。禁用后,请重新加载标签页以清除已经运行的插件 JavaScript。参见 功能插件。
    • controlUi.allowedOrigins:Gateway 浏览器连接的显式浏览器来源允许列表。省略时,若已配置 gateway.publicOrigin,则默认使用该值。显式列表(包括 [])会取代此默认值。来自回环、RFC1918/链路本地、.local、.ts.net 或 Tailscale CGNAT 主机的私有同源 LAN/Tailnet UI 加载会被接受,而无需启用 Host 头回退。
    • controlUi.environment:用于区分 Gateway 环境的可选视觉标识。设置 { label: "edge", color: "amber" } 可显示匹配的顶部条纹、Agent 头像环、环境标签、浏览器标题后缀以及着色的 favicon。label 会被去除首尾空白,且必须包含 1–24 个字符。color 必须是 teal、amber、purple、coral、pink、blue、green、red 或 gray。标签和颜色在登录前可见;省略该设置则保持默认外观不变。
    • controlUi.newSessionModelDefaults:"last-used"(默认)会恢复被记住的新会话模型、运行时和推理选择。设置为 "configured" 则以所选 Agent 已配置的默认值来开始新的草稿。适用于此 Gateway 提供 UI 中的 /new 和命令面板,在浏览器刷新或重新连接后生效。显式选择保持可编辑,并会随当前未发送草稿一起在重载后保留;提交该草稿后,其选择即告失效,因此下一个新草稿使用已配置的默认值。现有会话不受影响。工作区、放置方式和 Fast Mode 偏好会被保留;存储的偏好不会被删除。在 Agent(或 agents.defaults)上配置所需模型和 thinkingDefault;此设置不会强制使用特定模型或推理级别。
    • controlUi.communityInvite:在侧边栏中显示带有 Reddit、Discord 和 X 链接的社区邀请。默认值:true。在提供 UI 的 Gateway 上设置为 false,即可对使用该部署的每个浏览器隐藏它,包括连接到不同远程 Gateway 的浏览器。该设置会热重载;现有页面会在浏览器刷新或重新连接后生效。重新启用会保留浏览器本地的关闭状态。
    • controlUi.github.token:可选的、由 SecretRef 支持的服务凭据,用于在无需托管 Agent 身份的情况下进行 GitHub 支持的个人资料验证、Control UI 项目发现以及 GitHub 悬停预览。将 controlUi.github.host 设置为所选的 gateway.github.host,以进行 Enterprise 仓库服务访问。省略凭据主机时,默认表示 github.com;主机不匹配会在请求前失败关闭。公共个人资料元数据验证保持在公共签发者上进行,并且仅使用符合条件的公共凭据;登录提供者拥有该人员的身份。元数据缓存和配额冷却会自动进行;参见 Gateway 个人资料与 GitHub 额度。悬停预览优先使用所选 Agent 的有效 tools.github 身份(包括继承的系统身份),并且仍仅限于公共仓库。当 Gateway 应独立于其共享进程环境拥有服务访问权限时,优先使用此显式设置。省略时,共享的 GH_TOKEN 然后 GITHUB_TOKEN 回退仅适用于 github.com,因此 Enterprise 服务访问需要显式的、绑定主机的凭据。显式配置但不可用的凭据会失败关闭,而不会使用无关凭据。其确切的环境或存储名称被排除在 Agent 执行之外;自定义名称不会清除无关的原生 GH_TOKEN 或 GITHUB_TOKEN 值。此凭据独立于 tools.github Agent 身份,并且不创建 OS 用户安全边界。 会话 PR 摘要和 CI 详情使用仓库或检出记录的主机。在选择了 Enterprise 主机时,公共 GitHub 会话仍停留在公共 API 上并使用匿名访问;Enterprise 凭据和缓存的私有结果永远不会进入这些会话。
  • 工具活动描述会在由执行智能体提供时自动显示;查看工具调用不会请求实用模型补全。原有的 controlUi.toolTitles 设置已退役。运行 openclaw doctor --fix 可从现有配置中移除该项。

    • controlUi.automaticallyFetchFavicons:在 Control UI 聊天中启用链接 favicon 和浏览器标签页社交预览。默认值:true。通过身份验证的浏览器会为每个主机名向其同源 Gateway 发起请求。对于内联链接 favicon,Gateway 会请求 https://<hostname>/favicon.ico,拒绝 IP 字面量和私有/内部目标,固定公共 DNS 解析结果,在相同的严格 SSRF 策略下重新验证每次重定向,限制重定向次数/时间/字节数/并发数,校验图像,并返回可私有缓存的图像 blob。OpenClaw 在此流程中不使用 Google 或其他 favicon 服务。这会向目标站点披露链接的主机名以及 Gateway 的网络地址。浏览器标签页卡片还会通过 Gateway 额外请求公共页面标题、声明的 favicon 以及 Open Graph 或 Twitter 图像,并遵循相同的公共网络限制和有界 HTML/图像处理。不会转发浏览器 Cookie 或站点凭据。这些预览会向目标站点及其声明的图像主机披露页面 URL 和 Gateway 的网络地址。设置为 false 可同时禁用自动 favicon 和页面预览获取;现有的实时浏览器截图预览不受影响。
    • controlUi.dangerouslyAllowHostHeaderOriginFallback:危险模式,可为有意依赖 Host 头来源策略的部署启用 Host 头来源回退。
    • cliAgents.enabled:在 Control UI 新建会话模型选择器中显示 CLI agents 分组。默认值:true;设置为 false 可禁用 CLI agents 和原生 CLI 会话创建。该分组仅在 Gateway 公布 sessions.catalog.list 时出现,并且仅包含支持创建会话的目录提供方。选择其中一个将打开与侧边栏目录操作相同的目录目标新建会话流程。

    在 设置 → 基础设施 → Gateway 中配置 CLI agents。

    目录提供方也可以公布基于终端的会话创建方式。该方法仅在 cliAgents.enabled 开启、Gateway 终端可用且所选提供方暴露该能力时可用。调用方需提供 cwd;如有需要,请先使用 worktrees.create 创建新的工作树,因为终端启动不会预先配置工作树。

    • terminal.enabled:管理员作用域的操作员终端。默认值:true;设置为 false 可选择退出。终端会在所选智能体工作区中启动主机 PTY,继承 Gateway 进程环境,并且会拒绝 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 主机上的 Gateway 端口。macOS 隧道会依次回退到 remote.url 中的端口,然后是 18789;当隧道端口与目标端口不同时,请显式设置此项。
    • remote.tlsFingerprint:远程 wss:// Gateway 的预期 SHA-256 证书指纹。macOS 应用会将其同时应用于操作员/控制和伴随节点连接。没有显式值时,macOS 仅在常规系统信任成功后记录首次使用固定值(pin)。
    • remote.sshHostKeyPolicy:macOS SSH 隧道主机密钥策略。strict 是默认值,要求使用已受信任的密钥。openssh 是显式选择加入,使用托管别名的有效 OpenSSH 配置;使用前请审阅匹配的用户和系统 SSH 设置。除非再次显式选择加入,否则 macOS 应用和 configure-remote 在更改目标时会将该策略重置为 strict。
    • gateway.remote.token / .password 是远程客户端凭据字段。它们本身不配置 gateway 认证。
    • gateway.push.apns.relay.baseUrl:中继支持的 iOS 构建向 gateway 发布注册后使用的外部 APNs 中继的基本 HTTPS URL。公共 App Store 构建使用托管的 OpenClaw 中继。自定义中继 URL 必须匹配刻意分离的 iOS 构建/部署路径,且该路径的中继 URL 指向该中继。
    • gateway.push.apns.relay.timeoutMs:网关到中继的发送超时时间(毫秒)。默认值为 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。
    • OPENCLAW_HANDSHAKE_TIMEOUT_MS:内置预认证 Gateway WebSocket 握手超时时间的可选环境覆盖。
    • channels.<provider>.healthMonitor.enabled:按渠道选择退出健康监控器重启,同时保持全局监控器启用。
    • channels.<provider>.accounts.<accountId>.healthMonitor.enabled:多账户渠道的按账户覆盖。设置后,它优先于渠道级别的覆盖。
    • 仅当 gateway.auth.* 未设置时,本地 gateway 调用路径才能使用 gateway.remote.* 作为回退。
    • 如果通过 SecretRef 显式配置了 gateway.auth.token / gateway.auth.password 但无法解析,则解析会失败关闭(fail-closed),不会用远程回退掩盖。
    • trustedProxies:终止 TLS 或注入转发客户端头的反向代理 IP。只应列出你控制的代理。环回条目对于同主机代理/本地检测设置仍然有效(例如 Tailscale Serve 或本地反向代理),但它们不会使环回请求符合 gateway.auth.mode: "trusted-proxy" 的条件。
    • allowRealIpFallback:当为 true 时,如果缺少 X-Forwarded-For,gateway 会接受 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 验证自动批准(默认:启用)。gateway 会 SSH 回连配对主机(BatchMode、严格主机密钥),并且仅在 openclaw node identity 设备密钥完全匹配时批准。与 autoApproveCidrs 具有相同的资格底线;除非 cidrs 覆盖,否则检查仅限于私有/CGNAT 源地址。设置为 false 可禁用,或设置为 { user, identity, timeoutMs, cidrs } 进行调整。参见 节点配对。
    • 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)、Computer Control 和移动端 UI 控制则依赖节点本地启用加配对。桌面共享在桌面节点上默认启用,并仍然受显式拒绝条目约束。iOS 健康权限、Android 短信权限和 Gateway 命令授权相互独立。Gateway 命令策略更改会在默认重新加载模式下热应用到已连接的节点,而不会授予额外的配对批准。当节点更改其声明的命令列表时,请重新连接并批准新的命令请求,以便 Gateway 存储扩展后的命令面。
    • gateway.tools.deny:为 HTTP POST /tools/invoke 额外阻止的工具名称(扩展默认拒绝列表)。
    • gateway.tools.allow:为所有者/管理员调用者从默认 HTTP 拒绝列表中移除工具名称。这不会将带有身份的 operator.write 调用者升级为所有者/管理员访问权限;即使被加入允许列表,cron、gateway 和 nodes 对非所有者调用者仍不可用。

禁用文件和图片上传

将 gateway.uploads.enabled 设置为 false 可禁用客户端文件和图片上传:

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

默认值为 true。更改无需重启 Gateway 即可热应用。即使来自过时的浏览器或直接 API 客户端,Gateway 也会拒绝上传;隐藏 Control UI 控件并不构成强制执行边界。拒绝会返回 FORBIDDEN 及明细代码 UPLOADS_DISABLED(OpenAI 兼容 HTTP API 返回状态 403 和错误代码 UPLOADS_DISABLED)。工具调用端点保留其现有的被阻止工具信封,并附带相同的禁用上传消息。

该开关涵盖聊天和新会话附件、companion 附件、终端上传、内联用户/agent 头像、技能归档和文件夹上传,以及 Workboard 附件。携带新上传字节的直接节点和工具调用同样会被拒绝;现有媒体传输仍然可用。包含图片或文件内容部分的 OpenAI 兼容请求会在获取或解码之前被拒绝,包括 URL 支持的内容部分。纯文本请求仍然有效。被禁用的上传会作为一个整体被拒绝;其附件不会被静默移除。已接受的写入会继续完成落地:例如,在开关更改之前持久化的头像仍会获得相应的 agent 配置更新。禁用上传不会撤销现有字节,也不会将已完成的上传变为拒绝。对已接受的聊天、会话创建和出站消息请求的授权重试会重放其现有回执,而不会再次上传;使用新的幂等键仍然需要启用上传。

下载、现有媒体、agent 生成的图片/文件、普通文本编辑、服务器本地内存迁移、渠道入站媒体和内部 worker 文件传输仍然可用。此开关不是沙箱或数据丢失防护策略:它不会移除授权的 shell 访问、agent 文件系统工具、配置管理或任意第三方插件能力。对于这些,请使用相应的工具、终端、渠道和插件策略。

OpenAI 兼容端点

  • 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 输入加固:
  • gateway.http.endpoints.responses.maxUrlParts
  • gateway.http.endpoints.responses.files.urlAllowlist
  • gateway.http.endpoints.responses.images.urlAllowlist 空的 allowlist 被视为未设置;使用 gateway.http.endpoints.responses.files.allowUrl=false 和/或 gateway.http.endpoints.responses.images.allowUrl=false 可禁用 URL 获取。
  • 可选的响应加固标头:
  • gateway.http.securityHeaders.strictTransportSecurity 热应用于后续响应,包括健康检查。仅为你控制的 HTTPS 源设置;使用 false 或移除该值可停止发送此标头。参见 Trusted Proxy Auth。

多实例隔离

在一台主机上运行多个 Gateway,使用唯一的端口和状态目录:

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

便捷标志:--dev(使用 ~/.openclaw-dev + 端口 19001)、--profile <name>(使用 ~/.openclaw-<name>)。

参见 Multiple Gateways。

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:在 Gateway 监听器上启用 TLS 终止(HTTPS/WSS)(默认:false)。
  • autoGenerate:默认为 true。Gateway 启动时仅在两个文件都缺失的情况下生成本地自签名证书/密钥对,包括在配置的路径处;仅用于本地/开发环境。已存在的部分配对保持原样,且启动会失败。生成的文件在发布时不会覆盖现有路径,并且在文件系统支持时其父目录会被同步;不支持的目录刷新会发出结构化降级持久性警告。
  • certPath:TLS 证书文件的文件系统路径。
  • keyPath:TLS 私钥文件的文件系统路径;请保持权限受限。
  • caPath:可选的 CA 捆绑包路径,用于客户端验证或自定义信任链。

启用自动重新加载后,Gateway 会监视其接受路径上的证书、密钥和 CA 文件。替换其内容可续期所有 Gateway HTTPS 监听器,而不会断开现有连接。完整材料会先经过验证;缺失、不可读或不匹配的配对会保留之前的证书继续服务,并记录失败日志。续期永远不会生成缺失的文件。后台观察同样会跟踪原子符号链接和投影目录的替换。

gateway.reload.mode: "off" 也会暂停证书续期。重新启用 reload 会检查当前文件,包括暂停期间完成的续期。发现和新建配对载荷使用所提供的指纹。保存的远程证书 pin 仍由操作员控制:在使用续期证书重新连接之前更新它们。

客户端命令(如 triage、gateway status 和 gateway probe)仅读取公共证书以确定本地 TLS pin。它们从不生成或修复 TLS 文件,也不需要服务器私钥或 CA 捆绑包。未提供 certPath 时,它们会检查状态目录下的 gateway/tls/gateway-cert.pem。缺失或不可读的证书不会提供隐式 pin;正常的连接信任检查仍然适用。启动 Gateway 以生成缺失的配对,或在连接前提供配置的证书文件。

长期存活的本地健康检查会记住其端点最近一次已验证的证书,在替换文件不完整或重载暂停期间保持健康检查可用。它们只有在验证连接成功后才会采用替换证书。新的检查,或错过了中间续期的检查,不能信任一个已不在配置文件中且从未被验证过的正在提供的证书。请完成或重新启用续期,使监听器与配置的证书保持一致。

gateway.reload

{
  gateway: {
    reload: {
      mode: "hybrid", // off | hybrid
    },
  },
}
  • mode:控制运行时如何应用配置编辑。
  • "off":忽略实时编辑;更改需要显式重启。
  • "hybrid"(默认):在进程内应用热安全更改,当更改需要时再重启。

早期的 "restart" 和 "hot" 值已弃用;openclaw doctor --fix 会将两者都映射为 "hybrid"。

重载防抖和进行中操作的延迟不再可配置,而是使用内置默认值运行。openclaw doctor --fix 会从旧配置文件中移除已弃用的 debounceMs 和 deferralTimeoutMs 键。


本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw