XAG 官方文档

欢迎使用 XAG 高效稳定的 AI API 中转服务。以下是快速上手、使用与故障排查指南。

1. 快速开始

2. 接入主流客户端

我们的 API 完全兼容 OpenAI 格式，支持以下主流客户端无缝接入。

2.1 Chatbox / NextWeb / ChatGPT-Next-Web

• API 域名： https://api.xag-api.com（若客户端要求完整地址，请填 https://api.xag-api.com/v1）
• API 密钥： 填入你在控制台创建的令牌（sk- 开头）

2.2 Codex / Cursor

• Base URL： https://api.xag-api.com/v1
• API Key： 填入你的令牌

2.3 Claude Code 专属配置（程序员推荐）

如果你使用官方的 Claude Code 命令行工具，可以通过环境变量接入我们的服务：

export ANTHROPIC_BASE_URL="https://api.xag-api.com"
export ANTHROPIC_AUTH_TOKEN="sk-你的令牌"

2.4 OpenCode

在 OpenCode 的配置文件中填入：

• API 地址： https://api.xag-api.com/v1
• API Key： 你的令牌

3. 充值与兑换

点击左侧菜单的「充值中心」，选择对应面额进行支付。

重要提示： 购买后请复制卡密，回到控制台的「兑换」页面，粘贴卡密并提交，余额将即时到账。

4. 成功判断与验证

配置成功后，应该满足下面两点：

1. 软件能正常回复“连接成功”或正常对话。
2. 后台调用记录里出现新的调用。

⚠️ 如果软件回复了，但后台没有记录，说明它可能还在走别的账号或别的接口。

⚠️ 如果后台有记录，但软件报错，请把后台调用记录截图发给客服。

5. 常见问题排查（FAQ）

5.1 错误码速查

• 401 Unauthorized： API Key 错、复制少了、前后有空格，或软件还在使用旧 Key。重新复制完整 Key，再保存配置。
• 403 Insufficient account balance： 余额不足或模型权限未开。请联系客服处理，不要重装软件。
• 404 Not Found： 地址写错。OpenAI 兼容软件请用 https://api.xag-api.com/v1；Claude Code 请用 https://api.xag-api.com。
• 405 Method Not Allowed / wss://.../v1/responses： Codex 走了 WebSocket。请按 5.2 节检查 config.toml，确认有 supports_websockets = false。
• Reconnecting / Timeout： 网络、代理、服务端响应慢都有可能。先换网络，再重启软件测试。
• missing YAML frontmatter / invalid SKILL.md： 这是本机旧 Skill 文件格式不对，不是 API Key 问题。找到报错里显示的 skill 文件夹，可以删除那个不用的 skill 文件夹，或暂时忽略。
• C:\Windows\System32： 说明从系统目录启动了终端。关闭窗口，在桌面新建项目文件夹，从项目文件夹地址栏输入 powershell 后再操作。
• 点击软件闪退： 不要反复双击。打开终端输入对应命令查看错误：Codex 输入 codex，Claude Code 输入 claude，OpenCode 输入 opencode；其它工具按对应命令启动。把终端最后一屏截图发给客服。

5.2 为什么 Codex 一直 “Reconnecting 1/5…5/5”？

这不是你的网络问题，也不是站点故障，是 Codex 自身设定。每次启动会先用 WebSocket 协议连接后端，但中转站走的是标准 HTTP 接口，本来就没有 WebSocket，所以这个握手肯定连不上。

Codex 会把这种连不上当成普通网络抖动去重试，每次等 15 秒、连试 5 次，凑满 75 秒后才换到 HTTP。这就是“先卡一分多钟、然后又自己好了”的原因。网上不少流传的往 .env 里写代理没啥用，那一步根本没关掉 WebSocket。

解决办法：在 ~/.codex/config.toml 里把站配成自定义 provider，并加上 supports_websockets = false 这一行，等于直接让 Codex 走 HTTP，这样从第一步就走对路，Reconnecting 会彻底消失。

5.3 用龙虾以及非流式请求报 400

是因为请求缺少了 instructions 字段，可以让 Codex 自己补上。Codex 可以用是因为 baseline instructions 内置了该字段。

6. 重新配置或恢复

如果配置乱了，按下面方式找到配置文件，重新复制对应章节的内容即可。

• Codex：
  Windows: C:\Users\你的用户名\.codex\config.toml
  macOS/Linux: ~/.codex/config.toml
• Claude Code：
  Windows: C:\Users\你的用户名\.claude\settings.json
  macOS/Linux: ~/.claude/settings.json
• OpenCode：
  Windows: C:\Users\你的用户名\.config\opencode\opencode.json
  macOS/Linux: ~/.config/opencode/opencode.json

7. 客服支持

如有任何疑问或需要帮助，请通过以下方式联系我们：

• 官方客服 QQ： 2335351914