提示：AI 结果必须带引用；若证据不足会提示“未找到可靠证据”。

OpenClaw Manager Native 配置中心：信息架构与 Daemon API 草案（2026-03-13）

关联文档：
OpenClaw 本地配置可视化管理：分析报告与技术方案（2026-03-13）
本文继续向前推进，输出可直接用于研发拆解的页面信息架构与本地 daemon API 草案。
说明：本文仍然只做方案设计，不包含业务代码改动。

1. 设计目标

本稿的目标不是“再加一个设置页”，而是定义一套能够支撑下面这件事的产品与接口结构：

用户在 OpenClaw Manager Native 中查看、理解、验证并修改本机 OpenClaw 配置，并管理 skills 列表与基础生命周期

在这个目标下，配置中心必须同时满足四个要求：

普通用户可理解
- 先给当前判断，再给字段，再给动作
多 profile 可管理
- 兼容 .openclaw 与 .openclaw-*
写入安全
- 必须有校验、差异预览、冲突控制、备份与回滚
与官方能力对齐
- 尽量利用 OpenClaw 官方 config.get / patch / apply、schema、热重载语义

2. 约束与前提

2.1 官方约束

根据 OpenClaw 当前官方文档，配置管理至少具备以下事实：

默认配置路径是 ~/.openclaw/openclaw.json
可通过 CLI、Control UI、直接编辑三种方式管理
Control UI 会根据 config schema 渲染表单，并保留 Raw JSON 编辑器
config.patch 使用 merge patch 语义：
- object 递归合并
- null 删除 key
- array 直接替换
config.apply / config.patch 都带 baseHash 并具备重启/应用语义
配置严格校验，不符合 schema 时 Gateway 会拒绝启动
skills 是明确独立的配置域，支持：
- skills.allowBundled
- skills.load.extraDirs
- skills.entries.<skillKey>.enabled/env/apiKey
- openclaw skills list / info / check

这几条非常重要，因为它们直接决定了我们不能瞎定义自己的配置协议。

2.2 我们当前产品约束

当前 openclaw-manager-native 的产品重心仍然是：

账号池
诊断
修复
监控

所以配置管理的第一版不能破坏现有信息架构。

我的判断是：

不新增顶级“配置中心”导航
profile 配置继续挂在现有账号池语义之下
skills 管理作为全局配置面，挂在设置 / OpenClaw 配置子页下

2.3 当前工程约束

当前本地代码已经具备：

profile 目录发现
openclaw.json / auth-profiles.json 定位
provider / model / auth mode 摘要解析
profile 的创建 / probe / login / activate
本地 daemon 的受控 PATCH 机制

但尚未具备：

OpenClaw 配置 schema 模型
配置 diff 预览
字段白名单 patch
配置备份与回滚事务
active 与 inactive profile 的统一写入抽象

因此，本稿重点解决的不是“UI 怎么画”，而是“接口语义怎么定义才能稳”。

3. 页面信息架构

3.1 顶层导航策略

不建议新增新的顶级 section。

建议继续保留现有主结构：

总览
账号池
诊断
监控
设置 / 部署

配置相关能力应优先挂在：

账号池 / Profiles
设置 / OpenClaw 配置 / Skills

原因：

profile 配置天然依附于 profile
skills 管理天然是全局 / 工作区级，不属于某个 profile
如果把两者强行放在一个槽位页面里，会把作用域做混

3.2 账号池页的信息架构升级

建议把当前账号池页拆成：

左侧：Profile 列表

保留现有 profile list，但在列表项上增加更轻量的配置状态摘要：

配置有效
配置异常
缺少配置
有未应用变更

右侧：Spotlight 面板

将右侧 spotlight 区从“单块详情”升级为三级结构：

当前判断
配置摘要
动作区

更具体地说，可以做成以下 tabs 或 segmented control：

概览
配置
认证
操作历史

其中第一版只要做：

概览
配置

即可。

3.3 全局 Skills 管理页

建议放在：

设置
- OpenClaw 配置
  - Skills

页面结构建议：

A. 顶部状态条

当前 skills 总数
已启用数
缺失依赖数
额外挂载目录数

B. Skills 列表

每个 skill 至少展示：

名称 / key
来源
路径
是否启用
是否可用
缺失依赖摘要

C. 动作区

