配置 — 运行时基础
顶层运行时键:worktreeRoot、worktreeAcceleration、worktreeMaxCount、models.*、discovery.*、update.*、acp.* 和 wizard.*。
完整的键索引及其他顶层配置域,请参阅 配置参考。
worktreeRoot¶
可选的全局根目录,用于 托管工作树 检出。默认为 <openclaw-state-dir>/worktrees。
使用 Gateway 主机上的绝对路径、~ 表示 Gateway 用户的主目录,或 ~/ 后跟其中的文件夹;相对路径将被拒绝。OpenClaw 在 <worktreeRoot>/<repo-fingerprint>/<name> 处创建检出。此设置适用于所有代理及所有托管工作树所有者,没有按代理覆盖的选项。共享状态数据库和分配限制仍位于现有状态目录下。
更改仅影响新的分配。已注册的工作树保留其原始路径,用于复用、清理和快照恢复;现有检出不会自动移动。在这些记录仍然需要时,请保持其原始存储可用。
worktreeAcceleration¶
可选的全局布尔值,用于 托管工作树文件系统加速。默认为 true,会自动选择可用的文件系统后端,否则使用普通的 Git 检出。
设置为 false 以对新工作树使用普通的 Git 检出和文件复制。此选项适用于所有代理及托管工作树所有者;现有检出保持不变。支持的后端包括 Linux 上的 Btrfs 快照、macOS 上的 APFS 目录克隆以及 Windows 上的 ReFS 块克隆。仓库设置和依赖项仍按工作树各自管理。
worktreeMaxCount¶
可选的正整数,限制同一 OpenClaw 状态目录下所有代理、仓库和所有者的活动 托管工作树 数量。默认为 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)¶
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/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可在引导式或经典入门期间禁用已安装应用推荐,并阻止 Gatewaydevice.apps访问。节点主机仍需要它们单独的、默认关闭的已安装应用共享标志,然后才会广播该命令。
桥接(旧版,已移除)¶
当前构建不再包含 TCP 桥接。节点通过 Gateway WebSocket 连接。bridge.* 键不再是配置模式的一部分(在移除之前验证会失败;openclaw doctor --fix 可以移除未知键)。
旧版桥接配置(历史参考)
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw