外接与兼容类问题

本页适用于所有第三方客户端外接场景（IDE 插件、聊天客户端、网关工具等）。官方 CLI 的问题请看 Claude Code 专项 和 Codex 专项。

外接前必须确认的 5 项

开始配置前先对齐这 5 项，任何一项对不上都可能导致 403 / 401 / 模型不可用：

项	说明
分组	令牌属于哪个分组，该分组是否包含你要用的模型
协议	客户端走 Anthropic Messages 还是 OpenAI Responses
Base URL	Claude 类不带 /v1，Codex / OpenAI 兼容类带 /v1
请求头	外接场景通常需要补对应的 User-Agent
模型	有些客户端允许留空，有些必须填准确的模型 ID

Base URL 到底要不要加 /v1？

• Claude 类接入（Anthropic Messages 协议）：https://api.wow3.top —— 不带 /v1
• Codex / OpenAI 兼容类接入（Responses / Chat Completions 协议）：https://api.wow3.top/v1 —— 带 /v1

最常见的错误就是把 Claude 的地址误加了 /v1，或把 Codex 的地址漏了 /v1。

部分客户端会自动补全

有些客户端（如 Chatbox）会自己在主机地址后拼接 /v1/responses 这类路径，此时填写框里就不要再手动带 /v1。填完看一眼界面上的完整地址预览，确认最终请求地址正确即可。

外接调用返回 403 block / 403 Forbidden

按顺序排查：

1. 令牌分组是否匹配当前模型类型
2. Base URL 的 /v1 是否带错（Claude 不带、Codex 要带）
3. 请求头里的 User-Agent 是否缺失，或填成了另一种模型类型的 UA
4. 客户端是否真的把请求头发出去了——部分客户端界面上填了，实际并没有传
5. Authorization 是否仍为 Bearer sk-*** 格式

User-Agent 怎么填？

不同接入类型要用对应的 UA，不能混用：

# Claude 外接
User-Agent: claude-cli/2.0.76 (external, cli)

# Codex 外接
User-Agent: codex_cli_rs/0.77.0 (Windows 10.0.26100; x86_64) WindowsTerminal

# 国产模型外接（用浏览器型 UA）
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:149.0) Gecko/20100101 Firefox/149.0

版本号不必与上面完全一致，但类型必须对应：把 Claude 的 UA 复用到 Codex 接入上会直接被拒。

JetBrains IDE 里插件能看到，但调用报 401

优先检查：

• IDE 是否读到了旧的本地认证状态（官网 OAuth 残留）
• 令牌是否已切到正确分组
• 插件是否覆盖了本机的 settings.json

推荐做法：先用 cc-switch 在本机把 Claude Code 或 Codex 配通，确认命令行能正常对话，再让 IDE 复用本机环境。

本机 CLI 可用，但 IDE / Trae 里不可用

问题不在令牌，在 IDE 侧配置。优先排查：

• IDE 是否读取了另一个配置文件
• 请求头有没有真正带出去
• IDE 对本地代理或证书是否有额外限制
• 如果 Claude 正常、Codex 不正常，大概率是 Codex 地址漏了 /v1，或者 model 仍填着 Claude 的模型名

Trae 中改了 Base URL 还是连不上

• 先确认 Claude / Codex 的地址没写反（Claude 不带 /v1，Codex 带 /v1）
• 确认插件允许保存完整的自定义地址（部分版本会截断）
• 确认当前插件版本确实支持外接自定义端点

具体步骤见 Trae 配置教程。