2026 OpenClaw 前端實戰：
遠端 Mac 上網關對齊 /v1/models 與 OpenAI 相容客戶端及 Monorepo 冒煙路徑
OpenAI 相容客戶端與多數 SDK 會在啟動時請求列表端點；若閘道路徑、基底網址或模型別名與 monorepo 變更不同步，合併後才在生產爆炸。本文給遠端 Mac 可複現：curl／jq、v1_models_smoke.json、與 PR 冪等註解銜接。延伸參考 Monorepo 快取與鏡像、OpenAPI 冒煙、建置度量 PR 摘要。
01 痛點與目標
痛點一：基底網址重複拼接 /v1 導致路徑錯位。痛點二：別名表只在某 workspace 載入，預覽與正式不一致。痛點三：monorepo 變更路徑未觸發閘道冒煙，合併後客戶端才報錯。目標是以薄契約凍結列表回應與別名雜湊，產物可與 main 基線 JSON 對照；Runner 權杖與審查留言分離。
先匯出 GIT_SHA、PR_NUMBER、OPENAI_BASE_URL（主機或含 /v1 擇一）、權杖、MONOREPO_ROOT；審查要機讀 JSON 而非終端片段。建議與本機及 CI 使用相同 Node 大版本以免路徑解析差異。
02 閘道與客戶端對照
curl與相容 SDK須共用同一拼接規則，避免雙重 /v1；README 寫死契約。
| 面向 | 決策要點 |
|---|---|
| 閘道路由 | 是否直連 /v1/models 或反代剝前綴；與健康檢查同進程。 |
| OpenAI 相容客戶端 | 基底是否含 /v1；SDK 與 curl 同契約。 |
| 模型別名 | 別名載入順序與環境；預覽／正式雜湊一致。 |
03 v1_models_smoke.json 欄位
固定 schemaVersion；modelIds 為排序去重後之 id；aliasMapHash 對齊基線。
| 欄位 | 含義 |
|---|---|
schemaVersion git_sha pr_number |
契約版本、提交、PR 編號；供冪等鍵與工件目錄對齊。 |
httpStatus requestUrl |
去敏後請求網址；還原雙前綴。 |
modelIds |
列表中的模型識別字串陣列；與基線做集合差。 |
aliasMapHash |
別名表內容雜湊；變更僅文檔時可與上一版相同。 |
gateHint |
字串：pass／warn／fail，供 OpenClaw 渲染一句話結論。 |
① 契約唯一。② 列表與別名分欄。③ 工件放 .openclaw/reports/<sha>/。
04 HowTo：安裝與驗證腳本
- 安裝：
MONOREPO_ROOT內pnpm install或npm ci同鎖檔；鏡像見 Monorepo 鏡像文。 - 匯出
OPENAI_BASE_URL與權杖；祕鑰勿入日誌。 GET列表端點，jq取data[].id。- 寫
v1_models_smoke.json，對main產v1_models_gate.json。 - OpenClaw 產
pr_v1_models_summary.md；並列 建置度量摘要。 429／5xx退避；401／403／契約404停。
Shell 占位（替換變數後可執行）：
export OPENAI_BASE_URL="https://gateway.example" OPENAI_API_KEY="***"
export GIT_SHA="$(git rev-parse HEAD)" PR_NUMBER="${PR_NUMBER:-0}"
mkdir -p ".openclaw/reports/${GIT_SHA}"
REQ="${OPENAI_BASE_URL%/}/v1/models"
curl -sS -H "Authorization: Bearer ${OPENAI_API_KEY}" "$REQ" \
| tee ".openclaw/reports/${GIT_SHA}/models_raw.json" \
| jq -r '.data[].id' | sort -u > ".openclaw/reports/${GIT_SHA}/model_ids.txt"
jq -n --arg sha "$GIT_SHA" --argjson pr "$PR_NUMBER" --arg url "$REQ" \
--rawfile ids ".openclaw/reports/${GIT_SHA}/model_ids.txt" \
'{schemaVersion:1,git_sha:$sha,pr_number:$pr,httpStatus:200,requestUrl:$url,modelIds:($ids|split("\n")|map(select(length>0))),aliasMapHash:"placeholder"}' \
> ".openclaw/reports/${GIT_SHA}/v1_models_smoke.json"
- 契約與 README 範例一致。
- 變更觸及閘道或別名時必跑全量列表。
05 PR 工作流與路徑閘
paths：packages/gateway/**、config/models*.yaml 觸發全量冒煙；gh pr comment 底加 <!-- openclaw-v1-models:$SHA -->。
gate 為 fail 擋合併；再跑 OpenAPI 冒煙。技術見解列表。
06 常見故障 FAQ
雙重路徑或 404？基底已含 /v1 又拼 /v1/models，或子路徑掛載不符；寫入實際 requestUrl。
列表空或缺別名？上游不可用、閘道快取或 YAML 未載入；對日誌並清快取。
擋合併？缺模型、aliasMapHash 不符、或 401／403；5xx 先退避。