359 lines
9.8 KiB
Markdown
359 lines
9.8 KiB
Markdown
# OpenClaw 外部真实验证
|
||
|
||
日期：2026-05-26
|
||
|
||
## 目的
|
||
|
||
这份文档补齐两类长期缺口：
|
||
|
||
1. `sub2api-cn-relay-manager` 之外的最终使用面验证
|
||
- 即真实用户拿到宿主 key 后，在本机 `OpenClaw` 上是否真的可用
|
||
2. OpenClaw 本地运行时补丁的可复用操作流程
|
||
- 包括 `MiniMax` 的代理兼容补丁
|
||
- 以及升级后如何自动提醒重新打补丁
|
||
|
||
它不替代：
|
||
|
||
- `docs/REAL_HOST_ACCEPTANCE_RUNBOOK.md`
|
||
- 负责 `relay-manager -> host -> upstream` 三段验收
|
||
- 本文
|
||
- 负责 `user key -> OpenClaw -> public endpoint` 最后一段真实使用验证
|
||
|
||
## 当前结论
|
||
|
||
截至 2026-05-27，公网根端点已经切到 patched host，可统一按 OpenAI 兼容根地址使用：
|
||
|
||
- `base_url=https://sub.tksea.top`
|
||
- 若客户端强制要求显式 `/v1`，则使用 `https://sub.tksea.top/v1`
|
||
|
||
OpenClaw 当前外部真实验证结论如下：
|
||
|
||
| OpenClaw provider | model | base_url | 结果 | 说明 |
|
||
| ----------------- | ------------------------ | ---------------------------- | ---- | ------------------------------------------------------- |
|
||
| `tksea` | `kimi-k2.6` | `https://sub.tksea.top/kimi` | PASS | 已在 OpenClaw `agent` 路径验证通过 |
|
||
| `tksea-gpt` | `gpt-5.4` | `https://sub.tksea.top/v1` | PASS | `openclaw infer model run --local` 返回 `pong` |
|
||
| `tksea-gpt` | `gpt-5.4-mini` | `https://sub.tksea.top/v1` | PASS | `openclaw infer model run --local` 返回 `pong` |
|
||
| `tksea-gpt` | `gpt-5.5` | `https://sub.tksea.top/v1` | FAIL | upstream 当前返回 `503 Service temporarily unavailable` |
|
||
| `tksea-minimax` | `MiniMax-M2.5-highspeed` | `https://sub.tksea.top/v1` | PASS | 对应 remote43 导入 `minimax-53hk` 后的公网消费口径 |
|
||
| `tksea-minimax` | `MiniMax-M2.7-highspeed` | `https://sub.tksea.top/v1` | PASS | 对应 remote43 导入 `minimax-53hk` 后的公网消费口径 |
|
||
| `minimax53hk` | `MiniMax-M2.5-highspeed` | `https://api.53hk.cn/v1` | PASS | 本地补丁后恢复的 53hk 直连口径 |
|
||
| `minimax53hk` | `MiniMax-M2.7-highspeed` | `https://api.53hk.cn/v1` | PASS | 本地补丁后恢复的 53hk 直连口径 |
|
||
|
||
与 relay-manager pack 内 `provider_id` 的映射关系当前明确为：
|
||
|
||
- `openai-zhongzhuan` → `tksea-gpt`
|
||
- `minimax-53hk` → `tksea-minimax`
|
||
- `deepseek-chat-official` → `deepseek-official`（2026-05-27 已补齐 `auth-profiles.json`，`openclaw infer model run --model \"deepseek-official/deepseek-chat\" --prompt 'Reply with exactly OK' --json` 返回 `OK`）
|
||
|
||
## 前置条件
|
||
|
||
### 远端入口
|
||
|
||
- 用户注册页：`https://sub.tksea.top/portal/`
|
||
- 旧地址：`https://sub.tksea.top/kimi-portal/`
|
||
- 当前应作为兼容跳转入口保留，而不是继续作为正式主地址
|
||
- 宿主 OpenAI 兼容入口：`https://sub.tksea.top`
|
||
|
||
### OpenClaw 本地要求
|
||
|
||
- 已安装 `OpenClaw`
|
||
- 本机代理环境可用：
|
||
- `HTTP_PROXY`
|
||
- `HTTPS_PROXY`
|
||
- 已写入至少一种测试 key：
|
||
- `tksea`
|
||
- `tksea-gpt`
|
||
- `tksea-minimax`
|
||
- `minimax53hk`
|
||
|
||
### 已存在的本地补丁脚本
|
||
|
||
下列脚本当前位于操作者本机，不在本仓库内版本化；本仓库只记录它们的使用方法与验收口径：
|
||
|
||
- `~/.openclaw/bin/apply-openclaw-minimax-proxy-fix.sh`
|
||
- `~/.openclaw/bin/openclaw-minimax-post-upgrade-check.sh`
|
||
- `~/.openclaw/bin/openclaw-minimax-proxy-reminder.sh`
|
||
- `~/.openclaw/bin/install-openclaw-minimax-reminder-cron.sh`
|
||
|
||
## 根因与补丁范围
|
||
|
||
本轮 `MiniMax` 的 OpenClaw 故障，不是模型名大小写，也不是 allowlist 漏配导致。
|
||
|
||
真实根因是：
|
||
|
||
- `curl` 可以通过系统 `HTTP(S)_PROXY` 正常访问 `53hk` 与 `tksea` 的 `MiniMax`
|
||
- 但 `OpenClaw -> pi-ai -> openai-node` 默认没有继承同样的代理行为
|
||
- 因此在本地 one-shot 路径里被吞成：
|
||
- `No text output returned`
|
||
- `Connection error`
|
||
|
||
当前补丁做法是：
|
||
|
||
- 对本机安装的 `pi-ai` 运行时文件注入 `EnvHttpProxyAgent`
|
||
- 让 OpenAI SDK 使用带系统代理的 `fetch`
|
||
|
||
补丁目标文件：
|
||
|
||
- `~/.local/lib/node_modules/openclaw/node_modules/@earendil-works/pi-ai/dist/providers/openai-completions.js`
|
||
|
||
注意：
|
||
|
||
- 这不是本仓库源码补丁
|
||
- `OpenClaw` 升级后，这个补丁可能会被覆盖
|
||
|
||
## 用例设计
|
||
|
||
### 用例 1：提醒任务已安装
|
||
|
||
目的：
|
||
|
||
- 确保 OpenClaw 升级后，系统会自动提醒是否需要重新打补丁
|
||
|
||
执行：
|
||
|
||
```bash
|
||
crontab -l
|
||
```
|
||
|
||
预期：
|
||
|
||
- 输出中包含：
|
||
- `# BEGIN openclaw-minimax-proxy-reminder`
|
||
- `@reboot sleep 180 && "~/.openclaw/bin/openclaw-minimax-proxy-reminder.sh" ...`
|
||
- `*/30 * * * * "~/.openclaw/bin/openclaw-minimax-proxy-reminder.sh" ...`
|
||
|
||
### 用例 2：补丁状态诊断
|
||
|
||
目的：
|
||
|
||
- 在升级后先判定当前是否还带着代理补丁
|
||
|
||
执行：
|
||
|
||
```bash
|
||
~/.openclaw/bin/apply-openclaw-minimax-proxy-fix.sh doctor
|
||
```
|
||
|
||
预期：
|
||
|
||
- 输出 `OpenClaw` 版本
|
||
- 输出目标 `pi-ai` 文件路径
|
||
- 输出当前 `patched/not_patched`
|
||
- 输出 `HTTP_PROXY/HTTPS_PROXY/NO_PROXY`
|
||
- 输出备份列表
|
||
|
||
### 用例 3：升级后一键恢复
|
||
|
||
目的：
|
||
|
||
- 在 OpenClaw 升级后，自动完成 `doctor -> apply -> verify`
|
||
|
||
执行：
|
||
|
||
```bash
|
||
~/.openclaw/bin/openclaw-minimax-post-upgrade-check.sh
|
||
```
|
||
|
||
预期：
|
||
|
||
- `doctor` 正常输出
|
||
- `apply` 在已打补丁时表现为幂等
|
||
- `verify` 最终四条 `MiniMax` smoke 全部通过
|
||
|
||
### 用例 4：53hk MiniMax 直连恢复
|
||
|
||
目的：
|
||
|
||
- 验证官方宿主之外，老的 `53hk` 线路在 OpenClaw 本地也已恢复
|
||
|
||
执行：
|
||
|
||
```bash
|
||
openclaw infer model run --local \
|
||
--model "minimax53hk/MiniMax-M2.5-highspeed" \
|
||
--prompt "reply with pong only" \
|
||
--json
|
||
|
||
openclaw infer model run --local \
|
||
--model "minimax53hk/MiniMax-M2.7-highspeed" \
|
||
--prompt "reply with pong only" \
|
||
--json
|
||
```
|
||
|
||
预期：
|
||
|
||
- `ok=true`
|
||
- 输出文本为 `pong`
|
||
|
||
### 用例 5：tksea MiniMax 真实调用
|
||
|
||
目的：
|
||
|
||
- 验证 patched host 暴露的 `MiniMax` 公网入口，已经可被 OpenClaw 正常消费
|
||
|
||
执行：
|
||
|
||
```bash
|
||
openclaw infer model run --local \
|
||
--model "tksea-minimax/MiniMax-M2.5-highspeed" \
|
||
--prompt "reply with pong only" \
|
||
--json
|
||
|
||
openclaw infer model run --local \
|
||
--model "tksea-minimax/MiniMax-M2.7-highspeed" \
|
||
--prompt "reply with pong only" \
|
||
--json
|
||
```
|
||
|
||
预期：
|
||
|
||
- `ok=true`
|
||
- 输出文本为 `pong`
|
||
|
||
### 用例 6：tksea GPT 可用模型验证
|
||
|
||
目的：
|
||
|
||
- 区分“GPT 配置是否正确”与“某个具体模型当前 upstream 是否可用”
|
||
|
||
执行：
|
||
|
||
```bash
|
||
openclaw infer model run --local \
|
||
--model "tksea-gpt/gpt-5.4" \
|
||
--prompt "reply with pong only" \
|
||
--json
|
||
|
||
openclaw infer model run --local \
|
||
--model "tksea-gpt/gpt-5.4-mini" \
|
||
--prompt "reply with pong only" \
|
||
--json
|
||
```
|
||
|
||
预期：
|
||
|
||
- `gpt-5.4` 返回 `pong`
|
||
- `gpt-5.4-mini` 返回 `pong`
|
||
|
||
### 用例 7：tksea GPT 不稳定模型验证
|
||
|
||
目的：
|
||
|
||
- 把“不稳定模型”显式记录为当前运行态限制，而不是笼统地宣称 GPT 全量可用
|
||
|
||
执行：
|
||
|
||
```bash
|
||
openclaw infer model run --local \
|
||
--model "tksea-gpt/gpt-5.5" \
|
||
--prompt "reply with pong only" \
|
||
--json
|
||
```
|
||
|
||
预期：
|
||
|
||
- 当前基线结果是失败
|
||
- 错误为：
|
||
- `503 Service temporarily unavailable`
|
||
|
||
### 用例 8：DeepSeek 官方 OpenClaw 配置缺口探测
|
||
|
||
目的：
|
||
|
||
- 区分“remote43 上 `deepseek-chat-official` 已导入并能 completion”与“本机 OpenClaw 已经可直接消费”这两个结论
|
||
|
||
执行：
|
||
|
||
```bash
|
||
openclaw infer model run --local \
|
||
--model "deepseek-official/deepseek-chat" \
|
||
--prompt "reply with pong only" \
|
||
--json
|
||
```
|
||
|
||
预期：
|
||
|
||
- 当前基线结果是失败
|
||
- 失败点不是模型推理，而是本机 auth/profile 尚未就绪
|
||
- 典型错误：
|
||
- `No API key found for provider "deepseek-official"`
|
||
|
||
## 推荐执行顺序
|
||
|
||
每次 OpenClaw 升级后，按下面顺序执行：
|
||
|
||
1. 检查提醒任务
|
||
|
||
```bash
|
||
crontab -l
|
||
```
|
||
|
||
2. 先诊断当前状态
|
||
|
||
```bash
|
||
~/.openclaw/bin/apply-openclaw-minimax-proxy-fix.sh doctor
|
||
```
|
||
|
||
3. 再执行升级后一键恢复
|
||
|
||
```bash
|
||
~/.openclaw/bin/openclaw-minimax-post-upgrade-check.sh
|
||
```
|
||
|
||
4. 验证 `tksea-gpt` 当前可用模型
|
||
|
||
```bash
|
||
openclaw infer model run --local --model "tksea-gpt/gpt-5.4" --prompt "reply with pong only" --json
|
||
openclaw infer model run --local --model "tksea-gpt/gpt-5.4-mini" --prompt "reply with pong only" --json
|
||
```
|
||
|
||
5. 验证 `tksea-minimax`
|
||
|
||
```bash
|
||
openclaw infer model run --local --model "tksea-minimax/MiniMax-M2.5-highspeed" --prompt "reply with pong only" --json
|
||
openclaw infer model run --local --model "tksea-minimax/MiniMax-M2.7-highspeed" --prompt "reply with pong only" --json
|
||
```
|
||
|
||
## 诊断分流
|
||
|
||
### `/v1/models` 能出模型，但 OpenClaw 本地仍报 `Connection error`
|
||
|
||
优先排查：
|
||
|
||
1. `doctor` 是否显示 `patched`
|
||
2. 当前 shell 是否存在 `HTTP_PROXY` / `HTTPS_PROXY`
|
||
3. OpenClaw 是否刚升级，导致 `pi-ai` patch 丢失
|
||
|
||
### GPT 某个模型失败，但同组其他模型正常
|
||
|
||
优先判断为：
|
||
|
||
- 特定模型 upstream 不稳定
|
||
- 不要误判成整个 `tksea-gpt` provider 失效
|
||
|
||
当前基线就是：
|
||
|
||
- `gpt-5.4`：PASS
|
||
- `gpt-5.4-mini`：PASS
|
||
- `gpt-5.5`：FAIL（503）
|
||
|
||
### MiniMax API 直连可用，但 OpenClaw 本地失败
|
||
|
||
优先判断为：
|
||
|
||
- OpenClaw 本地运行时代理兼容问题
|
||
- 不是宿主 key、也不是 relay-manager 导入问题
|
||
|
||
## 结论口径
|
||
|
||
截至 2026-05-26，当前可以对外采用下面这套简化口径：
|
||
|
||
1. patched host 公网根入口已可直接给 OpenAI 兼容客户端使用：
|
||
- `https://sub.tksea.top`
|
||
2. OpenClaw 的 `MiniMax` 本地运行时兼容问题已经通过代理补丁恢复
|
||
3. `tksea-minimax` 当前可用
|
||
4. `tksea-gpt` 当前不是“全模型可用”，而是：
|
||
- `gpt-5.4` 可用
|
||
- `gpt-5.4-mini` 可用
|
||
- `gpt-5.5` 当前仍需视 upstream 状态单独观察
|