自定义模型配置

自定义模型配置让你为自己的主机更换执行模型：先配置一个第三方模型端点（API 地址 + KEY + 模型名），连通测试通过后应用到主机。一份配置按接口类型只作用于一个引擎（claude-code 与 codex 的协议栈互不相通，硬套必然失败）：anthropic 类型接管 claude-code，openai 类型接管 codex；另一个引擎会撤销接管、退回它自己的配置。「还原默认」把两个引擎都恢复原状。该功能仅作用于 claude-code 与 codex；ACP 引擎暂不支持在线切换模型（各 ACP 智能体的模型配置方式不同，尚未统一梳理）。

鉴权：raa- API Key 或 Web JWT 均可。
只能操作当前账号自己的配置与主机，他人资源返回 404。
配置的唯一键是自生成的配置 id（mc- 前缀），配置名称仅作展示、可重名；编辑时所有字段都可改。
接口类型（openai / anthropic）既决定连通测试的发包格式，也决定该配置作用于哪个引擎：anthropic 打 /v1/messages → 仅对 claude-code 引擎生效；openai 打 /chat/completions → 仅对 codex 引擎生效。另一个用不了该协议的引擎会退回默认配置，不会留下必然失败的覆盖。控制台选择接口类型时有对应提示。
KEY 加密存储，接口只返回脱敏摘要（apiKeyHint），明文不回显。
有任务运行中的主机不可更换模型配置（返回 409，更换会使任务直接失败）。
该功能目前仅 Web 控制台与 API 可用，raagent CLI 不暴露用户命令。

接口

方法与路径	说明
`GET /api/v1/model-configs`	列出自定义模型配置（含被主机使用数）。
`POST /api/v1/model-configs`	新建配置。
`GET /api/v1/model-configs/{id}`	配置详情。
`PATCH /api/v1/model-configs/{id}`	编辑配置（全字段可改；KEY 留空则沿用）。
`DELETE /api/v1/model-configs/{id}`	删除配置（有关联主机时返回 `409`）。
`POST /api/v1/model-configs/test`	连通测试（真实发一条简单消息，支持未保存的草稿）。
`POST /api/v1/hosts/{id}/model-config`	更换 / 还原主机模型配置。

列出配置

http

GET /api/v1/model-configs HTTP/1.1
Host: agent.raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY

json

{
  "code": "0",
  "message": "ok",
  "data": {
    "items": [
      {
        "id": "mc-1789015700-a1b2c3",
        "name": "glm",
        "apiType": "anthropic",
        "baseUrl": "https://open.bigmodel.cn/api/anthropic",
        "apiKeyHint": "9fba······5397",
        "authMode": "bearer",
        "modelName": "glm-5.3",
        "createdAt": "2026-09-10T04:00:00.000Z",
        "updatedAt": "2026-09-10T04:00:00.000Z",
        "hostCount": 1
      }
    ],
    "total": 1
  }
}

字段说明：

字段	说明
`apiType`	`openai` / `anthropic`，决定连通测试发包格式，并决定该配置作用于哪个引擎（`openai` → codex，`anthropic` → claude-code）
`apiKeyHint`	KEY 脱敏摘要（前 4 + 后 4），明文不可取回
`authMode`	anthropic 端点认证头（连通测试探测）：`bearer` → `ANTHROPIC_AUTH_TOKEN`；`x-api-key` → `ANTHROPIC_API_KEY`
`hostCount`	当前绑定该配置的主机数

新建配置

http

POST /api/v1/model-configs HTTP/1.1
Host: agent.raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY
Content-Type: application/json

{
  "name": "glm",
  "apiType": "anthropic",
  "baseUrl": "https://open.bigmodel.cn/api/anthropic",
  "apiKey": "你的KEY",
  "authMode": "bearer",
  "modelName": "glm-5.3"
}

返回 201 与创建后的配置视图。authMode 可省略（默认 bearer，连通测试会自动探测并回写）。模型名称只允许单个模型名。

编辑配置

http

PATCH /api/v1/model-configs/mc-1789015700-a1b2c3 HTTP/1.1
Host: agent.raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY
Content-Type: application/json

{
  "name": "glm-flash",
  "modelName": "glm-5.3-flash"
}

所有字段均可选，未传的保留原值；apiKey 不传则沿用已保存的 KEY。

编辑会触发关联主机同步：绑定该配置的主机会收到最新配置；空闲主机立即下发，有任务运行中的主机自动排队，任务归零后取最新版本下发（多次编辑只保留最新一次的结果）。

