OpenClaw 模型管理器：告别手动编辑模型路由 JSON

我曾经在 JSON 文件中拼错了一个模型 ID，结果使用该配置文件的代理程序就悄无声息地停止响应了。既没有报错，也没有崩溃。它就这样静静地试图与一个根本不存在的模型进行通信，而我当时正在寻找一个更有趣的 Bug。这款应用就是我的“绝不再犯”。

适用人群

如果您在运行 OpenClaw 时使用了多个代理程序，并且混合使用了本地模型与付费模型；同时您每月都会多次调整各个模型的使用分配情况，那么本工具对您会非常有用。但如果您只设定好一个模型后就再也不做改动，那么手动编辑即可，无需使用此工具。

该工具还能防范两种较为严重的故障：一是 openclaw.json 文件内容不完整或格式错误时可能导致整个网关陷入死循环；原子写入机制与备份功能则有效避免了这种情况。二是手动编写的 systemd 配置可能会将 API 密钥泄露到 ps 输出结果中；而本工具从设计层面就杜绝了这种风险。

2026-08 版本的变更内容：

• “添加 API 模型”对话框允许通过一次编辑操作即可添加云服务商信息。该操作会同时写入服务商配置块与目录条目，而 API 密钥则被保存至网关的环境变量文件中，而非配置文件中。
• 现在可以直接在目录列表中编辑各模型的上下文窗口设置。
• 目录列表会显示各云服务商实际为对应模型提供的参数信息。
• 我在第二台电脑上运行的推理服务器现已改用 llama.cpp 引擎，取代了原先的 LM Studio；不过两者使用的端口相同。由于应用程序是从配置文件中读取服务商的基础 URL 而非硬编码这些值，因此无需做任何修改。

最终效果展示

先来看截图。这些截图来自一个在临时 HOME 目录下运行的沙盒环境，使用的是虚拟配置。这是真实的应用程序，但数据都是假的，也没有使用我的任何密钥。

这个主界面解决了以往需要通过搜索JSON文件才能回答的问题：哪些模型正在哪里运行？它们的使用成本是多少？ 无论是每个代理的配置、全局默认设置、子代理的覆盖规则，还是定时任务，甚至是其他邮件代理所使用的模型信息，都在此显示。每条记录还配有颜色标识：本地（本机）、远程（另一台电脑）或云端（会在账单上体现）。对应用程序而言，本地与远程环境本质上都是兼容OpenAI协议的服务器；它只关心这些服务器在 /v1/models 接口下返回了什么信息。拍摄这些截图时，本机运行的是LM Studio；不过现在已没有模型在运行，另一台电脑上则运行着基于llama.cpp的服务器。

为什么需要这个工具

OpenClaw是我在家里使用的多智能体系统：包含多个AI代理，每个代理都对应一个模型——有些是本地且免费的模型，有些则需通过云端付费使用。所有的路由配置都集中在一个文件中，即 ~/.openclaw/openclaw.json：里面包含了模型目录、各个代理的主用/备用模型分配情况、提供商配置信息以及网关自身的认证令牌。不过手动编辑这个文件总是会引发问题。

首先，任何编辑都可能导致系统出错；最糟糕的情况就是保存了格式错误的配置——只要有一个小错误，整个网关就会陷入死循环（关于这种情况的应对方法，我在 网关出故障时我该怎么办 一文中有详细说明）。

其次，调整路由设置的过程极其繁琐且复杂。如果你的网关将编程任务转交给 Claude Code CLI，那么网关的 systemd 服务单元中所设置的 ANTHROPIC_* 环境变量便决定了这些请求会被发送到哪里以及由谁来计费。要在免费的本地模型、价格低廉的 DeepSeek 以及真正的 Anthropic 模型之间切换，就必须每次手动修改 systemd 配置；这种事往往只有我会在深夜犯迷糊。而该应用的“编程助手”面板则能自动完成这一切。自 2026 年 9 月起我便不再通过自己的网关来路由 Claude Code 请求了，因此该配置模块也就再没在我的电脑上安装过；不过它仍随软件包一同提供，且功能如下文所述。

保存路径说明

我需要重点了解的是点击“保存”后发生的流程。具体步骤如下：

其中有两个关键步骤尤为重要。首先，模型选择下拉菜单仅显示配置文件中已知的模型ID；若出现指向不存在模型的默认设置，程序也会予以拒绝（见下文示例）。这样一来，前文提到的“无效模型”问题便被程序自动拦截，无需我手动检查。其次，之所以采用原子写入机制，是因为 openclaw.json 文件中保存着网关的认证令牌，其权限必须保持为 chmod 600。具体流程为：临时文件先继承原文件的权限设置，随后写入内容并执行 fsync 操作，最后才重命名为原文件名。即便保存过程中发生崩溃，原文件也绝不会受损。

