跳转至

配置 — 运行时基础

顶层运行时键:worktreeRoot、worktreeAcceleration、worktreeMaxCount、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 块克隆。仓库设置和依赖项仍按工作树各自管理。

worktreeMaxCount

可选的正整数,限制同一 OpenClaw 状态目录下所有代理、仓库和所有者的活动 托管工作树 数量。默认为 4096。已移除但保留恢复快照的检出不计入此限制。

{
  worktreeMaxCount: 4096,
}

该上限会被强制执行:清理会先清除已合并或已压缩的分支,然后按最后使用时间清除空闲工作树,包括手动检出和未保存的数据。上限驱逐期间的快照捕获为尽力而为;快照失败不会阻止清除。因此,降低上限可能会移除现有检出。正在运行的任务仍受保护;如果没有其他检出可被驱逐,创建将失败,错误中会包含上限和活动所有者。请提高 worktreeMaxCount 或等待这些运行结束后再重试。

后台维护和创建使用相同的驱逐所有者。并发创建不能各自占用最后一个槽位。即使配置的计数留有空间,磁盘空间准入仍是独立的守卫。

模型

提供方定义、模型允许列表和自定义提供方设置位于 配置 - 工具与自定义提供方。 models 根键还掌管全局模型目录行为。

{
  models: {
    // 可选。托管目录更新默认开启。
    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 镜像覆盖(仅对显式本地主机测试接受普通 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 split 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