> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aioagi.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# 常见问题

> 排查 API Key、模型、余额、端点和客户端配置问题。

## API Key 放在哪里？

API Key 必须放在服务端环境变量或密钥管理系统中。不要把 Key 写入前端代码、移动端包体、公开文档或 Git 仓库。

## 为什么 OpenAI SDK 可以直接调用？

AIOAGI 提供 OpenAI 兼容接口。你通常只需要替换 `base_url` 和 `api_key`，并把 `model` 改为控制台支持的模型名称。

## 如何查看可用模型？

你可以在控制台查看模型列表，也可以调用 `GET /models` 获取当前 Key 可访问的模型。

## 请求失败时先检查什么？

* `Authorization` 是否为 `Bearer sk-...` 格式。
* `base_url` 是否包含 `/v1`。
* 模型名称是否与控制台一致。
* 账户余额或 Token 组额度是否充足。
* 请求体是否为合法 JSON。

## 出现 `Failed to fetch` 怎么办？

按以下顺序排查：

1. 检查当前令牌分组是否支持所选模型。
2. 刷新页面，重新打开聊天窗口，再发起一次请求。
3. 检查应用设置中的接口地址和 API Key 是否正确。
4. 切换网络环境，确认是否需要开启或关闭代理/VPN。
5. 如果是浏览器应用，检查控制台是否有跨域、网络或证书错误。

## Codex 返回 `Unexpected status 403 Forbidden` 怎么办？

如果你在 Codex 中看到类似下面的报错，通常先检查本地网络和代理环境：

```text theme={null}
Unexpected status 403 Forbidden: openai_error, url: https://api.aiearth.dev/v1/responses, cf-ray: ...
```

按以下顺序排查：

1. 检查代理或 VPN 状态。先确认是否开启了 VPN，再尝试切换为关闭状态；如果当前未开启，也可以反向测试开启后再重试。
2. 重置本地网络环境。必要时重启网络连接，并重启电脑后再试一次。
3. 检查 Codex 中配置的 `base_url` 和 API Key 是否正确，确认请求地址仍为可用的 OpenAI 兼容接口。端点和支持策略可能变化，请以控制台和开发者指南显示的信息为准。
4. 重装codex，删除.codex目录文件后重装codex（证实有效）。
5. 如果以上尝试后仍无法恢复，请通过微信联系 AIOAGI 获取技术支持，并提供报错时间、请求地址、模型名称和完整错误信息，便于定位问题。

## 为什么 Claude Code 和 Codex 等 CLI 越用越贵？

这通常先看请求日志里的输入上下文大小。Claude Code、Codex 等 CLI 工具会在同一个 session 中持续累积对话历史、项目说明、文件片段和工具结果。随着上下文变长，每一轮请求需要发送的输入 Token 也会增加，所以后续扣费可能明显高于刚开始使用时。

建议先在控制台或客户端日志中检查每次请求的输入 Token、上下文长度和缓存命中情况。如果发现同一个 session 的输入上下文持续变大，可以新开 session、压缩历史上下文、减少无关文件片段，或把长任务拆成多个独立步骤。实际扣费仍以控制台日志、Token 组规则和当前模型费率为准。

## 为什么 `Claude + OpenCode` 完全没有缓存、费用暴增？

