返回文章中心

LinkAGI 实用文章 · 2026-07-12

我用 Codex 做了一个“API 地址诊断器”，专治 `/v1` 路径打结

API 地址诊断器桌面版实拍

上一篇文章讲清楚了一个让人反复试错的问题：为什么 Claude Code 的 Base URL 不带 /v1，Codex 却要带，Gemini CLI 又不带？

讲完原理后，我冒出一个更直接的想法：

如果一个问题能被明确判断，就不应该继续让人靠记忆和猜测解决。

所以这次我没有继续写第二篇“配置大全”，而是让 Codex 把这套判断逻辑做成了一个可以点击、可以输错、也可以直接复制配置的小工具。

它叫 API 地址诊断器。

不需要安装依赖，不需要填写 API Key，也不会向服务器发送测试请求。选择客户端、粘贴 Base URL，它就会告诉你最终地址究竟会被拼成什么。

它解决的不是大问题，却是很烦的问题

假设你给 Claude Code 填了：

https://api.linktoagi.com/v1

看起来很像一个完整、专业、没有任何问题的 API 地址。

但 Claude Code 会在 Base URL 后自动追加 /v1/messages。两段拼起来，最终请求就成了：

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

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

Codex 又恰好相反。它在自定义 Responses 服务中通常只追加 /responses，因此 Base URL 应该写到 /v1 这一层。

人脑很容易把三套规则记混，工具却不会。

第一版需求，我只给 Codex 四个目标

我没有一开始就要求“做一个功能齐全的平台”，而是把任务压缩成四件事：

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

除此之外还有两个边界：整个项目必须是纯静态网页；用户不需要提交或保存 API Key。

这样做的好处是，任何人下载文件后都能直接打开，也可以扔到 GitHub Pages、Nginx 或对象存储上。

Codex 做出来的交互，比一张速查表多了什么

页面左侧选择客户端并输入地址，右侧会实时拆解路径：

你填写的 Base URL
        +
客户端自动追加的协议路径
        =
真正发出的请求地址

Claude Code 的正确结果是：

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

Codex 的正确结果是：

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

Gemini CLI 则从根地址继续追加 /v1beta/models/...。

工具会随着客户端切换自动调整推荐地址和配置文件，不需要用户先背会规则才能使用。

我真的点了一次“故意输错看看”

为了避免只测试正确状态，我给页面加了一个有点调皮的按钮：故意输错看看。

在 Claude Code 模式点击它，输入框会变成带 /v1 的错误 Base URL。诊断器马上把完整路径展开，并明确指出 /v1 被拼接了两次。

诊断器识别双重 v1 的真实截图

这不是预先画好的示意图。截图来自项目在本地服务器运行时的真实交互状态。

我实际验证的结果如下：

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

三种客户端切换、错误地址诊断和配置生成都在浏览器里完成了点击测试，控制台没有 JavaScript 报错。

发布前测试，还真的抓到一个问题

第一版页面在我的项目目录中看起来完全正常，但独立启动静态服务器后，下面的“路径拼接关系图”没有加载出来。

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

我随后做了三件事：

把图片收进项目自己的 assets 目录。
将引用改成 ./assets/day1-address-map.jpg。
重新加载页面，确认图片 naturalWidth 为 1280，并检查浏览器日志没有 404。

这类问题很适合交给 Codex 辅助排查，但最后的浏览器实测不能省。代码结构正确，不等于部署形态一定正确。

手机端不是把桌面版硬塞进去

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

API 地址诊断器手机端实拍

手机端会把三个客户端选项改成纵向排列，路径公式也从横向变成逐段展示。实测页面宽度和浏览器宽度同为 390 像素，没有出现横向滚动条。

这种工具很可能是用户看完文章后直接从微信里打开，因此手机端可用不是额外装饰，而是发布条件。

项目是怎么组成的

整个项目只有四类文件：

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

没有构建工具，也没有运行时依赖。核心判断逻辑可以简化成下面这样：

const hasDuplicateV1 = client !== "codex" && /\/v1$/i.test(baseUrl);
const missingV1 = client === "codex" && !/\/v1$/i.test(baseUrl);

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

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

真实项目还会识别缺少 https://、把 /messages 或 /responses 完整端点误当 Base URL 等情况。

你也可以在本地跑起来

进入项目目录后执行：

python3 -m http.server 8787

然后在浏览器打开：

http://localhost:8787

直接双击 index.html 也能使用，但通过本地服务器运行更接近真实部署环境。

可以尝试下面几组输入：

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

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

为什么这种小项目适合用来推广 API 服务

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

这个项目把 LinkAGI 放在三个合理位置：

默认演示地址使用 https://api.linktoagi.com，用户打开就能体验。
配置结果直接生成 LinkAGI 对应写法，减少从文章到使用之间的步骤。
页面底部提供控制台、文档和地址复制入口，但不遮挡诊断功能。

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

这比在正文里反复插入广告自然得多。

下一步还能怎么继续做

这个诊断器可以继续增加：

根据报错文本判断是地址、Key、模型权限还是余额问题。
一键生成 macOS、Windows 和 Linux 的环境变量命令。
导入脱敏后的客户端配置，自动标记错误字段。
生成一张可以发给同事的诊断结果图片。

但第一版先停在“把一个问题解决干净”。小工具最怕不是功能少，而是打开以后不知道该点哪里。

需要体验统一 API 服务，可以打开 LinkAGI 控制台；Claude Code、Codex 和 Gemini CLI 的完整配置教程在 LinkAGI 文档。

发布建议

推荐标题：

我用 Codex 做了一个“API 地址诊断器”，专治 /v1 路径打结

备选标题：

不再背配置：我让 Codex 把 Claude、Codex、Gemini 的地址规则做成了工具
两个 /v1 为什么会得到 404？我顺手做了个在线诊断器
用 Codex 做一个真能用的小项目：AI API 地址诊断器

推荐摘要：

Claude Code、Codex、Gemini CLI 的 Base URL 到底要不要带 /v1？与其继续背规则，不如让工具自动判断。本文记录我用 Codex 制作、实测并修复一个纯前端 API 地址诊断器的完整过程。

推荐标签：

Codex Claude Code Gemini CLI AI 编程 独立开发 API 实用工具