1实现原理 · 为什么它能做到
统一入口是个纯 argparse 转发层：cli.py 用 SUBCOMMANDS 字典把 audit/compare/diff/copy/add-model/list/switch 映射到各子模块的 main()，`diff` 只是 `compare` 的别名，没有任何自身业务逻辑。
openclaw/scripts/cli.py
SUBCOMMANDS = { "audit": audit, "compare": compare, "diff": compare, "copy": copy_provider,
这里在做什么：把「六个子命令」拆成六个可独立运行的脚本，再用一层薄转发把多命令体验装回来——SKILL.md 也提醒每个子命令可绕过 cli.py 直接跑（python3 scripts/audit.py ...），便于 agent 只读场景下按需调用。
配置定位是「显式路径 → 昵称注册表 → 三个默认位置」三级回退，默认位置顺序硬编码在 DEFAULT_CONFIG_PATHS。
openclaw/scripts/openclaw_config.py
DEFAULT_CONFIG_PATHS = [ Path.home() / "workspace" / ".force" / "openclaw" / "openclaw.json", Path.home() / ".kimi_openclaw" / "openclaw.json", Path.home() / ".openclaw" / "openclaw.json", ]
这里在做什么：不假设单一安装位置，按「先私有工作区、再 Kimi 旧路径、再官方路径」优先取第一个存在的文件；全部不存在时抛 ConfigError 并把三个候选路径都打印出来提示用户。
多实例抽象靠 lobsters.json 昵称注册表：先用 Path 判断入参是不是真实文件，若不是再去注册表里查 nickname→path 映射。
openclaw/scripts/openclaw_config.py
registry = load_lobster_registry() if str(name_or_path) in registry: return Path(registry[str(name_or_path)])
这里在做什么：让 `--config 甲虾`、`--from 乙虾` 这种人类口语昵称直接可用；代价是注册表文件里的路径值被无校验地 Path() 采纳（见 security.injection_surface）。
所有写操作都自带备份，且备份有保留上限：写到 <配置目录>/config-backups/<stem>-<UTC 时间戳>.json，随后按 mtime 排序裁掉超出 20 份的旧备份。
openclaw/scripts/openclaw_config.py
ts = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S") backup_path = backup_dir / f"{p.stem}-{ts}{p.suffix}" shutil.copy2(p, backup_path)
这里在做什么：把「改坏了怎么回滚」变成默认能力；用 UTC 时间戳避免时区歧义，用 shutil.copy2 连文件元数据一起复制。同文件下方 `for old in existing[:-max_backups]: old.unlink()` 负责裁剪，是防目录无限膨胀的唯一机制。
改默认模型时保留原有结构：agents.defaults.model 本来是对象就只改 primary，本来是字符串就写字符串——不会把用户原来的写法强行规范化。
openclaw/scripts/openclaw_config.py
if isinstance(current, dict): defaults["model"] = {**current, "primary": ref} else: defaults["model"] = ref
这里在做什么：OpenClaw 配置里 model 允许两种形态，直接下标 model["primary"] 会在字符串形态下抛 TypeError/KeyError；这里做形态自适应，是 openclaw 与 openclaw-model-switch 在健壮性上的关键差异。
变更类子命令默认做「改前体检 + 出 error 就中止 + 改后复检」，`--no-audit` 才跳过；这就是它所谓 auto-audit 护栏。
openclaw/scripts/switch_model.py
if any(i["level"] == "error" for i in issues): print("Aborting due to audit errors. Use --no-audit to skip.", file=sys.stderr) return 2
这里在做什么：把 audit.py 当软性事前门禁——只要配置里有结构性 error（缺 baseUrl/api、默认模型指向不存在的 provider…）就拒绝写入，避免在已经坏掉的配置上再叠一次修改。
copy 是「合并」而非「覆盖」：只同步 baseUrl/api 和同名 model 定义，目标端独有的模型不会被删掉。
openclaw/scripts/copy_provider.py
for key in ("baseUrl", "api"):
这里在做什么：跨实例搬运 provider 时，目标配置里自有的额外模型/别名必须幸存，否则一次 copy 就会静默丢配置；merge_provider 的 docstring 明确写「does not remove target-only models」。
重启网关用三级降级：先 `openclaw gateway restart`，失败再 `systemctl --user restart`，再退到系统级 `systemctl restart`，三档全失败只打警告不抛异常。
openclaw/scripts/openclaw_config.py
commands = [ ["openclaw", "gateway", "restart"], ["systemctl", "--user", "restart", "openclaw-gateway"], ["systemctl", "restart", "openclaw-gateway"], ]
这里在做什么：适配「CLI 在 PATH / 用户级 systemd / 系统级 systemd」三种安装形态；subprocess.run 传的是 argv 列表（无 shell=True），所以配置内容无法注入命令，但第三个候选意味着可能触发系统级服务重启。
把领域踩坑固化成可执行断言：audit 里有一条 DeepSeek 反模式启发式——provider 名以 deepseek 开头就告警，指向正确路径 gateway provider + deepseek-v4-pro。
openclaw/scripts/audit.py
if pname.lower().startswith("deepseek"):
这里在做什么：SKILL.md「Critical pitfalls」把这条经验写成人话，audit.py 把它写成代码检查，references/deepseek_patch_sop.md 写成长文 SOP，三者形成「文档→检查器→操作手册」的闭环。
2核心能力
01配置体检 audit：providers/baseUrl/api、model id 重复、模型条目类型、默认模型与别名能否解析、plugins 的 allow/entries/installs 一致性
02语义 diff 两个实例：providers/models/default model/aliases/plugins 分节报差异，cost 字段默认跳过（--include-cost 才比）
03跨实例复制 provider 并合并（可 --model 只搬指定模型、--alias 连别名一起搬）
04add-model：从源配置或 JSON 文件引入模型定义，必要时连 provider 一起拷过来，并自动补别名
05list：人读列表 / --json 给 jq，--validate 顺带校验默认模型与别名可解析
06switch：唯一改 agents.defaults.model 的子命令（改前校验 provider/model 存在）
07dry-run 预览：copy/add-model/switch 三个写命令都能只打印不落盘
08多实例昵称寻址：lobsters.json 里的中文昵称可当 --config/--from/--to 使用
3外部依赖
| Kind | Dependency / Endpoint |
|---|---|
| cli | openclaw CLI（gateway restart） |
| cli | systemctl（用户级/系统级服务重启回退） |
| package | Python 3 标准库 only（json/os/shutil/subprocess/argparse/pathlib；无第三方依赖） |
| network | OpenClaw provider baseUrl（仅写在配置里被审计/搬运，skill 自身从不发请求） |
4管控建议与判定依据
建议配套管控措施
面向 Agent
分级或逐次授权，建议在沙箱运行
面向管理者
审批流程、可回滚、全程审计
判定依据（文件路径与关键语句摘要）
- scripts/: 执行本地脚本或命令: python3 scripts/cli.py <audit|diff|copy|add-model|list|switch>（或直接跑对应子脚本）
- 环境变量 / API Key: 读取厂商服务密钥: openclaw.json 内的 models.providers.*.apiKey：随整份配置被读入内存并回写（脚本从不显式提取该字段）；copy/
- 本地工作目录: 文件读写与工件输出: <配置目录>/config-backups/<stem>-<UTC时间戳>.json（每次写操作前备份）
审计说明： 风险提醒：蓝色，本地配置工具的受控写入档。理由：①确实会执行子进程（openclaw/systemctl 重启网关，第 3 档是系统级服务），②确实会原地覆写用户的 openclaw.json 并删除超出保留上限的旧备份，③会读入并跨文件搬运 models.providers.*.apiKey——但全程无任何网络外发、无 env/keychain 凭证读取、无第三方依赖，且写操作默认有自动 audit 门禁 + 备份前置于修改。扣分项是 --config 任意路径 + --no-audit 组合、apiKey 随 provider 块被复制到目标配置（SOP 自己也提醒这一点）、备份目录权限未收紧。
5第二遍独立确认
- [ok] SKILL.md 声明「Backups: every write operation copies the config to config-backups/<stem>-<utc-timestamp>.json」是否与代码一致 — 三条写路径 copy_provider.py / add_model.py / switch_model.py 都在 save_config 之前调用 backup_config(config_path)，且 openclaw_config.backup_config 用 datetime.now(timezone.utc) 生成时间戳、文件名格式恰为 f"{p.stem}-{ts}{p.suffix}"；SKILL.md 关于「keeps the 20 most recent backups」也对得上 max_backups: int = 20 默认值与 existing[:-max_backups] 裁剪。
- [ok] SKILL.md 声明「switch 是唯一改 agents.defaults.model 的子命令」 — grep set_default_model 的调用点只有 switch_model.py 一处；add_model.py 只写 agents.defaults.models（别名映射），copy_provider.py 只写 models.providers 与别名，compare/list/audit 纯只读，声明成立。
- [ok] SKILL.md「Restart: write subcommands support --restart to restart the OpenClaw gateway after saving」 — 三个写脚本都定义了 --restart 并调用 restart_gateway()；且未给 --restart 时会打印「NOTE: You must restart the OpenClaw gateway...」提示，行为与文档一致。副产物确认：restart_gateway 的第三档是系统级 systemctl（无 --user），文档未提及这一越权风险，已写进 verdict.risks。
- [ok] external_deps 里是否漏掉了网络调用（有没有隐藏的 endpoint probe 或遥测） — 反向扫描 scripts/ 全部 8 文件：无 import urllib/requests/socket/httpx，无 curl/wget 字符串，无任何 URL 常量。openclaw 与 openclaw-model-switch 的关键差异（后者文档要求 curl 探针）在此得到对照确认。network 依赖项仅保留「配置里存在 baseUrl 字段」这一事实，并显式标注 skill 自身不请求。
- [ok] 是否读 env 里的 API key / 密钥 — scripts/ 内 os.environ、getenv 零命中；openclaw_config.py 里 import os 的唯一用途是 os.path.getmtime 做备份排序。凭证面仅为「随配置整份读写的 apiKey 字段」与「copy/add-model 把 provider 块连同 apiKey 深拷贝到目标配置」，已在 security.credential_reads 如实登记而非留空。
- [ok] 「copy 不删目标独有模型」是否为真（找反例：有没有静默覆盖整个 provider 的分支） — 反例检查通过：当目标已有该 provider 时走 merge_provider（只按 id 增补/更新、且注释明确 does not remove target-only models），不整块替换；唯一整体替换发生在「目标根本没有该 provider」时（copy.deepcopy(source_provider)），此时不存在目标独有模型可丢。--alias 分支只做 target_aliases[ref] = deepcopy(detail) 的增补，也不删。
- [discrepancy] 备份保留逻辑会不会误删非备份文件 — 发现第一遍未记的边界：裁剪用 backup_dir.glob(f"{p.stem}-*{p.suffix}") 匹配，若用户在 config-backups/ 目录里放了同名模式的其它文件（例如手工备份 openclaw-手工.json，而 stem 恰为 openclaw），mtime 最旧的会被 unlink。属真实但低概率的删除面，已补进 verdict.risks。
- [ok] 功能声明 vs 实际能力夸大检查（SKILL.md / README 有没有说到做不到的事） — SKILL.md 的六子命令、昵称注册表、三级默认路径、备份与 20 份上限、dry-run、restart、自动 audit 全部可在代码中一一落到实处，未发现夸大。唯一「文档比代码多说一句」的是 references/deepseek_patch_sop.md 的示例命令 `add-model gateway-provider references/deepseek_model.json`（相对路径需从 skill 根执行），属示例语境问题而非能力夸大。
6结论
适合： 适合同时维护多只「龙虾」（多个 OpenClaw 实例/包装器）的用户：需要横向对比两份 openclaw.json 差在哪、把某个 provider（如 gateway-provider 的 DeepSeek）同步到另一台、给新实例批量加模型与别名、或排查「为什么甲虾能用乙虾不行」。也适合把 DeepSeek 补丁当作业来做的场景——有 SOP + 模型定义 JSON + audit 断言三件套兜底，且每一步都可 dry-run 预览。给 agent 用时最舒服的路径是「audit → diff → copy/add-model --dry-run → 正式执行 → audit」。
不适合： 不适合单实例、只改一次默认模型就走的场景——那种需求 openclaw-model-switch 更直接（一条命令、不需要理解 audit/diff/copy 的概念）。不适合没有本地文件系统权限、或配置存放在远端/只读挂载的环境（全部操作都是本地就地覆写）。也不适合需要「改完立刻证明模型真的能跑」的场景：openclaw 只管配置结构与可选重启，没有任何端点探针或端到端验证，那部分是 openclaw-model-switch 的 Step 2/Step 4 覆盖的；更不要用 --no-audit 跳过门禁去修一份已经坏掉的配置。
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload openclaw.tar.gz
sha256:
Option B · Copy Guide for Agentc792eb95fa4dde39…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit d5c4678cb5.