启用
禁用
查看详情
新增本地 skill
增加 extraDirs
删除本地 skill / 删除 extraDirs 项

D. 高级区

skills 配置只读视图
原始 JSON
打开 skills 目录

3.4 Profile 配置页建议布局

A. 顶部判断卡

优先展示当前配置状态：

配置有效
配置缺失
配置校验失败
配置与运行实例不一致
当前改动尚未应用

需要展示的最短文案结构：

当前判断
为什么会这样
最安全的下一步

B. 配置摘要区

按“普通用户最关心”的顺序展示：

当前主模型
当前 provider
已配置 provider 列表
auth mode 摘要
当前配置路径
当前 auth store 路径
最近校验时间 / 最近修改时间

C. 可编辑字段区

第一版建议不要渲染完整 schema 表单，而是只做白名单字段卡片：

主模型
备用模型
provider 开关
provider 鉴权模式
网关远程/本地模式相关最少字段

每个字段块都应该同时显示：

当前值
推荐解释
修改影响

D. 高级区

折叠显示：

原始 JSON 只读视图
原始 auth-profiles.json 只读视图
配置 diff 预览
备份与回滚列表
打开原始文件

3.5 五种核心用户流程

流程 1：查看 active profile 配置

进入账号池
选中 active profile
打开 配置
看到当前判断、摘要、路径、可编辑字段

流程 2：修改 active profile 的主模型

进入 配置
修改主模型字段
先生成变更预览
校验通过后点保存
daemon 执行 patch / apply
页面刷新并显示结果

流程 3：检查 inactive profile 的配置是否有效

切到目标 profile
打开 配置
查看当前文件与校验结果
手动触发校验或重新 probe

流程 4：回滚错误配置

打开 配置
进入 高级
查看最近备份
选择一份回滚
完成校验与恢复
自动刷新摘要

流程 5：新增 / 删除本地 skill

进入 设置 -> OpenClaw 配置 -> Skills
查看当前 skills 列表与来源
选择：
- 导入本地 skill
- 增加 extraDirs
- 删除 managed/local/workspace skill
daemon 执行校验与刷新
页面更新 skills 状态

3.6 页面状态模型

配置页最少需要支持以下状态：

loading
ready
missing
invalid
dirty
applying
conflicted
rolledBack

对应语义：

loading
- 正在读取配置或 schema
ready
- 配置可读且可编辑
missing
- 配置文件不存在
invalid
- 当前配置不通过校验
dirty
- 用户本地改动尚未保存
applying
- 正在写入 / 应用 / 重新 probe
conflicted
- baseHash 或 revision 失效，有并发修改
rolledBack
- 最近一次已回滚成功

4. 交互原则

4.1 只在必要时暴露原始 JSON

第一版应坚持：

默认展示结构化字段
原始 JSON 仅作为高级区的兜底入口

不要让普通用户一打开就面对整份配置文本。

4.2 所有写入都先预览差异

任何可写字段都不应直接保存。

统一流程：

生成 patch
展示 diff
进行 validate
用户确认
写入

4.3 写入结果必须说明“是否热生效”

官方文档已经说明：

某些字段热应用
某些字段需要 restart

因此保存结果必须明确告诉用户：

已立即生效
将在 Gateway 重启后生效
这次变更会触发服务重载

这不是附加信息，而是主信息。

5. Daemon 配置域模型草案

建议新增一个独立的配置子域，而不是把它塞进现有 ManagerSummary。

5.1 领域对象

`ProfileConfigSummary`

用于页面首屏读取：

profileName
scope
isActive
configPath
authStorePath
exists
valid
dirty
source
primaryModelId
fallbackModelIds
configuredProviderIds
authModes
lastValidatedAt
lastModifiedAt
requiresRestart
canEdit

`ProfileConfigDocument`

用于高级视图与编辑器：

summary
rawConfig
rawAuthStore
hash
schemaVersion
schemaDigest

`ProfileConfigDraft`

用于 UI 本地编辑态：

baseHash
editableFields
patch
warnings

`ProfileConfigPreview`

baseHash
nextHash
diffItems
validation
restartImpact

`ProfileConfigApplyResult`

ok
applied
appliedAt
nextHash
validation
restartTriggered
hotApplied
summary

`ProfileConfigBackup`

