OpenClaw Backup Bot
204 lines
6.2 KiB
Markdown
204 lines
6.2 KiB
Markdown
---
|
||
name: "openclaw-trapi-config"
|
||
description: "配置传米 trapi Provider、模型、别名与图像模型；用于安装、增量更新、验证和排障，包括 MiniMax-M3 与 GPT-5.6。"
|
||
---
|
||
|
||
# trapi 配置
|
||
|
||
为 OpenClaw 配置传米科技 trapi Provider。trapi 允许不同模型使用不同 API 适配器；不要假设所有模型都使用同一种协议。
|
||
|
||
详细模型参数和别名见 [references/custom-provider-config.md](references/custom-provider-config.md)。配置前必须读取该文件。
|
||
|
||
## 固定信息
|
||
|
||
- Provider ID：`trapi`
|
||
- Base URL：`https://lapi.transiglobal.com`
|
||
- API Key 环境变量：`TRAPI_API_KEY`
|
||
- 默认适配器：`anthropic-messages`
|
||
- GPT 模型按目录使用 `openai-responses`
|
||
|
||
## 安全原则
|
||
|
||
1. 先读取并校验现有配置，再提出变更。
|
||
2. 只做增量写入；不得用不完整对象覆盖 Provider、模型数组、别名表或 imageModel。
|
||
3. 不在聊天、命令参数、日志或文档中回显 API Key。
|
||
4. 优先使用环境变量 SecretRef；不要把真实 Key 明文写入 `openclaw.json`。
|
||
5. 任何持久配置变更前，列出将新增、更新、保留和跳过的项目，并等待用户确认。
|
||
6. 不自动删除现有模型或别名。删除或替换必须由用户明确指定。
|
||
7. 不自动覆盖现有默认模型、imageModel 或 fallback 链。
|
||
8. 不使用 Agent 侧 `gateway config.patch` 写入 `models.providers` 等受保护路径。优先使用当前主机上的 OpenClaw CLI。
|
||
9. 不默认执行付费模型调用。实时验证前说明调用范围并征得确认。
|
||
|
||
## 工作流
|
||
|
||
### 1. 检查版本和 Schema
|
||
|
||
执行：
|
||
|
||
```bash
|
||
openclaw --version
|
||
openclaw config validate
|
||
openclaw config schema
|
||
```
|
||
|
||
要求当前版本支持：
|
||
|
||
- `openclaw config set ... --merge`
|
||
- `openclaw models aliases add`
|
||
- `openclaw models set-image`
|
||
- `openclaw models image-fallbacks`
|
||
|
||
如命令或 Schema 不支持这些字段，停止配置并建议使用 `openclaw update --yes` 升级。不要自行升级。
|
||
|
||
### 2. 检查现有状态
|
||
|
||
读取以下路径，不输出凭据值：
|
||
|
||
```bash
|
||
openclaw config get models.providers.trapi.models
|
||
openclaw config get agents.defaults.models
|
||
openclaw config get agents.defaults.imageModel
|
||
openclaw models list --provider trapi --json
|
||
openclaw models aliases list --json
|
||
openclaw models status --json
|
||
```
|
||
|
||
对照参考目录，按模型 ID 生成差异：
|
||
|
||
- 新增：目录有、当前没有
|
||
- 更新：模型已存在，但 api、input、contextWindow 或 maxTokens 不一致
|
||
- 保留：现有配置与目录一致
|
||
- 额外：当前存在、目录没有；只报告，不自动删除
|
||
- 别名缺失或冲突：单独列出
|
||
|
||
`GLM-5.1` 不再属于预置目录。若现有实例仍配置它，只列为额外项，不自动删除。
|
||
|
||
### 3. 处理认证
|
||
|
||
如果现有 trapi 认证可解析并且用户没有要求换 Key，保留现有认证，不再索要 Key。
|
||
|
||
首次配置或认证失效时，引导用户在 Gateway 服务环境中设置 `TRAPI_API_KEY`，然后使用 SecretRef：
|
||
|
||
```json
|
||
{
|
||
"source": "env",
|
||
"provider": "default",
|
||
"id": "TRAPI_API_KEY"
|
||
}
|
||
```
|
||
|
||
配置前确认该环境变量对 Gateway 服务进程可见。不得要求用户把 Key 直接粘贴到群聊；私聊中也优先让用户在主机端设置。
|
||
|
||
### 4. 展示变更方案并确认
|
||
|
||
至少展示：
|
||
|
||
- Provider 是否新建
|
||
- 将新增和更新的模型
|
||
- 将新增或调整的别名
|
||
- 当前目录外模型
|
||
- imageModel 是否保持不变
|
||
- 是否需要 Gateway 重载或重启
|
||
- 是否计划进行实时模型调用
|
||
|
||
用户未确认时不得写入。
|
||
|
||
### 5. 安全增量写入
|
||
|
||
使用参考文件中的 Provider 和模型目录。
|
||
|
||
优先使用 CLI 的合并写入：
|
||
|
||
```bash
|
||
openclaw config set models.providers.trapi '<provider-json>' --strict-json --merge
|
||
openclaw config set models.providers.trapi.models '<model-array-json>' --strict-json --merge
|
||
```
|
||
|
||
规则：
|
||
|
||
- Provider 已存在时保留未请求修改的字段。
|
||
- `models.providers.trapi.models` 只提交完整的新条目或明确更新的条目，并使用 `--merge`。
|
||
- 如 CLI 检测到会删除条目并拒绝写入，重新读取配置并修正差异；不要改用 `--replace` 绕过保护。
|
||
- 不直接编辑 `openclaw.json`。
|
||
- 不使用全量 `config.apply`。
|
||
|
||
逐个注册缺失别名：
|
||
|
||
```bash
|
||
openclaw models aliases add <alias> trapi/<model-id>
|
||
```
|
||
|
||
如别名被其他模型占用，报告冲突并让用户决定；不要自动重定向已有别名。
|
||
|
||
### 6. 可选配置 imageModel
|
||
|
||
只有用户明确要求，或现有 imageModel 为空且用户接受建议时才配置。
|
||
|
||
建议链仅引用已配置且认证可用的 trapi 图像模型：
|
||
|
||
1. `trapi/kimi-for-coding`
|
||
2. `trapi/qwen3.6-plus`
|
||
3. `trapi/mimo-v2.5`
|
||
4. `trapi/GLM-5V-Turbo`
|
||
5. `trapi/MiniMax-M3`
|
||
|
||
使用：
|
||
|
||
```bash
|
||
openclaw models set-image trapi/kimi-for-coding
|
||
openclaw models image-fallbacks add trapi/qwen3.6-plus
|
||
```
|
||
|
||
后续 fallback 逐个添加。已有 imageModel 时默认保持原样，不加入未认证的其他 Provider 模型。
|
||
|
||
### 7. 静态验证
|
||
|
||
写入后执行：
|
||
|
||
```bash
|
||
openclaw config validate
|
||
openclaw models list --provider trapi --json
|
||
openclaw models aliases list --json
|
||
openclaw models status --json
|
||
openclaw gateway status
|
||
```
|
||
|
||
静态验证通过条件：
|
||
|
||
- 配置 Schema 有效
|
||
- 新增模型出现在 trapi 列表
|
||
- 别名指向正确模型
|
||
- Gateway 探针正常
|
||
- 没有凭据、模型或 imageModel 缺失警告
|
||
|
||
`models list` 的 `available: true` 只表示配置和认证状态可用，不等于已完成真实推理验证。
|
||
|
||
### 8. 可选实时验证
|
||
|
||
获得用户确认后，只验证本次新增或更新的模型，不默认全量测试。
|
||
|
||
文本模型使用最小请求：
|
||
|
||
```text
|
||
Reply with exactly: OK
|
||
```
|
||
|
||
图像模型还需用一张无敏感信息的测试图片验证图片输入。需要工具能力时，再单独做一次最小工具调用测试。
|
||
|
||
并发数控制在 2–3。记录成功、超时、认证失败、模型不存在和协议不兼容。不要把“返回任意文本”当作所有能力均验证通过。
|
||
|
||
### 9. 报告结果
|
||
|
||
输出以下内容：
|
||
|
||
- 已新增和更新的模型
|
||
- 已注册的别名
|
||
- 保留的现有配置
|
||
- 未处理的额外模型
|
||
- 静态验证结果
|
||
- 实时验证结果或“未执行”
|
||
- 失败项、原因和建议
|
||
- 正确切换方式：`/model <alias>`
|
||
|
||
不要声称可以直接输入 `/<alias>` 切换模型。
|