删除配置

http

DELETE /api/v1/model-configs/mc-1789015700-a1b2c3 HTTP/1.1
Host: agent.raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY

仍有主机绑定该配置时返回 409，需先在主机上更换为其他配置或还原默认。

连通测试

真实向模型端点发一条简单消息并检查回复内容（不是可达性 ping），超时 2 分钟。支持两种用法：

测试已保存的配置（只传 id，用存量 KEY）：

http

POST /api/v1/model-configs/test HTTP/1.1
Host: agent.raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY
Content-Type: application/json

{ "id": "mc-1789015700-a1b2c3" }

测试草稿（未保存前先验证，字段与 id 可组合，显式字段覆盖存量值）：

json

{
  "apiType": "anthropic",
  "baseUrl": "https://api.deepseek.com/anthropic",
  "apiKey": "你的KEY",
  "modelName": "deepseek-v4-pro"
}

响应：

json

{
  "code": "0",
  "message": "ok",
  "data": {
    "ok": true,
    "authMode": "bearer",
    "replyPreview": "OK",
    "latencyMs": 1830
  }
}

字段	说明
`ok`	测试是否通过（收到模型真实回复）
`authMode`	anthropic 端点探测到的认证头（先 Bearer，401/403 再 `x-api-key`），测试通过时返回
`replyPreview`	模型回复摘录（最多 120 字符）
`latencyMs`	耗时
`error`	失败原因（HTTP 状态 + 端点返回的可读错误信息）

测试通过且探测到与存量不同的 authMode 时，服务端会自动回写该配置。

更换 / 还原主机模型配置

http

POST /api/v1/hosts/h-1788767193919/model-config HTTP/1.1
Host: agent.raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY
Content-Type: application/json

{ "configId": "mc-1789015700-a1b2c3" }

configId 传 null 表示还原默认配置：撤销两个引擎的接管（claude-code 按备份写回、codex 删除覆盖配置）。

主机侧行为（由 raagent CLI 完成，需较新版本）：

按接口类型只作用于一个引擎，另一个引擎撤销接管退回默认：
- anthropic → 接管 claude-code：精准替换 ~/.claude/settings.json 中 env 的 Anthropic 相关键（ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN / ANTHROPIC_API_KEY 二选一、ANTHROPIC_MODEL 与三个 ANTHROPIC_DEFAULT_*_MODEL、CLAUDE_CODE_MAX_CONTEXT_TOKENS，均写入配置的单一模型名），其他键一律不动；同时清除 codex 的覆盖配置。
- openai → 接管 codex：写 ~/.raagent/codex-model.json（0600，KEY 只经 OPENAI_API_KEY env 注入、不进命令行，也不改用户自己的 ~/.codex/config.toml）；同时撤销 claude-code 的接管。
备份仅在 claude-code 侧默认 → 自定义时触发；自定义 → 自定义不覆盖备份；撤销接管 = 按备份精准写回并删除备份。若某引擎从未被接管过，撤销时不读不写该引擎的用户配置（no-op）——所以「从未用过本功能」的用户自己的 claude 配置不会被动。
CLI 对有任务运行中的请求会兜底拒绝。

错误情况（均返回 409）：

场景	message
主机有任务运行中	有任务运行过程中更换模型配置，会直接使任务失败，请停止任务后再更换
主机离线	主机离线，无法更换模型配置，请先启动主机上的 raagent
CLI 版本过旧（未响应）	主机 CLI 未响应模型配置指令，请升级 CLI 到最新版本后重试

成功后 GET /api/v1/hosts 列表中该主机的 modelConfig 字段为当前绑定视图：

json

{
  "modelConfig": {
    "configId": "mc-1789015700-a1b2c3",
    "name": "glm",
    "status": "idle",
    "lastError": null
  }
}

modelConfig 为 null 表示默认；status 含义：idle 已生效、pending 待同步（主机在跑任务已排队）、syncing 下发中、failed 最近一次下发失败（lastError 为原因，任务归零或主机上线后自动重试）。

自定义模型配置 ​

接口 ​

列出配置 ​

新建配置 ​

编辑配置 ​

删除配置 ​

连通测试 ​

更换 / 还原主机模型配置 ​

自定义模型配置

接口

列出配置

新建配置

编辑配置

删除配置

连通测试

更换 / 还原主机模型配置