跳转至

配置 — 运行时基础

顶层运行时键：worktreeRoot、worktreeAcceleration、models.*、discovery.*、update.*、acp.* 和 wizard.*。

完整的键索引和其他顶层配置域，请参见配置参考。

worktreeRoot

用于受管工作树检出的可选全局根目录。默认值为 <openclaw-state-dir>/worktrees。

{
  worktreeRoot: "/mnt/workspaces/openclaw-worktrees",
}

请使用 Gateway 主机的绝对路径、表示 Gateway 用户家目录的 ~，或 ~/ 后跟其内部的一个文件夹；相对路径会被拒绝。OpenClaw 会在 <worktreeRoot>/<repo-fingerprint>/<name> 创建检出。此设置适用于所有代理和所有受管工作树所有者，且没有按代理覆盖。共享状态数据库和分配限制仍位于现有状态目录下。

更改仅影响新分配。已注册的工作树会保留其原始路径，以便复用、清理和快照恢复；现有检出不会自动移动。在仍需要这些记录时，请保持其原始存储可用。

worktreeAcceleration

用于受管工作树文件系统加速的可选全局布尔值。默认值为 true，会自动选择一个可用的文件系统后端，否则使用常规 Git 检出。

{
  worktreeAcceleration: false,
}

设置为 false 可对新工作树使用常规 Git 检出和文件复制。此选项适用于所有代理和受管工作树所有者；现有检出保持不变。支持的后端包括 Linux 上的 Btrfs 快照、macOS 上的 APFS 目录克隆，以及 Windows 上的 ReFS 块克隆。仓库配置和依赖项仍按工作树独立保留。

模型

提供商定义、模型允许列表和自定义提供商设置位于 配置 - 工具和自定义提供商。 models 根节点还负责全局模型目录行为。

{
  models: {
    // Optional. Hosted catalog updates default on.
    catalogRefresh: {
      enabled: true,
      // url: "https://catalog.example.com/openclaw/catalog.json",
    },
  },
}
  • models.mode：提供商目录行为（merge 或 replace）。
  • models.providers：以提供商 ID 为键的自定义提供商映射。
  • models.providers.*.localService：用于本地模型服务器的可选按需进程管理器。OpenClaw 会探测配置的健康检查端点，在需要时启动绝对路径 command，等待就绪，然后发送模型请求。参见本地模型服务。
  • models.catalogRefresh.enabled：控制托管模型目录刷新（默认：true）。将其设置为 false 可阻止所有远程目录请求；模型元数据和价格将保持为已安装版本中提供的值，或 models.providers.*.models[].cost 下声明的值。
  • models.catalogRefresh.url：可选的 HTTPS 镜像覆盖（仅当明确进行 localhost 测试时才接受纯 HTTP）。默认值为 https://catalog.openclaw.ai/models/v2/catalog.json。镜像可以提供 v1 或 v2。Gateway 会在启动时以及每六小时在后台检查。下载的目录将在下次 Gateway 重启时生效；捆绑目录较新的版本始终优先。

V2 在每行模型中包含价格。未知或不可用的价格并不意味着模型免费。目录外的模型（例如较旧的模型 ID 或通过网关路由的模型）使用同一文件中的独立费率：按供应商价格收费的网关只需读取该供应商的费率一次，无需为每个网关复制。显式模型成本仍优先。

价格更新与模型元数据一起包含在同一托管目录文件中。已弃用的 models.pricing 开关会由 openclaw doctor --fix 自动移除；当 OpenClaw 必须避免所有托管目录流量时，请使用 models.catalogRefresh.enabled: false。

发现

mDNS（Bonjour）

{
  discovery: {
    mdns: {
      mode: "minimal", // minimal | full | off
    },
  },
}
  • minimal（默认）：从 TXT 记录中省略 cliPath + sshPort。
  • full：包含 cliPath + sshPort；LAN 多播广播仍要求启用捆绑的 bonjour 插件。
  • off：在不更改插件启用状态的情况下，抑制 LAN 多播广播。
  • 捆绑的 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" },
  },
}

设置 discovery.wideArea.domain 可启用广域发现，并在 ~/.openclaw/dns/ 下写入一个单播 DNS-SD 区域。对于跨网络发现，请搭配 DNS 服务器（推荐 CoreDNS）+ Tailscale 拆分 DNS。

设置：openclaw dns setup --apply。

更新

{
  update: {
    channel: "stable", // stable | extended-stable | beta | dev
    checkOnStart: true,

    auto: {
      enabled: false,
    },
  },
}
  • channel：发布渠道 - "stable"、"extended-stable"、"beta" 或 "dev"。extended-stable 仅限包安装：前台命令负责安装，而 Gateway 可能发出只读更新提示。
  • checkOnStart：在 Gateway 启动时通过 https://telemetry.openclaw.ai/api/latest-version 检查更新，之后最多每 24 小时检查一次（默认：true）。默认请求仅在其 User-Agent 中共享 OpenClaw 版本和平台信息；仅当 telemetry.enabled 为 true 时才包含匿名功能统计。将此设置为 false，或设置 OPENCLAW_NO_AUTO_UPDATE=1，可阻止所有自动更新请求、功能统计和更新通知，即使 auto.enabled 为 true。已存储的 extended-stable 选择使用相同的只读提示和 24 小时提示计划。
  • auto.enabled：当 checkOnStart 也启用时，为 stable 和 beta 包安装以及 dev git 安装启用后台自动更新活动（默认：false）。extended-stable 永远不会自动应用。

无头节点具有独立的默认开启的 nodeHost.autoUpdate.enabled 策略，每小时检查且仅在空闲时激活。update.checkOnStart: false 和 OPENCLAW_NO_AUTO_UPDATE=1 也会禁用该策略。参见 无头节点更新。

ACP

{
  acp: {
    enabled: true,
    dispatch: { enabled: true },
    backend: "acpx",
    fallbacks: ["acpx-secondary"],
    defaultAgent: "main",
    allowedAgents: ["main", "ops"],
    stream: {
      repeatSuppression: true,
      deliveryMode: "live", // live | final_only
    },
  },
}
  • 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 目标 agent id。
  • allowedAgents：允许用于 ACP 运行时会话的 agent id 白名单；为空表示无额外限制。
  • stream.repeatSuppression：抑制每轮中重复的状态/工具行（默认：true）。
  • stream.deliveryMode："live" 增量流式传输；"final_only" 缓冲直到轮次终止事件。
  • stream.tagVisibility：流式事件的标签名到布尔可见性覆盖的映射。
  • runtime.installCommand：可选的安装命令，在引导 ACP 运行时环境时运行。

向导

CLI 引导式设置流程（onboard、configure、doctor）的行为和元数据：

{
  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。节点主机仍需要其独立的、默认关闭的已安装应用共享标志，才会广播该命令。

桥接（旧版，已移除）

当前构建不再包含 TCP 桥接。节点通过 Gateway WebSocket 连接。bridge.* 键不再是配置模式的一部分（在移除之前验证会失败；openclaw doctor --fix 可以移除未知键）。

旧版桥接配置（历史参考） 
{
  "bridge": {
    "enabled": true,
    "port": 18790,
    "bind": "tailnet",
    "tls": {
      "enabled": true,
      "autoGenerate": true
    }
  }
}

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