backupId
profileName
createdAt
source
configPath
authStorePath
note

`SkillSnapshot`

key
name
source
path
enabled
eligible
missingRequirements
hasLocalOverride

`SkillsConfigSnapshot`

allowBundled
extraDirs
watch
watchDebounceMs
install.preferBrew
install.nodeManager
entries

5.2 两种后端来源

这是整个设计的关键。

建议在 daemon 内显式区分两类配置后端：

A. `gateway-rpc`

适用于：

active profile
当前 Gateway 正在使用的配置

优先使用官方能力：

config.get
config.patch
config.apply
config.schema

优点：

语义与官方一致
自带 hash / 校验 / 应用机制
更适合“运行中配置”

B. `filesystem`

适用于：

inactive profile
尚未运行的 profile 槽位

由我们自己的 daemon 做：

读取 profile 配置文件
生成字段级 patch
写前备份
本地校验
写后重新 probe

优点：

可管理 dormant slot
不依赖当前 Gateway 必须正在以该 profile 运行

因此建议在所有配置读取结果里返回一个字段：

source: "gateway-rpc" | "filesystem"

这样前端可以明确知道自己正处于哪种语义下。

skills 这条线则建议单独定义来源：

bundled
managed
workspace
extra-dir

6. Daemon API 草案

6.1 读取类接口

`GET /api/openclaw/profiles/{profileName}/config/summary`

作用：

返回该 profile 的轻量配置摘要

适合：

列表页
spotlight 顶部判断

`GET /api/openclaw/profiles/{profileName}/config/document`

作用：

返回完整配置文档对象

包含：

summary
raw config
raw auth store
hash
schema 摘要

`GET /api/openclaw/profiles/{profileName}/config/schema`

作用：

返回该 profile 当前可用的 schema 信息

active profile：

优先透传官方 config.schema

inactive profile：

返回我们支持的字段白名单 schema

`GET /api/openclaw/profiles/{profileName}/config/backups`

作用：

返回备份列表

`GET /api/openclaw/skills`

作用：

返回当前 skills 列表、来源、路径、启用态、可用态、缺失依赖

`GET /api/openclaw/skills/config`

作用：

返回 skills 配置快照

6.2 校验与预览接口

`POST /api/openclaw/profiles/{profileName}/config/validate`

请求：

可选 raw 或 patch

作用：

对当前配置或草稿进行校验

valid
errors
warnings
restartImpact

`POST /api/openclaw/profiles/{profileName}/config/preview`

请求：

baseHash
patch

作用：

生成变更预览

diffItems
validation
restartImpact
nextHash

`POST /api/openclaw/skills/check`

作用：

触发一次 skills eligibility 检查

最新 skills 列表与检查结果

6.3 写入接口

`PATCH /api/openclaw/profiles/{profileName}/config`

请求：

baseHash
patch
note

语义：

只接受字段白名单 patch
不直接 apply
返回 preview 或 staged result

建议第一版不要让这个接口直接完成全部写入。

`POST /api/openclaw/profiles/{profileName}/config/apply`

请求：

baseHash
patch
note

语义：

active profile：
- 走官方 config.patch 或 config.apply
inactive profile：
- 走本地文件 patch + 重新校验

ProfileConfigApplyResult

`POST /api/openclaw/profiles/{profileName}/config/restore`

请求：

backupId

语义：

回滚指定备份

ProfileConfigApplyResult

`PATCH /api/openclaw/skills/config`

请求：

baseHash
patch

语义：

只修改 skills 相关配置，如 allowBundled、load、install、entries

`POST /api/openclaw/skills/{skillKey}/enable`

作用：

启用指定 skill

`POST /api/openclaw/skills/{skillKey}/disable`

作用：

禁用指定 skill

`POST /api/openclaw/skills/import`

作用：

从本地目录导入 skill 或创建 managed/local skill override

`DELETE /api/openclaw/skills/{skillKey}`

作用：

删除 managed/local/workspace skill

说明：

bundled skill 不允许删除，只允许禁用
extraDirs 的删除建议单独做成配置 patch，不直接删除外部目录

6.4 原始文件接口

`GET /api/openclaw/profiles/{profileName}/auth-store`

作用：

返回 auth-profiles.json 摘要与原始内容

`PATCH /api/openclaw/profiles/{profileName}/auth-store`

作用：

