用 Codex 做一个 API 地址诊断器：Claude Code、Codex、Gemini CLI 的 /v1 排错实战

今天我重新对 LinkAGI 的四条接口路径发了一轮不带 API Key 的请求：

Claude Code、Codex、Gemini CLI 对应的正确协议路由均返回 401 Invalid token；
故意重复一层 /v1 后返回 404 Invalid URL。

这个结果看起来有点反直觉。为什么 401 反而说明地址大概率正确，404 才表示 Base URL 真正填错了？

原因是 401 表示请求已经穿过域名、HTTPS 和接口路由，走到了令牌校验；404 则说明客户端拼出来的路径根本不存在。

与其让使用者继续背规则，我用 Codex 把判断逻辑做成了一个可以直接点击的纯前端工具。

在线体验：https://docs.linktoagi.com/tools/endpoint-lab/
源码下载：https://docs.linktoagi.com/tools/endpoint-lab/LinkAGI-Endpoint-Lab.zip
LinkAGI 控制台：https://api.linktoagi.com

诊断器不要求填写 API Key，也不会主动向服务端发起测试请求。选择客户端、粘贴 Base URL，页面会展示客户端最终拼出的请求地址，并生成可以复制的配置。

1. 为什么两个 `/v1` 会得到 404

假设 Claude Code 的 Base URL 写成：

text 复制代码

https://api.linktoagi.com/v1

Claude Code 还会在后面自动追加 /v1/messages。最终请求会变成：

text 复制代码

https://api.linktoagi.com/v1/v1/messages

两个 /v1 见面不会变得更强，只会得到 404。

Codex 的 Responses 配置又恰好相反。它继续追加的是 /responses，所以 Base URL 需要写到 /v1 这一层：

text 复制代码

https://api.linktoagi.com/v1 + /responses
= https://api.linktoagi.com/v1/responses

Gemini CLI 则使用根地址，由客户端继续拼接 /v1beta/models/...。

人脑很容易把三套规则记混，确定性的程序不会。

2. 第一版需求只保留四个目标

支持 Claude Code、Codex、Gemini CLI 三种客户端。
展示 Base URL、客户端追加路径和最终请求地址。
识别 /v1 重复、Codex 遗漏 /v1、误填完整端点等问题。
生成可以直接复制的客户端配置。

项目还有两个明确边界：必须是纯静态网页；不接收、不保存 API Key。

整个项目只有这些文件：

text 复制代码

linkagi-endpoint-lab/
├── index.html
├── styles.css
├── app.js
├── README.md
└── assets/
    └── day1-address-map.jpg

没有构建工具，也没有运行时依赖。下载后直接打开即可，也可以放到 GitHub Pages、Nginx 或对象存储。

3. 核心判断逻辑

诊断器会先规范化 URL，再根据客户端判断重复前缀、缺失前缀和误填完整端点：

javascript 复制代码

const hasDuplicateV1 = client !== "codex" && /\/v1$/i.test(baseUrl);
const missingV1 = client === "codex" && !/\/v1$/i.test(baseUrl);
const containsEndpoint = /\/(messages|responses|v1beta\/models)(\/|$)/i.test(baseUrl);

if (hasDuplicateV1) {
  showWarning("/v1 可能会被拼接两次");
}

if (missingV1) {
  showWarning("Codex 的 Base URL 少了一层 /v1");
}

if (containsEndpoint) {
  showWarning("这里需要 Base URL，不要直接填完整接口路径");
}

真实页面还会识别缺少 https://、空地址和多余尾部斜杠等情况。

4. 真实错误状态测试

为了避免只验证正确状态，我给页面加了一个"故意输错看看"按钮。

在 Claude Code 模式点击后，Base URL 会变成带 /v1 的错误写法。页面立即展开 /v1/v1/messages，并明确提示"路径打结了"。

2026 年 7 月 20 日完成的浏览器测试结果：

