跳转至

配置 — 浏览器、UI 和桌面

面向客户端的配置域:browser.*、ui.* 和 desktop.*。

有关完整键索引和其他顶层配置域,请参阅配置参考。

浏览器

{
  browser: {
    enabled: true,
    evaluateEnabled: true,
    defaultProfile: "user",
    ssrfPolicy: {
      // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access
      // allowPrivateNetwork: true, // legacy alias
      // allowedHostnames: ["*.example.com", "example.com", "localhost"],
      // blockedHostnames: ["tracker.example.com", "*.ads.example.com"],
    },
    tabCleanup: {
      enabled: true,
    },
    extensionRelay: {
      allowLegacyAuth: true,
    },
    profiles: {
      openclaw: { cdpPort: 18800 },
      work: {
        cdpPort: 18801,
        executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
      },
      chrome: { driver: "extension" },
      user: { driver: "existing-session", attachOnly: true },
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
      },
      remote: { cdpUrl: "http://10.0.0.42:9222" },
    },
    // headless: false,
    // noSandbox: false,
    // extraArgs: [],
    // executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    // attachOnly: false,
  },
}
  • evaluateEnabled: false 会禁用 act:evaluate 和 wait --fn。
  • extensionRelay.allowLegacyAuth 在浏览器中继身份验证迁移窗口期内默认为 true。它允许旧的扩展以及外部的 CDP Bearer、Basic 和 token 子协议客户端。在所有中继客户端都使用 auth v2 之后,将其设置为 false;v2 客户端永远不会降级。
  • tabCleanup 控制对受跟踪的主代理标签页在空闲一段时间后或会话超过其上限时进行的尽力而为的定期清理。跟踪仅适用于由浏览器工具 action: "open" 创建的标签页;用户打开的标签页或所有权未知的标签页永远不会被接管。禁用 tabCleanup 不会禁用显式的会话生命周期清理。
  • 主机本地的打开操作若具有稳定的原生 CDP 目标和浏览器身份,则会存储在共享的 SQLite 状态中,并在 Gateway 重启后仍可用于 /new 和会话生命周期清理。面向工具的原生 CDP 目标在重启后仍可用于空闲和上限清理。Chrome MCP 使用进程本地的目标句柄,因此冷启动的 existing-session 记录会等待生命周期清理,而不是冒着对重启后无法归属的活动进行空闲清扫的风险。OpenClaw 在关闭前会验证配置文件和浏览器实例。Chrome MCP 自动连接、缺少 /json/version 浏览器身份以及未解析的原生目标都完全属于进程本地范围,因此它们不会在重启后自动关闭。较旧的未跟踪标签页需要手动关闭。瞬时失败会保持待处理状态,以便稍后重试。参见标签页清理所有权。
  • ssrfPolicy.dangerouslyAllowPrivateNetwork 未设置时处于禁用状态,因此浏览器导航默认保持严格模式。
  • 仅当你有意信任私有网络浏览器导航时,才设置 ssrfPolicy.dangerouslyAllowPrivateNetwork: true。
  • 在严格模式下,远程 CDP 配置文件端点(profiles.*.cdpUrl)在可达性/发现检查期间同样会受到私有网络阻止规则的约束。
  • ssrfPolicy.allowPrivateNetwork 仍作为旧版别名受支持。
  • 在严格模式下,使用支持通配符的 ssrfPolicy.allowedHostnames 设置精确主机和模式例外。
  • ssrfPolicy.blockedHostnames 会在 DNS 和允许规则(包括私有网络例外)之前拒绝精确主机和 *.example.com 子域名。通配符不包含顶级域名;如需阻止 example.com,请单独添加。为空或未设置时不添加任何拒绝规则。
  • 远程配置文件仅可附加(禁用启动/停止/重置)。
  • profiles.*.cdpUrl 接受 http://、https://、ws:// 和 wss://。当你希望 OpenClaw 发现 /json/version 时使用 HTTP(S);当你的提供商提供直接的 DevTools WebSocket URL 时使用 WS(S)。
  • 如果外部管理的 CDP 服务可通过 loopback 访问,请将该配置文件的 attachOnly 设置为 true;否则 OpenClaw 会将 loopback 端口视为本地受管的浏览器配置文件,并可能报告本地端口所有权错误。
  • existing-session 配置文件使用 Chrome MCP 而非 CDP,并且可以附加到所选主机,或通过已连接的浏览器节点进行附加。
  • extension 配置文件使用已认证的 OpenClaw Chrome 扩展中继。该中继拥有其 loopback 端点,因此这些配置文件不接受 cdpUrl。参见 Chrome 扩展。
  • existing-session 配置文件可以设置 userDataDir,以定位特定的基于 Chromium 的浏览器配置文件,例如 Brave 或 Edge。
  • 如果 Chrome 已经通过 DevTools HTTP(S) 发现端点或直接 WS(S) 端点运行,existing-session 配置文件可以设置 cdpUrl。在该模式下,OpenClaw 会将端点传递给 Chrome MCP,而不是使用自动连接;userDataDir 在 Chrome MCP 启动参数中被忽略。mcpArgs 中有效的端点参数优先于 cdpUrl;参见自定义 Chrome MCP 启动。
  • existing-session 配置文件沿用当前的 Chrome MCP 路由限制:使用快照/引用驱动的操作而非 CSS 选择器定位、单文件上传钩子、不支持对话框超时覆盖、不支持 wait --load networkidle,也不支持 responsebody、PDF 导出、下载拦截或批量操作。
  • 本地受管的 openclaw 配置文件会在 OpenClaw 创建该配置文件时,从受管范围内分配一个 cdpPort。手动声明的配置文件必须自行设置 cdpPort,或为远程 CDP 端点设置 cdpUrl;schema 会拒绝两者都未设置的 openclaw(或旧版 clawd)驱动配置文件。
  • 本地受管的配置文件可以为该配置文件设置 executablePath,以覆盖全局的 browser.executablePath。使用此选项可以在 Chrome 中运行一个配置文件,在 Brave 中运行另一个。
  • 自动检测顺序:基于 Chromium 的默认浏览器 → Chrome → Brave → Edge → Chromium → Chrome Canary。
  • browser.executablePath 和 browser.profiles.<name>.executablePath 在 Chromium 启动前都接受 ~ 和 ~/... 来表示你的操作系统主目录。existing-session 配置文件中按配置文件设置的 userDataDir 也会进行波浪号展开。
  • 控制服务:仅限 loopback(端口由 gateway.port 派生,默认 18791)。
  • extraArgs 会向本地 Chromium 启动附加额外的启动标志(例如 --disable-gpu、窗口大小或调试标志)。
  • 浏览器配置文件、默认配置文件、全局启动设置、snapshotDefaults 和 tabCleanup 支持热重载。更改后的启动设置会在受影响的受管浏览器下次使用时替换它们;外部附加的浏览器保持运行。启用、评估、SSRF 策略和扩展中继身份验证的更改会替换浏览器控制服务及其所拥有的中继连接,而无需重启 Gateway。独立运行的中继守护进程保持自己的生命周期和策略。

