人工智能AI 应用桌面应用交互助手【免费下载链接】ClawXClawX is a desktop app that provides a graphical interface for OpenClaw AI agents. It turns CLI-based AI orchestration into a desktop experience without using the terminal. China website is https://clawx.com.cn.项目地址https://gitcode.com/gh_mirrors/cl/ClawX点击查看免费下载ClawX 作为 OpenClaw AI Agent 的桌面图形化前端将 CLI 形态的 AI 编排转换为无需终端的桌面体验其中最关键的一环是如何安全、一致地把 ClawX 内的 Provider、Agent、Channel、Skill、代理proxy、图像生成与插件安装等配置变更投递给随附的 OpenClaw Gateway。本文以仓库规则文档 openclaw-config-delivery.md 与其参考实现 openclaw-config-delivery.md 为主体结合 config-delivery.ts 源码与 gateway-config-delivery.test.ts 测试用例讲解 ClawX 如何通过单一协调器 Mutator 重放模型实现配置投递读完本文你将掌握其运行时快照选择、base-hash 冲突重试、Redacted 密钥保护、文件回退与 WebSocket 跟踪脱敏的完整工作原理。一、为什么需要配置投递协调器write-then-notify 的陷阱ClawX 随附 OpenClaw 2026.7.1-2见 config-delivery.ts 注释与测试中的lastTouchedVersion断言。OpenClaw Gateway 在字段级别自行决定一次配置变更究竟触发无操作快照更新no-op snapshot update、热应用hot application、子系统重启还是进程内 Gateway 重启。因此 ClawX 的职责不是替 Gateway 规划重启策略而是把配置变更完整、安全地送达 Gateway。规则文档明确了两条核心红线ClawX 必须把运行时配置规划让渡给随附的 OpenClaw GatewayClawX must defer runtime config planning to the bundled OpenClaw Gateway。Main 进程拥有的配置协调器必须独占整个 read-modify-write 事务任何生产环境的辅助模块都不得先写活动配置、再事后通知其他层Production helpers must not write the active OpenClaw config and then notify another layer afterward。这正是文档反复强调的这不是 write-then-notify 设计This is not a write-then-notify design。参考文档点名了受影响的范围Provider、Agent、Channel、Skill、proxy、image-generation、plugin-install 的辅助函数一律以Mutator变更函数的形式表达配置变更由唯一的协调器统一决定权威基线并提交任何辅助模块都不能独立写活动配置否则一个本地读到的过期快照就可能覆盖并发中的 Gateway 或 CLI 配置变更。从源码看这条规则的落点集中在 config-delivery.ts它导出了mutateOpenClawConfig、readOpenClawConfigSnapshot、registerOpenClawConfigCoordinator、restoreRedactedSentinelsFromBaseline等入口并以transactionTail串联所有读改写事务实现串行化serializes concurrent read-modify-write transactions测试用例验证了并发事务会依次排队。二、Mutator 协议可重放的纯变换协调器要求所有 Mutator 都是可重放的变换replayable transformations约束包括不得执行文件系统写入、SQLite 写入、设置写入、生命周期动作或其他非幂等的外部副作用必须在进入 Mutator 之前预载所需的外部输入后续副作用只能在提交成功之后执行。源码中的类型定义印证了这一契约config-delivery.ts/** Mutators may be replayed after a compare-and-swap conflict and must not perform external writes. */ export type OpenClawConfigMutator ( config: OpenClawConfig, ) void | Promisevoid; /** Runs inside the serialized transaction before each pure mutator application. */ export type OpenClawConfigBeforeApply () void | Promisevoid; export type OpenClawConfigMutationOptions { beforeApply?: OpenClawConfigBeforeApply; };测试 gateway-config-delivery.test.ts 中runs transaction-serialized before-apply validation before each pure mutator replay用例验证了base-hash 冲突触发重放时beforeApply校验会在每一次Mutator 应用之前执行事件序列为validate, mutate:1, validate, mutate:4保证重放路径与首次路径行为一致。三、Gateway 运行时的提交主流程config.get → 克隆 → config.set当 Gateway 处于运行状态时协调器遵循五步主流程参考文档第 14 步调用config.get取得运行时快照要求其中包含运行时形态的config对象与hash。raw仅在旧版本响应缺失config时作为兼容回退compatibility fallback。克隆运行时形态的 config应用 Mutator然后以序列化结果调用config.set并携带baseHash: hash。首选 source-shapedraw作为基线是错误的——它的脱敏密钥路径可能与 OpenClaw 运行时形态的恢复基线错位Using source-shaped raw as the preferred baseline can misalign redacted secret paths with OpenClaws runtime-shaped restore baseline。冲突处理base-hash 冲突错误消息形如config changed since last load; re-run config.get and retry从一次全新的config.get重试一次其他 RPC 错误失败关闭fail closed绝不绕过运行中的 Gateway 去做带外文件写入。提交成功后视为收敛converged不再发送SIGUSR1也不再安排多余的 ClawX 进程替换。源码中的mutateRunningConfigconfig-delivery.ts精确实现了该流程循环最多两次第一次从manager.rpc(config.get, {})取快照与 hashparseRunningConfigSnapshot优先使用snapshot.config运行时形态仅在缺失时回退解析snapshot.raw应用 Mutator 后调用manager.rpc(config.set, { raw: serializeConfig(config), baseHash: hash })。测试用例mutates the running Gateway snapshot and commits it with its base hash给出了完整的行为断言config.set的第二个参数必须是{ raw: 序列化 JSON, baseHash: hash-1 }且提交后不得调用gatewayManager.restart或process.kill——这正是不发送 SIGUSR1 / 不做冗余重启的代码级证据。3.1 为什么以运行时形态 config 为基线config.get返回的config是 OpenClaw 的运行时形态runtime-shaped快照raw是源形态source-shaped序列化文本。两者在字段布局上可能不一致例如 binding 的归属字段。测试uses the runtime-shaped config snapshot when OpenClaw also returns source-shaped raw专门构造了raw与config字段不同的场景断言提交内容以configruntimeOnly: true为准而非rawsourceOnly: true。更深层的原因是脱敏路径对齐config.get会把敏感值替换为占位符__OPENCLAW_REDACTED__源码常量OPENCLAW_REDACTED_SENTINEL见 config-delivery.tsconfig.set会根据基线快照把这些占位符还原为真实密钥。如果 ClawX 以源形态raw作为首选基线占位符出现的路径就可能与 OpenClaw 运行时写侧的还原基线不一致导致真实密钥被占位符覆盖。3.2 无操作no-op提交的短路协调器通过applyMutator在应用前后做isDeepStrictEqual比较config-delivery.ts如果 Mutator 没有产生任何字段变化则直接返回false不会发起config.set。测试does not commit a no-op mutation验证Mutator 把value从 1 写成 1 时RPC 只发生一次config.get绝无config.set。四、代码 1012 重载下的响应丢失验证持久化而非盲目重放OpenClaw 的config.set可能先持久化落盘、随后因进程内 1012 重载code-1012 in-process restart关闭 WebSocket导致 RPC 响应丢失。协调器的处理分两条路径可验证时接受既有提交若config.set已按请求精确落盘协调器会在 Gateway 离开运行状态后校验持久化快照与提交内容等价isPersistedConfigSetCommitEquivalent确认一致就直接接受该提交不重放、不重写。无法验证时重放并还原密钥若无法确认落盘则对持久化文件重放 Mutator重放前必须先保存Mutator 前的文件快照重放后把__OPENCLAW_REDACTED__字段从该快照还原回来避免脱敏的运行时编辑覆盖真实密钥。源码用isConfigSetResponseLost判定响应丢失匹配RPC timeout: config.set或 Gateway 不可用错误并用acceptPersistedConfigSetCommitIfMatched读取解析后的活动配置文件、剥离 OpenClaw 自动维护的meta.lastTouchedAt/lastTouchedVersion后做递归等价比较config-delivery.ts。递归比较isPersistedValueEquivalent的特殊之处在于提交侧的__OPENCLAW_REDACTED__占位符与持久化侧的任意真实值视为等价——这正是脱敏占位符在 config.get 中往返、config.set 自行还原语义的映射。测试矩阵覆盖了这条路径的各个分支accepts a config.set commit whose response is lost to a native restartconfig.set写盘后抛Gateway stopped协调器读盘校验后接受且不触发 restartaccepts a config.set commit after RPC timeout when the snapshot was persisted抛RPC timeout: config.set但快照已落盘仍接受accepts a config.set commit after a 1012 service restart when the snapshot was persisted抛Gateway service restart接受accepts a lost config.set commit although OpenClaw stamped meta and restored redacted secrets持久化侧出现了meta.lastTouched*与真实密钥real-secret-token等价比较仍通过rejects a lost config.set commit when the persisted snapshot differs beyond meta and redaction持久化侧仍是旧值等价比较失败异常向上抛出does not persist redacted sentinels when a lost config.set is replayed to the file重放路径下appSecret保持文件中的real-secret而非占位符——这是restoreRedactedSentinelsFromBaseline的核心价值config-delivery.ts单测restoreRedactedSentinelsFromBaseline还验证了保留无关字段、仅替换占位符的行为。五、Gateway 停止/启动中的文件回退路径当 Gateway 处于stopped 或 starting状态时协调器对resolveOpenClawConfigPath()解析出的配置文件应用同一个 Mutator并持有共享配置锁withConfigLock规则明确不得为了应用配置变更而专门启动 GatewayIt must not start the Gateway solely to apply a config mutation。源码mutateFileConfigconfig-delivery.ts实现了这条回退路径在共享锁内解析configPath用 JSON5 解析parseConfig使用JSON5.parse因为 OpenClaw 配置文件允许 JSON5 语法如注释与尾逗号应用 Mutator 后调用restoreRedactedSentinelsFromBaseline还原占位符若快照未变化直接返回false落盘采用同目录临时文件 rename 原子替换${configPath}.${pid}.${uuid}.tmpmode: 0o600保证权限随后rename到目标路径测试atomically replaces the fallback file with a same-directory temporary file断言了临时文件命名与 rename 目标落盘前会再次校验文件内容是否被外部写者改动currentRaw ! snapshot.raw若被改动则重试一次第二次仍冲突则抛出OpenClaw config changed during file mutation; retry the mutation——这与 base-hash 冲突的重试一次策略对称路径切换如果在文件提交过程中 Gateway 恰好转为 running协调器会放弃文件路径、改走运行中 RPC 事务测试switches to a fresh running RPC transaction when the Gateway starts before file commit验证了getStatus依次返回stopped → running时的行为。此外即使注册了协调器若没有 Gateway Manager 或 Gateway 不可用文件路径同样生效uses file fallback without starting a Gateway when no manager is registered。六、Gateway 不可用时的整体重放逻辑runMutationconfig-delivery.ts展示了运行中事务中途掉线的兜底若config.set/config.get期间抛出的错误被isGatewayUnavailableError判定为 Gateway 不可用匹配Gateway stopped、Gateway not connected、Gateway service restart、Failed to send RPC request:则落回文件路径重放。源码注释解释了原因Mutator 是纯且可重放的——已落地的提交重放后变成无操作丢失的提交则由 ClawX 补写且一旦 Gateway 恢复运行文件路径会自动切回 RPC。测试replays the mutator through the file path when the Gateway drops during config.get与replays the mutator through the file path when a lost config.set cannot be verified分别覆盖了config.get阶段与config.set阶段掉线时的文件重放。七、读取侧的权威规则运行时快照优先JSON5 文件兜底协调器背书的读取runReadconfig-delivery.ts遵循同样的权威规则Gateway 运行时优先返回config.get.config运行时形态对象exists: trueGateway 停止时使用 JSON5 文件解析readFileConfig遇ENOENT返回空对象与exists: false复合视图compound views所有配置支撑字段都取自同一个快照避免字段间来自不同时点的拼接若运行中config.get因 Gateway 服务重启失败同样回退到持久化文件测试reads the durable file when config.get is rejected by a Gateway service restart。测试还验证了两条读取语义reads the running Gateway snapshot instead of a stale local file本地文件写有localOnly但 RPC 返回gatewayOnly读取结果以 RPC 为准与reads JSON5 from the resolved file while the Gateway is stopped注释型 JSON5 可正常解析。另外readDurableOpenClawConfigconfig-delivery.ts提供了一个永远读磁盘文件、绝不读脱敏快照的专用入口用于需要真实密钥值的场景。八、配置路径的唯一权威resolveOpenClawConfigPath规则要求协调器的所有文件回退读写都必须通过resolveOpenClawConfigPath()解析活动配置保证文件投递与 Gateway RPC 指向同一个配置并且任何其他生产模块都不得写这个文件No other production module may write that file。该函数位于 paths.tsexport function resolveOpenClawConfigPath(env: NodeJS.ProcessEnv process.env): string { const configured env.OPENCLAW_CONFIG_PATH?.trim(); return resolve(expandPath(configured || join(resolveOpenClawStateDir(env), openclaw.json))); }其解析优先级为OPENCLAW_CONFIG_PATH环境变量支持~展开→ 默认~/.openclaw/openclaw.jsonOPENCLAW_STATE_DIR可覆盖状态目录。测试通过设置OPENCLAW_CONFIG_PATH指向临时目录来隔离每个用例侧面印证了该环境变量的真实语义。九、WebSocket 跟踪脱敏整段 raw 必须打码Gateway WebSocket 跟踪trace必须把config.set、config.patch、config.apply的序列化raw写载荷替换为脱敏标记因为基于键名的结构性脱敏无法检查嵌入在该字符串内部的密钥key-based structural redaction cannot inspect secrets embedded inside that string而且不得记录 Mutator 引入的凭据。实现位于 ws-trace.tsCONFIG_WRITE_METHODS new Set([config.set, config.patch, config.apply])redactGatewayFrameForTrace在方法命中集合时把params.raw整体替换为[redacted]普通帧则按SECRET_KEYStoken、authorization、apikey、api_key、signature、cookie、set-cookie、accesstoken、refreshtoken逐键脱敏。跟踪开关为环境变量CLAWX_GATEWAY_WS_TRACE 1。十、密钥刷新与 Agent models.json 的旁路策略OpenClaw 2026.7.1-2 会把 auth-profile 的 SQLite 快照保存在内存中。因此在一个完整的 auth-store 写批次完成后只要 Gateway 运行中ClawX 就会调用一次secrets.reloadconfig.set不能替代这次刷新。实现为reloadOpenClawSecretsIfRunning/runSecretsReloadconfig-delivery.ts仅在running状态调用manager.rpc(secrets.reload, {})。Agent 的models.json则不需要显式 RPC——OpenClaw 会在其文件指纹fingerprint变化时自行重新读取。十一、升级前的兼容清理update-check 状态裁决在启动前升级兼容清理quarantineLegacyUpdateCheckState见 openclaw-upgrade-snapshot.ts会检查规范的state/openclaw.sqlite更新检查行若 SQLite 中已存在该行hasCanonicalUpdateCheckState则 SQLite 行是权威遗留的根级update-check.json会被以受限权限移动到backups/文件名clawx-UPGRADE_ID-legacy-update-check.json若 SQLite 尚无该行则保留 JSON 在原地交给 OpenClaw 导入。该清理运行在一次性升级快照one-time upgrade snapshot之后目的是防止无害的更新器簿记差异阻塞 Gateway 就绪或触发无效的 doctor 重试。它由 config-sync.ts 的prepareGatewayLaunchContext在启动前调用。快照会在原生 ready 事件或成功的 RPC-router 就绪回退之后移除removeOpenClaw2026_7_1UpgradeSnapshotopenclaw-upgrade-snapshot.ts以覆盖快速 Gateway 在 ClawX 挂接 WebSocket 客户端之前就已发出就绪的竞态。十二、仍然需要完整进程替换的边界规则明确以下场景在协调器提交成功后仍需要完整的 ClawX 进程替换仅能在进程创建时注入的值发生变化——典型代表是proxy 环境变量如buildProxyEnv构造的 HTTP(S)/ALL_PROXY 环境见 config-sync.ts用户显式的手动生命周期操作健康/崩溃恢复。反过来Provider、Agent、Channel、binding、skill、model 与普通 plugin-entry 的配置变更不得携带一刀切的 ClawX 重启策略——凡是 OpenClaw 能规划生效方式的变更都应交给 Gateway 决策OpenClaw 配置类别绝不能复制成一份 ClawX 重启白名单OpenClaw config categories must not be duplicated as a ClawX restart whitelist。十三、总结一份可以持续演进的配置投递契约ClawX 的 OpenClaw 配置投递可以概括为一组可验证的不变量单一协调器所有配置变更表达为纯 Mutator由 config-delivery.ts 串行执行 read-modify-write运行时快照优先运行中以config.get.configbaseHash提交config.setraw仅为兼容回退冲突有限重试base-hash 冲突重试一次文件外部改写冲突重试一次其余错误 fail closed密钥永不丢失脱敏占位符在重放文件路径时通过基线快照还原WebSocket 跟踪对配置写载荷整体打码文件与 RPC 同源文件回退统一经resolveOpenClawConfigPath()解析其他模块不得直写该文件收敛即止提交成功不发送SIGUSR1、不安排冗余进程替换只有进程创建期注入值如代理环境与显式生命周期/恢复才触发整进程替换。这份契约同时被规则文档harness/specs/rules/openclaw-config-delivery.md、参考文档harness/reference/openclaw-config-delivery.md与覆盖 30 场景的单元测试tests/unit/gateway-config-delivery.test.ts三方锁定任何新增的配置类别接入者都可以直接复用mutateOpenClawConfig而无须触碰 Gateway 内部规划逻辑。赞分享人工智能AI 应用桌面应用交互助手【免费下载链接】ClawXClawX is a desktop app that provides a graphical interface for OpenClaw AI agents. It turns CLI-based AI orchestration into a desktop experience without using the terminal. China website is https://clawx.com.cn.项目地址https://gitcode.com/gh_mirrors/cl/ClawX点击查看免费下载相关推荐ClawX OpenClaw 配置投递机制深度解析单一协调器、Mutator 事务与安全提交ClawX OpenClaw 配置投递机制深度解析单一协调器、Mutator 事务与安全提交 导读 本文围绕 ClawX 的 OpenClaw 配置投递Co人工智能AI 应用桌面应用交互助手OpenClaw 如何在同一主机上运行多个隔离的 Gateway 并配置救援机器人OpenClaw 如何在同一主机上运行多个隔离的 Gateway 并配置救援机器人 在 OpenClaw 中绝大多数部署只需要一个 Gateway——单个AI 应用AI Agent交互助手后端即时通讯网关5分钟装好G-Helper一个免安装exe管好华硕笔记本性能5分钟装好G Helper一个免安装exe管好华硕笔记本性能 G Helper 是一款免费开源的华硕笔记本性能控制工具定位是 Armoury Crate奥桌面应用系统编程上一篇10分钟搭建Searx高可用集群从请求分发到智能负载均衡下一篇让每位用户都能顺畅选择Android-PickerView无障碍适配全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/28 6:53:31 · 阅读 1.2k ClawX 的 OpenClaw 配置投递机制：单一协调器下的 Gateway 运行时配置编排
人工智能AI 应用桌面应用交互助手【免费下载链接】ClawXClawX is a desktop app that provides a graphical interface for OpenClaw AI agents. It turns CLI-based AI orchestration into a desktop experience without using the terminal. China website is https://clawx.com.cn.项目地址https://gitcode.com/gh_mirrors/cl/ClawX点击查看免费下载ClawX 作为 OpenClaw AI Agent 的桌面图形化前端将 CLI 形态的 AI 编排转换为无需终端的桌面体验其中最关键的一环是如何安全、一致地把 ClawX 内的 Provider、Agent、Channel、Skill、代理proxy、图像生成与插件安装等配置变更投递给随附的 OpenClaw Gateway。本文以仓库规则文档 openclaw-config-delivery.md 与其参考实现 openclaw-config-delivery.md 为主体结合 config-delivery.ts 源码与 gateway-config-delivery.test.ts 测试用例讲解 ClawX 如何通过单一协调器 Mutator 重放模型实现配置投递读完本文你将掌握其运行时快照选择、base-hash 冲突重试、Redacted 密钥保护、文件回退与 WebSocket 跟踪脱敏的完整工作原理。一、为什么需要配置投递协调器write-then-notify 的陷阱ClawX 随附 OpenClaw 2026.7.1-2见 config-delivery.ts 注释与测试中的lastTouchedVersion断言。OpenClaw Gateway 在字段级别自行决定一次配置变更究竟触发无操作快照更新no-op snapshot update、热应用hot application、子系统重启还是进程内 Gateway 重启。因此 ClawX 的职责不是替 Gateway 规划重启策略而是把配置变更完整、安全地送达 Gateway。规则文档明确了两条核心红线ClawX 必须把运行时配置规划让渡给随附的 OpenClaw GatewayClawX must defer runtime config planning to the bundled OpenClaw Gateway。Main 进程拥有的配置协调器必须独占整个 read-modify-write 事务任何生产环境的辅助模块都不得先写活动配置、再事后通知其他层Production helpers must not write the active OpenClaw config and then notify another layer afterward。这正是文档反复强调的这不是 write-then-notify 设计This is not a write-then-notify design。参考文档点名了受影响的范围Provider、Agent、Channel、Skill、proxy、image-generation、plugin-install 的辅助函数一律以Mutator变更函数的形式表达配置变更由唯一的协调器统一决定权威基线并提交任何辅助模块都不能独立写活动配置否则一个本地读到的过期快照就可能覆盖并发中的 Gateway 或 CLI 配置变更。从源码看这条规则的落点集中在 config-delivery.ts它导出了mutateOpenClawConfig、readOpenClawConfigSnapshot、registerOpenClawConfigCoordinator、restoreRedactedSentinelsFromBaseline等入口并以transactionTail串联所有读改写事务实现串行化serializes concurrent read-modify-write transactions测试用例验证了并发事务会依次排队。二、Mutator 协议可重放的纯变换协调器要求所有 Mutator 都是可重放的变换replayable transformations约束包括不得执行文件系统写入、SQLite 写入、设置写入、生命周期动作或其他非幂等的外部副作用必须在进入 Mutator 之前预载所需的外部输入后续副作用只能在提交成功之后执行。源码中的类型定义印证了这一契约config-delivery.ts/** Mutators may be replayed after a compare-and-swap conflict and must not perform external writes. */ export type OpenClawConfigMutator ( config: OpenClawConfig, ) void | Promisevoid; /** Runs inside the serialized transaction before each pure mutator application. */ export type OpenClawConfigBeforeApply () void | Promisevoid; export type OpenClawConfigMutationOptions { beforeApply?: OpenClawConfigBeforeApply; };测试 gateway-config-delivery.test.ts 中runs transaction-serialized before-apply validation before each pure mutator replay用例验证了base-hash 冲突触发重放时beforeApply校验会在每一次Mutator 应用之前执行事件序列为validate, mutate:1, validate, mutate:4保证重放路径与首次路径行为一致。三、Gateway 运行时的提交主流程config.get → 克隆 → config.set当 Gateway 处于运行状态时协调器遵循五步主流程参考文档第 14 步调用config.get取得运行时快照要求其中包含运行时形态的config对象与hash。raw仅在旧版本响应缺失config时作为兼容回退compatibility fallback。克隆运行时形态的 config应用 Mutator然后以序列化结果调用config.set并携带baseHash: hash。首选 source-shapedraw作为基线是错误的——它的脱敏密钥路径可能与 OpenClaw 运行时形态的恢复基线错位Using source-shaped raw as the preferred baseline can misalign redacted secret paths with OpenClaws runtime-shaped restore baseline。冲突处理base-hash 冲突错误消息形如config changed since last load; re-run config.get and retry从一次全新的config.get重试一次其他 RPC 错误失败关闭fail closed绝不绕过运行中的 Gateway 去做带外文件写入。提交成功后视为收敛converged不再发送SIGUSR1也不再安排多余的 ClawX 进程替换。源码中的mutateRunningConfigconfig-delivery.ts精确实现了该流程循环最多两次第一次从manager.rpc(config.get, {})取快照与 hashparseRunningConfigSnapshot优先使用snapshot.config运行时形态仅在缺失时回退解析snapshot.raw应用 Mutator 后调用manager.rpc(config.set, { raw: serializeConfig(config), baseHash: hash })。测试用例mutates the running Gateway snapshot and commits it with its base hash给出了完整的行为断言config.set的第二个参数必须是{ raw: 序列化 JSON, baseHash: hash-1 }且提交后不得调用gatewayManager.restart或process.kill——这正是不发送 SIGUSR1 / 不做冗余重启的代码级证据。3.1 为什么以运行时形态 config 为基线config.get返回的config是 OpenClaw 的运行时形态runtime-shaped快照raw是源形态source-shaped序列化文本。两者在字段布局上可能不一致例如 binding 的归属字段。测试uses the runtime-shaped config snapshot when OpenClaw also returns source-shaped raw专门构造了raw与config字段不同的场景断言提交内容以configruntimeOnly: true为准而非rawsourceOnly: true。更深层的原因是脱敏路径对齐config.get会把敏感值替换为占位符__OPENCLAW_REDACTED__源码常量OPENCLAW_REDACTED_SENTINEL见 config-delivery.tsconfig.set会根据基线快照把这些占位符还原为真实密钥。如果 ClawX 以源形态raw作为首选基线占位符出现的路径就可能与 OpenClaw 运行时写侧的还原基线不一致导致真实密钥被占位符覆盖。3.2 无操作no-op提交的短路协调器通过applyMutator在应用前后做isDeepStrictEqual比较config-delivery.ts如果 Mutator 没有产生任何字段变化则直接返回false不会发起config.set。测试does not commit a no-op mutation验证Mutator 把value从 1 写成 1 时RPC 只发生一次config.get绝无config.set。四、代码 1012 重载下的响应丢失验证持久化而非盲目重放OpenClaw 的config.set可能先持久化落盘、随后因进程内 1012 重载code-1012 in-process restart关闭 WebSocket导致 RPC 响应丢失。协调器的处理分两条路径可验证时接受既有提交若config.set已按请求精确落盘协调器会在 Gateway 离开运行状态后校验持久化快照与提交内容等价isPersistedConfigSetCommitEquivalent确认一致就直接接受该提交不重放、不重写。无法验证时重放并还原密钥若无法确认落盘则对持久化文件重放 Mutator重放前必须先保存Mutator 前的文件快照重放后把__OPENCLAW_REDACTED__字段从该快照还原回来避免脱敏的运行时编辑覆盖真实密钥。源码用isConfigSetResponseLost判定响应丢失匹配RPC timeout: config.set或 Gateway 不可用错误并用acceptPersistedConfigSetCommitIfMatched读取解析后的活动配置文件、剥离 OpenClaw 自动维护的meta.lastTouchedAt/lastTouchedVersion后做递归等价比较config-delivery.ts。递归比较isPersistedValueEquivalent的特殊之处在于提交侧的__OPENCLAW_REDACTED__占位符与持久化侧的任意真实值视为等价——这正是脱敏占位符在 config.get 中往返、config.set 自行还原语义的映射。测试矩阵覆盖了这条路径的各个分支accepts a config.set commit whose response is lost to a native restartconfig.set写盘后抛Gateway stopped协调器读盘校验后接受且不触发 restartaccepts a config.set commit after RPC timeout when the snapshot was persisted抛RPC timeout: config.set但快照已落盘仍接受accepts a config.set commit after a 1012 service restart when the snapshot was persisted抛Gateway service restart接受accepts a lost config.set commit although OpenClaw stamped meta and restored redacted secrets持久化侧出现了meta.lastTouched*与真实密钥real-secret-token等价比较仍通过rejects a lost config.set commit when the persisted snapshot differs beyond meta and redaction持久化侧仍是旧值等价比较失败异常向上抛出does not persist redacted sentinels when a lost config.set is replayed to the file重放路径下appSecret保持文件中的real-secret而非占位符——这是restoreRedactedSentinelsFromBaseline的核心价值config-delivery.ts单测restoreRedactedSentinelsFromBaseline还验证了保留无关字段、仅替换占位符的行为。五、Gateway 停止/启动中的文件回退路径当 Gateway 处于stopped 或 starting状态时协调器对resolveOpenClawConfigPath()解析出的配置文件应用同一个 Mutator并持有共享配置锁withConfigLock规则明确不得为了应用配置变更而专门启动 GatewayIt must not start the Gateway solely to apply a config mutation。源码mutateFileConfigconfig-delivery.ts实现了这条回退路径在共享锁内解析configPath用 JSON5 解析parseConfig使用JSON5.parse因为 OpenClaw 配置文件允许 JSON5 语法如注释与尾逗号应用 Mutator 后调用restoreRedactedSentinelsFromBaseline还原占位符若快照未变化直接返回false落盘采用同目录临时文件 rename 原子替换${configPath}.${pid}.${uuid}.tmpmode: 0o600保证权限随后rename到目标路径测试atomically replaces the fallback file with a same-directory temporary file断言了临时文件命名与 rename 目标落盘前会再次校验文件内容是否被外部写者改动currentRaw ! snapshot.raw若被改动则重试一次第二次仍冲突则抛出OpenClaw config changed during file mutation; retry the mutation——这与 base-hash 冲突的重试一次策略对称路径切换如果在文件提交过程中 Gateway 恰好转为 running协调器会放弃文件路径、改走运行中 RPC 事务测试switches to a fresh running RPC transaction when the Gateway starts before file commit验证了getStatus依次返回stopped → running时的行为。此外即使注册了协调器若没有 Gateway Manager 或 Gateway 不可用文件路径同样生效uses file fallback without starting a Gateway when no manager is registered。六、Gateway 不可用时的整体重放逻辑runMutationconfig-delivery.ts展示了运行中事务中途掉线的兜底若config.set/config.get期间抛出的错误被isGatewayUnavailableError判定为 Gateway 不可用匹配Gateway stopped、Gateway not connected、Gateway service restart、Failed to send RPC request:则落回文件路径重放。源码注释解释了原因Mutator 是纯且可重放的——已落地的提交重放后变成无操作丢失的提交则由 ClawX 补写且一旦 Gateway 恢复运行文件路径会自动切回 RPC。测试replays the mutator through the file path when the Gateway drops during config.get与replays the mutator through the file path when a lost config.set cannot be verified分别覆盖了config.get阶段与config.set阶段掉线时的文件重放。七、读取侧的权威规则运行时快照优先JSON5 文件兜底协调器背书的读取runReadconfig-delivery.ts遵循同样的权威规则Gateway 运行时优先返回config.get.config运行时形态对象exists: trueGateway 停止时使用 JSON5 文件解析readFileConfig遇ENOENT返回空对象与exists: false复合视图compound views所有配置支撑字段都取自同一个快照避免字段间来自不同时点的拼接若运行中config.get因 Gateway 服务重启失败同样回退到持久化文件测试reads the durable file when config.get is rejected by a Gateway service restart。测试还验证了两条读取语义reads the running Gateway snapshot instead of a stale local file本地文件写有localOnly但 RPC 返回gatewayOnly读取结果以 RPC 为准与reads JSON5 from the resolved file while the Gateway is stopped注释型 JSON5 可正常解析。另外readDurableOpenClawConfigconfig-delivery.ts提供了一个永远读磁盘文件、绝不读脱敏快照的专用入口用于需要真实密钥值的场景。八、配置路径的唯一权威resolveOpenClawConfigPath规则要求协调器的所有文件回退读写都必须通过resolveOpenClawConfigPath()解析活动配置保证文件投递与 Gateway RPC 指向同一个配置并且任何其他生产模块都不得写这个文件No other production module may write that file。该函数位于 paths.tsexport function resolveOpenClawConfigPath(env: NodeJS.ProcessEnv process.env): string { const configured env.OPENCLAW_CONFIG_PATH?.trim(); return resolve(expandPath(configured || join(resolveOpenClawStateDir(env), openclaw.json))); }其解析优先级为OPENCLAW_CONFIG_PATH环境变量支持~展开→ 默认~/.openclaw/openclaw.jsonOPENCLAW_STATE_DIR可覆盖状态目录。测试通过设置OPENCLAW_CONFIG_PATH指向临时目录来隔离每个用例侧面印证了该环境变量的真实语义。九、WebSocket 跟踪脱敏整段 raw 必须打码Gateway WebSocket 跟踪trace必须把config.set、config.patch、config.apply的序列化raw写载荷替换为脱敏标记因为基于键名的结构性脱敏无法检查嵌入在该字符串内部的密钥key-based structural redaction cannot inspect secrets embedded inside that string而且不得记录 Mutator 引入的凭据。实现位于 ws-trace.tsCONFIG_WRITE_METHODS new Set([config.set, config.patch, config.apply])redactGatewayFrameForTrace在方法命中集合时把params.raw整体替换为[redacted]普通帧则按SECRET_KEYStoken、authorization、apikey、api_key、signature、cookie、set-cookie、accesstoken、refreshtoken逐键脱敏。跟踪开关为环境变量CLAWX_GATEWAY_WS_TRACE 1。十、密钥刷新与 Agent models.json 的旁路策略OpenClaw 2026.7.1-2 会把 auth-profile 的 SQLite 快照保存在内存中。因此在一个完整的 auth-store 写批次完成后只要 Gateway 运行中ClawX 就会调用一次secrets.reloadconfig.set不能替代这次刷新。实现为reloadOpenClawSecretsIfRunning/runSecretsReloadconfig-delivery.ts仅在running状态调用manager.rpc(secrets.reload, {})。Agent 的models.json则不需要显式 RPC——OpenClaw 会在其文件指纹fingerprint变化时自行重新读取。十一、升级前的兼容清理update-check 状态裁决在启动前升级兼容清理quarantineLegacyUpdateCheckState见 openclaw-upgrade-snapshot.ts会检查规范的state/openclaw.sqlite更新检查行若 SQLite 中已存在该行hasCanonicalUpdateCheckState则 SQLite 行是权威遗留的根级update-check.json会被以受限权限移动到backups/文件名clawx-UPGRADE_ID-legacy-update-check.json若 SQLite 尚无该行则保留 JSON 在原地交给 OpenClaw 导入。该清理运行在一次性升级快照one-time upgrade snapshot之后目的是防止无害的更新器簿记差异阻塞 Gateway 就绪或触发无效的 doctor 重试。它由 config-sync.ts 的prepareGatewayLaunchContext在启动前调用。快照会在原生 ready 事件或成功的 RPC-router 就绪回退之后移除removeOpenClaw2026_7_1UpgradeSnapshotopenclaw-upgrade-snapshot.ts以覆盖快速 Gateway 在 ClawX 挂接 WebSocket 客户端之前就已发出就绪的竞态。十二、仍然需要完整进程替换的边界规则明确以下场景在协调器提交成功后仍需要完整的 ClawX 进程替换仅能在进程创建时注入的值发生变化——典型代表是proxy 环境变量如buildProxyEnv构造的 HTTP(S)/ALL_PROXY 环境见 config-sync.ts用户显式的手动生命周期操作健康/崩溃恢复。反过来Provider、Agent、Channel、binding、skill、model 与普通 plugin-entry 的配置变更不得携带一刀切的 ClawX 重启策略——凡是 OpenClaw 能规划生效方式的变更都应交给 Gateway 决策OpenClaw 配置类别绝不能复制成一份 ClawX 重启白名单OpenClaw config categories must not be duplicated as a ClawX restart whitelist。十三、总结一份可以持续演进的配置投递契约ClawX 的 OpenClaw 配置投递可以概括为一组可验证的不变量单一协调器所有配置变更表达为纯 Mutator由 config-delivery.ts 串行执行 read-modify-write运行时快照优先运行中以config.get.configbaseHash提交config.setraw仅为兼容回退冲突有限重试base-hash 冲突重试一次文件外部改写冲突重试一次其余错误 fail closed密钥永不丢失脱敏占位符在重放文件路径时通过基线快照还原WebSocket 跟踪对配置写载荷整体打码文件与 RPC 同源文件回退统一经resolveOpenClawConfigPath()解析其他模块不得直写该文件收敛即止提交成功不发送SIGUSR1、不安排冗余进程替换只有进程创建期注入值如代理环境与显式生命周期/恢复才触发整进程替换。这份契约同时被规则文档harness/specs/rules/openclaw-config-delivery.md、参考文档harness/reference/openclaw-config-delivery.md与覆盖 30 场景的单元测试tests/unit/gateway-config-delivery.test.ts三方锁定任何新增的配置类别接入者都可以直接复用mutateOpenClawConfig而无须触碰 Gateway 内部规划逻辑。赞分享人工智能AI 应用桌面应用交互助手【免费下载链接】ClawXClawX is a desktop app that provides a graphical interface for OpenClaw AI agents. It turns CLI-based AI orchestration into a desktop experience without using the terminal. China website is https://clawx.com.cn.项目地址https://gitcode.com/gh_mirrors/cl/ClawX点击查看免费下载相关推荐ClawX OpenClaw 配置投递机制深度解析单一协调器、Mutator 事务与安全提交ClawX OpenClaw 配置投递机制深度解析单一协调器、Mutator 事务与安全提交 导读 本文围绕 ClawX 的 OpenClaw 配置投递Co人工智能AI 应用桌面应用交互助手OpenClaw 如何在同一主机上运行多个隔离的 Gateway 并配置救援机器人OpenClaw 如何在同一主机上运行多个隔离的 Gateway 并配置救援机器人 在 OpenClaw 中绝大多数部署只需要一个 Gateway——单个AI 应用AI Agent交互助手后端即时通讯网关5分钟装好G-Helper一个免安装exe管好华硕笔记本性能5分钟装好G Helper一个免安装exe管好华硕笔记本性能 G Helper 是一款免费开源的华硕笔记本性能控制工具定位是 Armoury Crate奥桌面应用系统编程上一篇10分钟搭建Searx高可用集群从请求分发到智能负载均衡下一篇让每位用户都能顺畅选择Android-PickerView无障碍适配全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考