操作	页面生成结果	判断
Claude Code + 根地址	`/v1/messages`	正确
Claude Code + `/v1`	`/v1/v1/messages`	警告
Codex + `/v1`	`/v1/responses`	正确
Codex + 根地址	`/responses`	警告
Gemini CLI + 根地址	`/v1beta/models/...`	正确

5. 前端判断之外，再请求真实接口

只看前端拼接还不够。我又向线上服务发起四次不带 Key 的 POST 请求：

bash 复制代码

curl -X POST -H 'Content-Type: application/json' -d '{}' \
  https://api.linktoagi.com/v1/messages

curl -X POST -H 'Content-Type: application/json' -d '{}' \
  https://api.linktoagi.com/v1/responses

curl -X POST -H 'Content-Type: application/json' -d '{}' \
  'https://api.linktoagi.com/v1beta/models/gemini-2.5-flash:generateContent'

curl -X POST -H 'Content-Type: application/json' -d '{}' \
  https://api.linktoagi.com/v1/v1/messages

前三条正确协议路由都返回 401 Invalid token，重复 /v1 的错误路由返回 404 Invalid URL。

一套更有效的排错顺序是：

域名和 HTTPS 是否可达；
请求有没有到达正确路由；
API Key 是否有效；
模型权限、余额和上游状态是否正常。

如果地址已经错了，换 Key、充值、重装客户端都不会解决问题。

6. 发布测试抓到的资源路径问题

第一版页面在项目目录里看起来完全正常，但单独启动静态服务器后，路径关系图没有加载出来。

原因是图片最初放在项目文件夹外面，HTML 使用了 ../ 引用。开发时两个目录都在本机，很容易误以为没有问题；真正把项目目录作为网站根目录后，浏览器就找不到图片了。

修复方式是把图片收进项目自己的 assets 目录，改为 ./assets/... 引用，再重新检查资源状态和浏览器日志。

代码结构正确，不代表部署形态一定正确。真正发布前，浏览器实测不能省。

7. 390px 手机端实测

我又用 390 像素宽的手机视口重新跑了一次线上页面。

三个客户端选项会改成纵向排列，路径公式也会逐段展示。实测页面宽度与浏览器宽度都是 390 像素，没有横向滚动条，控制台无 JavaScript 报错。

8. 本地运行与在线体验

本地运行：

bash 复制代码

cd linkagi-endpoint-lab
python3 -m http.server 8787

打开：

text 复制代码

http://localhost:8787

可以依次尝试：

text 复制代码

api.example.com
https://api.example.com/v1
https://api.example.com/v1/messages
https://api.example.com/

再切换 Claude Code、Codex 和 Gemini CLI，观察同一个地址如何得到不同诊断结果。

9. 一个实用工具比一段广告更容易被记住

直接告诉用户"我们支持很多模型"，很难让人记住。解决一个他今天就可能遇到的问题，记忆会自然得多。

诊断器默认使用 LinkAGI 地址演示，能够直接生成对应配置；页面底部也提供控制台、文档和地址复制入口，但这些内容不会遮挡工具本身。

即使用户暂时不需要购买服务，也能带走一个有用的工具；真正需要配置 Claude Code、Codex 或 Gemini CLI 时，又能直接找到入口。

低成本带来的第一次尝试很重要，但真正让人留下来的，始终是一次少走弯路的体验。

用 Codex 做一个 API 地址诊断器：Claude Code、Codex、Gemini CLI 的 /v1 排错实战

1. 为什么两个 /v1 会得到 404

2. 第一版需求只保留四个目标

3. 核心判断逻辑

4. 真实错误状态测试

5. 前端判断之外，再请求真实接口

6. 发布测试抓到的资源路径问题

7. 390px 手机端实测

8. 本地运行与在线体验

9. 一个实用工具比一段广告更容易被记住

相关入口

1. 为什么两个 `/v1` 会得到 404