界面

{
  ui: {
    seamColor: "#FF4500",
    prefs: {
      theme: "claw", // claw | knot | dash | absolutely | tide | beacon | phosphor | crt | manuscript | rose | miami | custom
      themeMode: "system", // light | dark | system
      locale: "en",
      chatShowThinking: true,
      chatShowToolCalls: true,
      chatPersistCommentary: true, // Keep commentary after runs in Control UI; does not deliver it to channels
      chatSendShortcut: "enter", // enter | modifier-enter
      chatFollowUpMode: "steer", // steer | queue; omit to use the server queue mode
    },
  },
}

Agent 显示名称、表情符号和头像分别归属于 agents.entries 下每个 Agent 的 identity 块;参见 Agent 配置。

  • seamColor:用于原生应用 UI 镶边的操作员强调色(Talk Mode 气泡色调等)。在 talk.config 载荷和 macOS 应用的配置快照中,Control UI 用户强调色(ui.prefs.accent)优先。如果两者均未设置,则使用主题默认值。prefs.accent 也接受 "theme",用于明确选择 Control UI 主题调色板而不继承 seamColor;在此情况下,talk.config 会省略其仅支持十六进制颜色的强调色。
  • prefs:跨设备操作员偏好。这是权威存储位置,因此 Agent 可以通过审批门修改它们,且每个 Control UI 客户端都能保持同步;浏览器会将这些值镜像到本地存储,以便立即启动。显式只读的连接会在该浏览器中保留编辑,而不会尝试写入配置。离线编辑会排队等待后续的可写连接,并在以只读方式重新连接后继续作为浏览器本地偏好生效。 chatPersistCommentary 默认为 true。将其设为 false 会在运行期间保持实时评论可见,但在完成时移除,并阻止新的 Codex 评论进入持久化的转录镜像。消息通道投递保持独立且不变。 仅用于呈现的偏好(例如高级层级可见性、文本缩放、聊天宽度和实时侧边栏活动)保留在浏览器本地,并在设置中配置。 已连接的客户端会实时应用服务端更改:Gateway 在每次持久化配置写入后广播仅含哈希的 config.changed 事件,客户端会刷新自身的快照(当本地设置草稿存在未保存的编辑时跳过)。重新连接的客户端会在连接时进行同步。

