sub2api-cn-relay-manager/docs/OPENCLAW_EXTERNAL_VALIDATION.md

# 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 状态单独观察