受控修改 auth store

说明：

第一版建议只读，不建议立即放开写入。

7. 并发控制与回滚策略

7.1 并发控制

建议所有可写接口都强制要求：

baseHash

规则：

hash 不一致直接拒绝
返回 409 Conflict
前端提示“配置已被其他操作修改，请先刷新”

理由：

官方 Control UI 已经在配置写入里使用 base-hash guard
我们应该沿用同样的防覆盖思路

7.2 写前备份

无论 active / inactive，都建议写前自动备份：

openclaw.json
auth-profiles.json

备份目录建议放在 manager 自己的 backup 根目录下，按：

<manager-backup-root>/config/<profileName>/<timestamp>/

7.3 回滚策略

回滚必须是可见动作，不应隐式吞掉。

建议策略：

写入前备份
写入失败且文件已变更时自动回滚
回滚成功后返回明确结果
前端展示“已回滚到最近一次有效配置”

8. 第一版字段白名单建议

我建议第一版只做这些字段：

必做

agents.defaults.model.primary
agents.defaults.model.fallbacks
agents.defaults.models
auth.profiles
skills.entries.<skillKey>.enabled
skills.load.extraDirs

可选

gateway.mode
gateway.remote.url
gateway.remote.token
env.shellEnv.enabled

暂不做

渠道类配置全量编辑
plugin 配置
cron / hooks 全量配置
skills 全量 schema 动态表单
browser / exec approvals 全量配置

原因：

范围会立刻失控
与“本地 OpenClaw 管理入口”的第一阶段核心价值不完全一致

9. 分阶段研发建议

M1：配置只读能力

交付：

配置摘要读取
配置校验
原始文件查看
路径展示
skills 列表
skills 来源 / 依赖状态

验收：

用户能在 app 中看见 active / inactive profile 的配置状态

M2：active profile 安全编辑

交付：

白名单字段表单
diff 预览
validate
apply
skills 启用 / 禁用
extraDirs 新增 / 删除

验收：

用户可以稳定修改 active profile 的主模型与 provider 配置

M3：inactive profile 受控编辑

交付：

文件 patch
写前备份
失败回滚
重新 probe

验收：

用户可以修改 dormant slot，而不会把整个 profile 写坏

M4：skills 本地增删

交付：

新增本地 skill
删除 managed/local/workspace skill
删除 extraDirs 项

验收：

用户可在 app 中完成 skills 列表、启停、新增、删除闭环

10. 建议暂不做的事情

以下方向我建议暂缓：

通用 JSON 树编辑器作为主入口
所有字段 schema 动态表单一次性上线
把 auth store 和 config 混成一个统一表单
以“设置中心”替代现有账号池语义

这些做法理论上都能做，但第一版很容易把产品从“降低使用门槛”做成“可视化暴露复杂度”。

11. 最终建议

如果现在要立项，我建议按下面的句子来定义目标：

让用户在 OpenClaw Manager Native 中，以 profile 为中心查看、校验并安全修改本机 OpenClaw 配置；先覆盖 active profile 的高价值字段，再逐步扩展到 inactive profile 的受控编辑。

建议升级为：

让用户在 OpenClaw Manager Native 中，以 profile 为中心管理槽位级 OpenClaw 配置，并以全局视角管理 skills 列表、启停、新增与删除；先覆盖 active profile 的高价值字段和 skills 的基础生命周期，再逐步扩展到 inactive profile 的受控编辑。

这一定义的好处是：

边界清晰
能快速交付
与官方能力一致
与我们现有代码结构兼容

12. 参考资料

官方资料

OpenClaw Configuration
https://docs.openclaw.ai/gateway/configuration
OpenClaw CLI: openclaw config
https://docs.openclaw.ai/cli/config
OpenClaw Control UI
https://docs.openclaw.ai/web/control-ui
OpenClaw FAQ
https://docs.openclaw.ai/help/faq
OpenClaw GitHub 仓库
https://github.com/openclaw/openclaw

本地实现参考

openclaw-manager-native/cmd/openclaw-manager-daemon/main.go
openclaw-manager-native/Sources/OpenClawManagerNative/main.swift
openclaw-manager-native/Sources/OpenClawManagerNative/NativeStore.swift
openclaw-manager-native/Sources/OpenClawManagerNative/NativeShellView.swift