桌面

主机桌面源允许 Control UI 桌面面板连接到 Gateway 机器。它可以附加到现有的回环 RFB 服务器,或监管 Linux 上的无头 TigerVNC/XFCE 桌面。这是一项 Labs 功能,默认处于关闭状态。

在系统中,选择 Gateway 主机以检查是否存在现有的屏幕共享服务器。当存在可用服务器时,在 OpenClaw 中启用桌面访问会在不重启 Gateway 的情况下开启主机桌面;该桌面将在同一连接上可用。需要 Gateway 管理员权限。检测不会暴露桌面,也不会更改系统权限。现有的受管 Linux 桌面可以从同一视图启用。设置 → Labs → 主机桌面仍然可用于关闭访问权限或单独管理。

单独启用 macOS 屏幕共享、配对节点的桌面共享或屏幕截图捕获,并不会启用 Gateway 的桌面。在 macOS 上,远程管理也提供屏幕共享,但账户必须在系统设置 → 通用 → 共享 → 远程管理中拥有观察和控制权限。如果缺少这些权限,即使密码正确也可能被拒绝。OpenClaw 不会自动更改这些系统权限。

观察者令牌和观察者连接都绑定到请求它们的 Gateway 连接。结束或撤销该连接会使未使用的令牌失效,并以 4006 authority_revoked 关闭其观察者。没有 Gateway 连接的内部调用者仅保留带 TTL 的令牌。

