openclaw-model-config-helper

OpenClaw Model Config Helper

OpenClaw 第三方 API 配置插件

自动探测 API 兼容性，安全合并配置，无需手动编辑 JSON。

 

---

为什么需要这个插件？

配置第三方 API 中继时经常遇到这些问题：

• 不知道用哪个 API 格式 — anthropic-messages？openai-completions？还是 openai-responses？
• 手动编辑 JSON 容易出错 — 一个逗号错位就要重启排查
• 配置写错位置不生效 — 有时需要同时写 openclaw.json 和 agents/main/agent/models.json
• 改坏了难以恢复 — 没有备份，只能手动回滚

OpenClaw Model Config Helper 提供 Web UI 和 CLI 两种方式，自动探测 API 格式，安全合并配置，自动备份，支持一键回滚。

---

快速开始

安装

openclaw plugins install openclaw-model-config-helper
openclaw gateway restart

Web UI 访问

http://127.0.0.1:18789/plugins/openclaw-model-config-helper

---

功能特性

自动探测 API 格式

不需要猜测或查文档，插件会自动尝试三种格式：

• anthropic-messages → /v1/messages
• openai-completions → /v1/chat/completions
• openai-responses → /v1/responses

发送最小测试请求（"hi"），返回 200 且结构匹配即判定成功。

安全配置合并

• 自动备份 — 写入前创建 .bak.<timestamp> 备份
• 保护主模型 — 绝不修改 agents.defaults.model.primary
• 双文件写入 — 默认同时更新 openclaw.json 和 agents/main/agent/models.json
• 历史记录 — 所有变更记录到 merge-history.jsonl

Web UI 界面

• 填写 Base URL、API Key、Model ID
• 自动探测并生成配置
• 预览合并结果（dry-run）
• 一键应用或回滚

---

工作原理

┌──────────────────────────────────────┐
│           浏览器 (Web UI)             │
│  ┌────────────┐  ┌───────────────┐   │
│  │  填写信息  │  │  测试 API     │   │
│  └─────┬──────┘  └───────┬───────┘   │
│        └──────┬──────────┘           │
│               ▼                      │
│          生成 provider JSON           │
└───────────────┬──────────────────────┘
                │ HTTP API
┌───────────────▼──────────────────────┐
│         OpenClaw Gateway              │
│  ┌────────────────────────────────┐  │
│  │  model-config-helper 插件      │  │
│  │  ├─ POST /api/test             │  │
│  │  ├─ POST /api/merge            │  │
│  │  ├─ GET  /api/history          │  │
│  │  └─ POST /api/revert           │  │
│  └────────────────────────────────┘  │
│               │                      │
│               ▼                      │
│   ~/.openclaw/openclaw.json  ◄───────┤
│   (备份 → .bak.20260312_120000)      │
└──────────────────────────────────────┘

---

CLI 使用

测试 API

openclaw-model-config-helper test <baseUrl> <apiKey> <modelId> [providerName]

合并配置

# 默认写入两个文件
openclaw-model-config-helper merge provider-test.json

# 预览不写入
openclaw-model-config-helper merge provider-test.json --dry-run

查看历史

openclaw-model-config-helper history --limit 20

回滚配置

openclaw-model-config-helper revert --last --yes

---

项目结构

openclaw-model-config-helper/
├── index.ts                # 插件入口
├── core.js                 # 核心逻辑（CLI 与 HTTP 共用）
├── cli.js                  # CLI 入口
├── public/                 # Web UI
│   ├── index.html
│   ├── style.css
│   └── app.js
├── openclaw.plugin.json
├── package.json
└── README.md

---

安全提示

• ⚠️ 生成的 provider-*.json 包含 API Key，不要提交到 Git
• ✅ 项目已配置 .gitignore 规则

---

License

MIT