若保存失败，只需一次重命名即可恢复原状。执行轮换备份后，磁盘上会保留六个版本的文件：最新版存于 .bak，其余五个旧版分别命名为 .bak.1 至 .bak.5。每次保存操作都会使最旧的备份文件被覆盖。

以下为程序如何拦截无效模型设置的实例：下拉菜单中仅列出配置文件中已知的模型ID；而所谓的“默认模型”选项往往指向某个提供商已不再支持的模型。此时程序会保留代理当前使用的模型设置，并提示相应错误信息而非保存无效配置（此处的代理与模型名称仅为示例）。

"[Default]" primary for worker points at vllm/old-model, which doesn't exist on its provider — keeping the agent's current model. Fix the Model Defaults slot.

这是一次真实保存操作产生的完整差异记录：该操作将示例配置文件中的 worker 代理设置为 DeepSeek Flash。我在临时目录下运行了程序自身的保存功能，并对比了原始示例文件与保存后的版本。

--- openclaw.json.bak
+++ openclaw.json
@@ -36,7 +36,7 @@
         "id": "worker",
         "name": "Worker",
-        "model": "vllm/example-local-model"
+        "model": "deepseek/deepseek-v4-flash"
       }

需注意一点：首次保存时会以两个空格作为缩进重写整个文件，因此原本写在一行上的数组内容（如 "input": ["text"]）会被拆分成多行显示。不过实际数据并未改变；此后每次保存产生的差异都会保持较小规模。

Coding Helper 插件机制

这是一个可选功能，适用于网关需要启动 Claude Code CLI 的场景。其重定向流程是独立的，因为该流程根本不会触及 openclaw.json 文件。应用程序会生成一个 systemd 插件，在网关启动任何 Claude Code 进程之前覆盖其环境变量。

共有四种模式，均通过同一个下拉菜单进行选择：LM Studio（免费且本地运行）、通过 Anthropic 兼容端点访问的 DeepSeek（价格低廉）、Anthropic Cloud（默认选项：无需任何插件，环境变量也不会被覆盖），以及 关闭 模式（下拉菜单显示为“关闭”）。选择“关闭”后，CLI 会被指向 http://127.0.0.1:9/blocked，这样所有请求都会迅速失败而不会陷入等待状态。此外还有一个一键实时测试功能：它会向 LM Studio 或 DeepSeek 发送一个符合 Anthropic 格式的 ping 请求，并报告最终响应的是哪个模型。这种实测方式提供的信息远比任何配置界面要直观可靠，因为请求确实是真实发送的。

确保 API 密钥不会出现在 unit 文件中

DeepSeek 模式需要使用 API 密钥，但将密钥写入 systemd 的 unit 文件实在不是个好主意：任何写入该文件的内容都会以纯文本形式存储在磁盘上，并且也会出现在 systemctl show 的输出结果中。因此，对应的 drop-in 文件中并不会包含实际的密钥，而是写入如下内容：

ExecStart=/usr/bin/bash -c 'export ANTHROPIC_API_KEY="$$DEEPSEEK_API_KEY"; exec <gateway cmd>'

这里的诀窍就是使用 $$。在 unit 文件中，$$ 的作用是对字面量 $ 进行转义。如果不使用它，systemd 在构建命令行时会自行展开该变量，导致真正的密钥出现在进程的命令行参数中，进而被 ps 读取到。而使用了双美元符号后，Bash 接收到的是字面量 $DEEPSEEK_API_KEY，并在运行时从网关的 EnvironmentFile（即 OpenClaw 主目录下的 gateway.systemd.env 文件，需设置 chmod 600）中读取实际值。这样一来，该密钥便不会出现在 unit 文件、systemctl show 输出或任何进程列表中；它仅存在于该进程的 Bash 环境变量里。压缩包中的 examples/ 文件夹以 CHANGE_ME 占位符的形式演示了这一用法。

2026年8月发布的版本中，“添加 API 模型”对话框则从另一个角度贯彻了同样的规则。手动添加云服务商时，需要同时修改 openclaw.json 中的两处内容，且二者必须保持一致：一个是 models.providers.<id> 连接配置块，另一个则是 agents.defaults.models 目录条目。如果遗漏其中任何一部分，该模型便无法被选中，且不会出现任何错误提示说明原因。

该对话框会一次性完成这两项修改。用户输入的密钥值会被写入前述的 gateway.systemd.env 文件中。系统会先对该文件进行备份，保持其 0600 权限设置，同时合并其中重复定义的变量内容，从而避免旧版本中的冗余定义产生干扰。openclaw.json 中则仅会写入字符串 "${YOUR_KEY_VAR}"。在保存前，用户可点击“测试”按钮向相应端点发送一次实际请求；这是验证基础 URL、协议、密钥及模型 ID 是否匹配的唯一途径——否则可能数周后才发现所添加的服务商其实早已不可用。