{
  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 即可生效,并会更新已连接的桌面选择器。在 Labs 中关闭主机桌面会写入 enabled: false,关闭主机桌面观察,并保留其托管模式、端口和密码文件设置。现有的系统 VNC 或屏幕共享服务会继续运行。
  • desktop.host.managed:仅限 Linux。在首次观察或 computer 发现时惰性启动一个由 Gateway 监管、仅回环的 TigerVNC/XFCE 桌面。当桌面会话的驻留期结束,且没有观察者或进行中的 computer 执行持有它时,将其停止。默认值:false。
  • desktop.host.port:127.0.0.1 上的回环 RFB 端口(默认值:5900)。
  • desktop.host.passwordFile:供 attach 模式使用的可选 UTF-8 VNC 密码文件。若未提供,Control UI 会提示输入 VNC 密码,并将密码保留在浏览器内存中供该连接使用。托管模式始终会创建自己的临时密码。

对 managed、port 或 passwordFile 的更改会停用当前主机源,关闭其观察者,并释放其 computer 执行占用。替换后的主机源会按需启动,无需重启 Gateway。外部 VNC 服务器会继续运行。

OpenClaw 仅通过回环连接。显式指定 port 始终会选择 attach 模式;如果端口 5900 上已有 RFB 监听器,则它会优先于托管模式。托管模式需要 Xtigervnc、tigervncpasswd、startxfce4 和 dbus-daemon;在 Debian/Ubuntu 上,请安装 tigervnc-standalone-server tigervnc-tools xfce4-session dbus-daemon。Gateway 会为每个托管会话创建全新的临时 VNC 密码,绝不会持久化该密码,并监管 VNC 服务器、XFCE 会话和私有 D-Bus 会话。

若要允许 Agent 控制此桌面,请在 Gateway 主机上显式启用 cua-computer,并在其工具策略中公开 computer 工具。Gateway 和配对节点复用同一个 computer 提供程序;Gateway 拥有自己的桌面时不需要配对节点。其辅助程序会接收托管桌面的 X11 显示和私有 D-Bus 地址。关闭桌面面板会让进行中的 computer 执行保持存活;停止或重启桌面会在替换显示之前关闭该执行。参见 Computer use。

仅凭外部 VNC 流本身无法标识出 CUA 可以控制的原生显示。如果外部监听器优先于托管模式,托管计算机路由会报告该不匹配。在托管模式之外,Gateway 计算机使用其进程的原生桌面环境以及提供者的可用性检查。更新时现有配置和节点配对保持不变;启用 Desktop 面板不会自动启用 CUA。

如果桌面拆除失败,Gateway 会保留会话的清理所有者,并在其日志中报告该失败。新的观察结果会返回该失败,而不会重试清理或累积替代所有者。生命周期清理(例如在 Labs 中关闭 Host Desktop)会重试保留的所有者;只有在清理成功后才能启动替代者。对于 SSH 后端的 worker 桌面,临时连接文件会保留到传输关闭为止;进程延迟退出会触发另一次清理尝试。在重试清理之前,请检查所报告的进程或文件系统错误。

在托管模式之外,当第三方服务器支持时,请将其配置为在回环地址上监听。在 Linux 上,使用仅回环的 TigerVNC 或 x11vnc;不支持 GNOME Remote Desktop 的 VeNCrypt 模式。在 Windows 上,请在 VNC 服务器中启用 VNC 身份验证和回环访问。

在 macOS 上,启用 System Settings → General → Sharing → Screen Sharing。新版 Screen Sharing 使用 ARD 账户认证,因此 Gateway 会执行该握手,并向浏览器提供已经过身份验证的免认证 RFB 流。macOS 账户密码不会在观察结果、URL 或日志中返回。当 Screen Sharing 关闭时,openclaw doctor 可以提供经明确确认的 sudo launchctl 修复;根据 macOS Sharing 设置,启用 macOS 系统服务可能会将其暴露在其他网络接口上。

桌面音频

托管的 Linux Gateway 桌面可以将其应用程序音频发送到浏览器。在安装托管桌面依赖项的同时安装 pulseaudio 和 pulseaudio-utils,然后重启托管桌面并重新连接。每个托管桌面都拥有一个专用的 PulseAudio 服务器和虚拟输出设备;它不会捕获主机麦克风或其他桌面的输出。缺少音频依赖项时,屏幕仍可使用,但音频不可用。将光标悬停、聚焦或点击 Audio unavailable 即可查看设置指南,该指南会要求操作员检查这些软件包并重启托管桌面;原生错误详细信息和主机路径不会发送给查看者。如果专用音频无法启动,桌面应用程序将保留其先前的音频路由;该后备路由永远不会被采集给查看者。

如果专用音频服务器退出,Gateway 会在五分钟内重试其专用路由最多三次,独立于桌面进程恢复。现有流会停止;重新连接并取消静音即可再次收听,如有需要可重播应用程序音频。如果该路由无法恢复或其重试预算已用尽,音频将保持不可用,而不会关闭健康的桌面应用程序或计算机会话。仅在需要音频时才检查音频依赖项并重启托管桌面;操作员请求的重启可能会关闭应用程序。实际的 VNC、D-Bus 或桌面会话失败仍使用单独的桌面重启预算。

音频启动时处于静音状态。要收听,请在桌面工具栏中选择 Unmute audio;要停止采集和播放,请选择 Mute audio。点击后,您的浏览器必须允许音频。隐藏、断开或替换桌面会停止播放;新连接将以静音状态开始。音频授权与经过认证的屏幕连接绑定,并随其一起被撤销。

独立的 Desktop 视图也会在其触摸工具栏中提供 Unmute/Mute,其播放生命周期和静音启动规则与嵌入式面板相同。

此首条路径通过单独的经过认证的 WebSocket 使用未压缩的 48 kHz 立体声 PCM(收听时约为 1.5 Mbit/s)。缓冲是有上限的;无法跟上的连接会停止,而不会累积延迟的声音。它旨在用于桌面音频的首次实现,而非同步视频播放或低带宽流传输。

外部 VNC 服务器、配对节点桌面、云 worker 桌面、macOS 和 Windows 尚不支持音频。其工具栏会报告音频不可用。不支持麦克风转发。

配对节点桌面

升级会保留因从 Gateway 允许列表中移除 desktop.stream 而被禁用的桌面访问。当节点重新连接时,这些现有的桌面授权需要重新获得批准。其他节点能力和设备令牌保持不变,新节点使用已启用的默认值。现有的显式允许和拒绝条目仍然有效。一次性迁移会记录在现有的共享 SQLite 迁移台账中;它不会重写您的配置。Doctor 在导入较旧的配对文件时会应用相同的保留逻辑。

配对的 macOS、Windows 或 Linux 节点可以在同一个 Control UI 的 Desktop 面板和 Systems 中暴露自己的桌面。桌面共享默认启用,且始终使用 127.0.0.1 上现有的节点本地 RFB 服务器;Gateway 绝不会要求节点连接到调用者选择的主机或端口。

在 macOS 应用中,使用 Settings → This Mac → Capabilities → Desktop sharing。此选项控制运行该应用的 Mac,即使其仪表板连接到远程 Gateway 也是如此。更改此选项会自动重新连接节点。Computer Control 分别控制代理截图和输入;Keep computer awake 控制空闲休眠。桌面共享不会启用 macOS Screen Sharing:请先在 System Settings → General → Sharing 中将其开启。

Tauri 配套应用 在 Settings → This computer → Capabilities(macOS 上为 This Mac)下有相同的共享开关。它使用本地 CLI 将仅桌面节点连接到其主 Gateway。

CLI 节点在其本地配置中使用 desktop.host.enabled。缺少此设置时默认为启用;显式设置为 false 会禁用共享。现有的显式禁用设置在更新后仍保持禁用。桌面应用中的显式选择优先于该计算机的本地配置。

若要使用非默认端口或密码文件,请在节点上配置 attach 模式:

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

更改配置后,请重启 CLI 节点主机。managed: true 是 Gateway 主机功能,不会在节点主机内部启动受管桌面;已配对的 节点必须已经具有回环 RFB 服务器。

Gateway 允许已批准的桌面节点使用 desktop.stream,无需 额外的 gateway.nodes.commands.allow 条目。显式的 gateway.nodes.commands.deny 条目仍然优先。 更新现有节点后,其重新连接可以将 desktop.stream 作为配对表面升级进行通告。 检查 openclaw nodes pending,然后使用 openclaw nodes approve <requestId> 批准新请求。只有当节点处于连接状态,且有效已批准命令仍被允许时,该节点才会显示在桌面选择器中。

可见的选择器会随着节点连接或断开而更新。为某个会话或特定源打开的桌面 会在其分配节点可用时连接;自行打开选择器可保持源选择为手动。

对于 VncAuth,desktop.host.passwordFile 保留在节点上,并且只交付给 Gateway 的已认证中继。如果没有密码文件,Control UI 会提示输入 VNC 密码。macOS ARD 在你首次在桌面面板中连接到节点时会要求输入账户凭据。面板会将它们保存在内存中,用于重新连接到同一节点。关闭面板、选择另一个桌面或失去 Gateway 连接会清除它们;身份验证被拒绝时会再次要求输入密码。Gateway 会在向浏览器暴露无认证 RFB 握手之前完成 ARD 或 VNC 身份验证,因此凭据不会在 URL、日志或 RPC 结果中返回。

桌面字节流使用节点专用的出站二进制 WebSocket。常规 节点 invoke 仅保留为可取消的生命周期句柄,并且从不承载帧缓冲数据。重新连接或更改节点的配对代次会关闭活动中继。若要禁用该功能,请在 Mac 应用中关闭 桌面共享,在 CLI 节点上设置 desktop.host.enabled: false,或将 desktop.stream 添加到 Gateway 的 commands.deny。在默认混合重载模式下,Gateway 命令策略更改会应用于已连接节点,无需重启 Gateway 或重新连接节点。

如果节点未显示在选择器中,请检查桌面共享是否已启用、配对更新是否已批准,以及 Gateway 策略是否未拒绝该命令。如果查看器无法连接,请验证节点的回环 RFB 监听器。更改桌面配置后,请重启 CLI 节点主机,然后检查 openclaw nodes pending 中是否有扩展的声明。Gateway 策略更改会在现有配对批准范围内生效。


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