原文参考：[CSDN 博客主页](https://blog.csdn.net/qq_36396104)。

这通常不是单纯的模型价格问题，而是缓存机制、客户端提示词组织方式和网关协议转换共同影响。

OpenAI 侧的 Prompt Caching 会自动生效。只要请求提示词足够长，且前缀保持一致，`gpt-5.5`、`gpt-4o` 及之后的模型通常可以自动复用缓存。你可以在日志或响应的 `usage.prompt_tokens_details.cached_tokens` 中查看命中的缓存 Token。Codex 类工具通常会把系统指令、固定项目上下文和工具说明放在前面，把动态对话放在后面，这更容易命中 OpenAI 的前缀缓存。

Claude 侧需要请求明确启用缓存控制。常见方式是在 Anthropic 原生请求中加入 `cache_control`，例如顶层自动缓存或内容块级缓存断点：

```json theme={null}
{
  "cache_control": {
    "type": "ephemeral"
  }
}
```

如果 OpenCode 或其他客户端把 Claude 当作 OpenAI 兼容模型，通过 `/v1/chat/completions` 发送请求，但请求体里没有 Claude 所需的 `cache_control` 信息，网关通常无法凭空判断应该在哪里设置缓存断点。结果就是大段系统提示词、项目上下文或历史对话可能被当作普通输入反复计费。

建议按这个顺序排查：

1. 查看请求日志。OpenAI 模型关注 `cached_tokens`；Claude 模型关注是否有缓存创建和缓存读取字段。
2. 确认客户端是否原生支持 Claude prompt caching。只改 `base_url` 不一定能启用 Claude 缓存。
3. 把稳定内容放在提示词前缀，例如系统指令、项目规范、工具说明和不变的仓库上下文。
4. 把动态内容放在后面，例如用户本轮问题、临时文件片段和本轮工具结果。
5. 如果通过 OpenAI 兼容网关调用 Claude，请确认网关是否支持透传或生成 `cache_control`。
6. 大上下文编程任务建议使用单独 API Key，并在控制台核对 Token 组的缓存策略、模型权限和实际扣费。

<Note>
  OpenAI、Anthropic、客户端工具和网关实现都可能更新。正式使用前，请以控制台日志、当前客户端版本和官方缓存文档为准。
</Note>

## 密码重置链接无法访问怎么办？

如果邮件中的重置链接只有相对路径，例如 `/user/reset?...`，请在前面补上控制台域名：

```text theme={null}
https://api.aiearth.dev/user/reset?email=your-email@example.com&token=your-reset-token
```

不要把真实邮箱和重置 token 发到公开渠道。

## 为什么 GPT-4 类模型说自己是 GPT-3？

模型的自我描述不一定可靠。它可能沿用训练语料中的旧身份描述，也可能被客户端提示词影响。判断模型是否生效时，优先看控制台模型配置、请求日志和实际能力测试。

如果你需要验证模型，可以使用几类测试问题：

* 常识纠错，例如“鲁迅和周树人是什么关系？”
* 多步推理，例如时间关系、数量变化和条件推断。
* 业务样例，例如让模型处理你真实场景中的代码、论文段落或结构化输出。

## 是否支持余额查询和实时语音？

官网说明余额查询和实时语音 API 使用 `api-s1.aiearth.dev` 或 `api-s1.aiearth.vip` 相关端点。具体路径和参数请以控制台及开发者指南为准。

## 免费体验是否等于免费 API？

不是。平台可能提供免费聊天或学术智能体体验入口，但这不代表 API 调用免费。API 调用仍以账户余额、令牌额度和控制台费率为准。

## 如何获得技术支持？

你可以通过官网、控制台、开发者指南和服务社区获取支持。官网首页展示的支持入口包括 CSDN 企业社区、Link3 Link Hub、QQ 技术支持群和微信咨询。企业用户可联系官方展示的客服渠道咨询批量接入、资源包和售后方案。

## QQ 群和微信信息可以直接写进代码吗？

不要。QQ 群、微信、商城商品和企业服务政策都可能变化。建议在文档里说明入口和用途，具体联系方式以官网首页最新展示为准。

## 如何判断是平台问题还是本地配置问题？

先按这个顺序排查：

1. 查看 [服务状态与支持](/service-status) 中的官网和控制台入口。
2. 检查控制台余额和令牌额度。
3. 检查 Key 分组是否支持目标模型。
4. 检查客户端端点和 `/v1` 路径。
5. 换网络或代理环境重试。
6. 携带请求时间、模型名、端点、错误码和请求 ID 联系支持。