dsh-TUI 接入 OpenAI 兼容接口的配置步骤与错误排查

dsh-TUI 接入 OpenAI 兼容接口时，出现 401 或 404 请求错误，通常不是工具本身的问题，而是接口地址或密钥没有对齐服务商提供的兼容网关。先拿到正确的 API Base 和 Key，再改配置，最后用 curl 做独立验证，就能定位大部分故障。

适用场景：自己申请了 OpenAI 兼容服务，但 dsh-TUI 请求返回 401 或 404。处理方向：按“获取端点信息 → 修改配置文件 → curl 测试 → 按状态码分路径”的顺序执行。验证方式：关注 curl 和 dsh-TUI 日志中的 HTTP 状态码。风险边界：api_key 属于敏感信息，建议用环境变量或密钥管理工具注入，不要直接写在明文配置中。

获取接口地址与认证令牌

API Base 和 Key 一般由服务商在开通接口后提供。如果不确定位置，先查控制台的“API Keys”或“接入信息”页面，通常会有形如 https://api.example.com/v1 的地址，以及一串以 sk- 开头的令牌。两者是配对使用的，base 是请求入口，key 用于身份认证。

注意：base 通常已经包含 /v1 版本号，后续请求会拼接 /chat/completions。如果服务商给的是根地址（无版本），需要按文档补全。我们这里用占位符：https://api.example.com/v1 和 sk-your-api-key。实际配置时把 example.com 和 your-api-key 换成自己的值。

在dsh-TUI中配置接口路由与密钥

dsh-TUI 的配置通常位于 ~/.config/dsh-tui/config.yaml 或软件安装目录下的 config.toml。找到后，确认存在两个关键字段：base_url 和 api_key。如果没有，手动新增。

base_url: https://api.example.com/v1
api_key: sk-your-api-key

注意：不要带引号，也不要多加空格。修改后保存，重启 dsh-TUI 或执行配置重载命令（通常是 :reload 或 Ctrl+R）。如果使用系统环境变量，也可以设置为 DASH_TUI_BASE_URL 和 DASH_TUI_API_KEY，但需要确认软件是否支持。

发送测试请求验证连通性

先用 curl 直接请求 OpenAI 兼容接口，排除 dsh-TUI 配置之外的问题。在终端执行：

curl -X POST https://api.example.com/v1/chat/completions -H "Authorization: Bearer sk-your-api-key" -H "Content-Type: application/json" -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"hello"}]}'

成功响应会包含 choices 数组，例如：

{"id":"chatcmpl-...","object":"chat.completion","choices":[{"index":0,"message":{"role":"assistant","content":"Hello! ..."},"finish_reason":"stop"}],"usage":{...}}

如果 curl 同样返回 401 或 404，问题在服务商配置而非 dsh-TUI。此时检查 URL 和 Key。如果 curl 返回 200，说明服务可用，接着用 dsh-TUI 的内置测试命令（部分版本支持 /test 或 ping）重新验证。若内置测试失败，再检查 dsh-TUI 的配置文件是否被正确加载。

区分401与404错误的处理路径

401 Unauthorized：日志中常见 401、Unauthorized、Invalid API key。处理步骤：

确认 api_key 是否完整复制，没有遗漏字符或额外空格。
确认服务商是否更换了 key，旧 key 已失效。
确认 base_url 是否写错，少数服务商在路径错误时也会返回 401。

404 Not Found：日志中常见 404、Not Found、endpoint not found。处理步骤：

确认 base_url 是否包含 /v1，缺失时组合出的 URL 会找不到路由。
确认接口路径是 /chat/completions 而不是 /completions 或 /v1/chat/completions/ 加斜杠。
curl 测试时使用完整 URL，如果 curl 成功而 dsh-TUI 失败，对比 dsh-TUI 实际发送的请求路径是否与 curl 一致。

这两类错误通常不会同时出现。若先处理 401 再看到 404，说明认证通过后路径仍有问题；反过来则说明路径没问题但令牌无效。