设置方法

具体内容可参考压缩包内附带的 README 文件：

# 1. Install GTK4 + libadwaita + PyGObject from your distro's packages
#    (one dnf/apt line; README-SETUP.md has the exact package names)

# 2. Install the app and its launcher
install -Dm755 openclaw-model-manager ~/.local/bin/openclaw-model-manager
# .desktop file goes to ~/.local/share/applications/

# 3. If you don't already have an OpenClaw config:
cp examples/openclaw.json.example ~/.openclaw/openclaw.json
chmod 600 ~/.openclaw/openclaw.json
# then replace every CHANGE_ME placeholder inside it

# 4. Optional: API keys go in two files in the same directory as
#    openclaw.json: .env and gateway.systemd.env (both chmod 600;
#    examples/ has a template for each)

除了 PyGObject 外无需使用 pip 安装任何包；其余所有功能均可通过 Python 3.11+ 的标准库实现，其中也包含了 tomllib。整个程序仅由一个可执行脚本构成（共 4,181 行代码，大小约 190 KB），此外还有一个 .desktop 启动器、一份 README 文档、MIT 许可证以及四个示例配置文件。整个压缩包的大小为 56 KB。

注意事项

• “云模式”仅意味着不会使用替换配置。 任何原有设置都不会被覆盖，因此设备上原本的配置仍会正常运行。当您选择的模式没有可用的密钥时，应用会发出警告，但建议您还是自行检查一下。
• 替换配置机制会刻意“隐藏”真实的 Anthropic 密钥。 在本地模式下，系统会为网关生成的所有进程设置 ANTHROPIC_API_KEY=lm-studio。在我的机器上，这一操作悄悄地将我常用的 claude CLI 命令指向了 LM Studio。虽然 Claude Code 看似仍能正常运行，但实际上返回的结果均来自本地模型。如果 Claude 的输出变得异常，请运行 systemctl --user cat openclaw-gateway.service 并查看其中是否有相关替换配置，再判定是否为模型本身的问题。
• 在执行 openclaw update 后，需重新选择一次 DeepSeek 模式 以便应用能重新封装新的命令。该应用会从服务单元配置文件中读取原始的 ExecStart 参数，并识别出自身的封装逻辑（以 index.js 的存在以及缺少 $$DEEPSEEK_API_KEY 作为判断依据），因此不会重复封装命令。不过如果某个命令此前未被应用识别过，它也不会自动修正。
• 对于本地模型而言，reasoning: true 是安全的默认设置。 若模型在 reasoning: false 的配置下仍输出 reasoning_content，网关会误以为该模型已停滞：经过约 390 秒无响应后便会强制终止进程。对于非推理型模型而言，保持此设置并无害处，因此添加模型对话框中也默认开启此选项。这一设置曾让我耗费不少时间进行排错。
• 只要 plugins.allow 不为空，它即构成严格的允许列表。 某个插件即便设置了 enabled: true，也只有其 ID 同时存在于 allow 列表中才会生效。该应用能正确读取此配置，且刻意不会写入任何 plugins.* 相关设置；因此若某个插件出现异常行为，该应用也无法指出具体原因。本地 AI 代理栈的相关说明中也提到了类似的陷阱。
• openclaw.json 文件由网关自行修改（例如身份同步、openclaw update 操作等）。该应用会记录文件的最后修改时间，在覆盖外部编辑内容前发出警告；同时保存前的备份机制也能确保原始内容得以保留。
• 服务方宣称的上下文窗口大小仅为宣传数值而已。 某些服务器会声称某模型支持高达 50 万个 Token 的上下文长度，但实际上其底层引擎仅能处理其中一小部分；而网关也会完全采信这一宣传值，导致过长的提示信息引发错误——这种现象常被误认为是模型本身的缺陷。正因如此，配置界面才允许您手动调整 contextWindow 的实际数值。
• 模型 ID 的格式为 provider/raw-id。 不带斜杠的简单 ID 则会通过本地推理端点进行解析。有些服务器使用的原始 ID 更为复杂（例如 publisher/repo/file-stem），因此请直接输入服务提供方给出的完整 ID，切勿自行简化。这仅是一种命名规范而非错误，了解这一点能避免您徒劳地去寻找根本不存在的“提供商”字段。

相关链接：此应用用于编辑配置的 本地 AI 代理栈、将 DeepSeek 作为所有请求的后端服务，以及 网关出现故障时我的处理办法。

下载

• Download OpenClaw Model Manager source (zip) 56 KB

仅限个人使用免费。如果它替你省下了一下午的时间，欢迎点旁边的咖啡按钮支持一下。