ApiFluxAI | ApiFlux 常见问题

排查 ApiFlux API Key、Base URL、Codex CLI、Claude Code 与 OpenCode 的常见问题。

本文整理 ApiFlux 用户在创建 API Key、设置 Base URL、连接 Codex CLI、Claude Code 和 OpenCode 时常见的问题。

Q1：官网地址和 API Base URL 有什么区别？

官网入口用于登录、创建 API Key、查看模型、查看余额和查看记录：

https://apiflux.ai/

API Base URL 用于设置工具或 SDK：

https://apiflux.ai/v1

大多数 OpenAI-compatible 工具应填写 https://apiflux.ai/v1。

Claude Code 使用网关环境变量时，可以先尝试：

https://apiflux.ai

如果出现路径相关错误，再尝试：

https://apiflux.ai/v1

Q2：API Key 泄露了怎么办？

请立即执行以下操作：

登录 ApiFlux 控制台
进入 API Keys
删除泄露的 API Key
建立新的 API Key
更新本地工具或应用中的设置

泄露过的 API Key 不建议继续使用。

Q3：为什么会报 401 或 Unauthorized？

常见原因包括：

API Key 填写错误
API Key 已被删除或失效
复制 API Key 时包含多余空格
当前终端没有加载环境变量
工具读取到了旧的 API Key

OpenCode 或 Codex CLI 用户可检查。

Windows PowerShell：

echo $env:APIFLUX_API_KEY

macOS / Linux：

echo $APIFLUX_API_KEY

Claude Code 用户可检查。

Windows PowerShell：

echo $env:ANTHROPIC_API_KEY

macOS / Linux：

echo $ANTHROPIC_API_KEY

如果没有输出，请重新配置环境变量。

Q4：为什么提示余额不足？

通常是 ApiFlux 账户余额不足，或目前 API Key 所属账户没有可用额度。

处理方式：

打开 ApiFlux Dashboard
查看 Current balance
如果余额不足，点击 Recharge
充值后重新发起请求

Q5：为什么提示模型不存在？

多数情况是模型 ID 填写错误。

请打开 ApiFlux Models 页面，复制模型详情中展示的 interface model ID。不要使用模型展示名称，也不要手动猜测模型 ID。

错误示例：

Claude Sonnet
GPT 4o
Gemini Pro

正确做法是复制 ApiFlux Models 页面展示的完整模型 ID。

Q6：请求成功了，但 Logs 中没有记录怎么办？

请依次检查：

当前登录的 ApiFlux 账号是否正确
工具是否设置了 ApiFlux Base URL
工具是否使用了 ApiFlux API Key
请求是否可能发送到了其他服务商
Logs 页面是否需要重新整理
是否选错了时间范围

如果工具可以回复，但 ApiFlux Logs 中完全没有记录，通常说明请求没有经过 ApiFlux。

Q7：Codex CLI、Claude Code、OpenCode 应该使用哪种界面？

Codex CLI 建议使用自定义 model provider，设置 ApiFlux Base URL：

https://apiflux.ai/v1

OpenCode 建议使用 OpenAI-compatible custom provider：

https://apiflux.ai/v1

Claude Code 建议使用 Anthropic-compatible 网关环境变量：

ANTHROPIC_BASE_URL
ANTHROPIC_API_KEY
DISABLE_INTERLEAVED_THINKING
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS

配置完成后，可通过 ApiFlux Logs 验证请求是否成功到达 ApiFlux。

Q8：一个 API Key 可以给多个工具共用吗？

可以，但正式使用时建议按工具或环境拆分。

例如：

codex-cli-key
claude-code-key
opencode-key
production-app-key

这样做有三个好处：

更容易定位用量来源
更容易排查异常请求
某个 Key 泄露时只影响对应工具或环境

Q9：如何更换模型？

先到 ApiFlux Models 页面复制新的模型 ID。

Codex CLI 用户修改：

model = "YOUR_NEW_MODEL_ID"

OpenCode 用户修改：

"models": {
  "YOUR_NEW_MODEL_ID": {}
}

Claude Code 用户如果支持启动参数，可以使用：

claude --model "YOUR_NEW_MODEL_ID"

修改后重新启动工具，并前往 ApiFlux Logs 确认请求记录。

Q10：如何安全处理截图和屏幕录屏？

公开截图或屏幕录屏前，请确认没有展示以下内容：

完整 API Key
包含真实 Key 的环境变量
包含真实 Key 的配置文件
敏感 prompt
私密记录内容

推荐打码方式：

sk-****abcd

最多保留前 3 到 4 位和后 3 到 4 位，不要展示完整 Key。

Q11：Base URL 后面到底要不要加 `/v1`？

大多数 OpenAI-compatible 工具和 SDK 应填写：

https://apiflux.ai/v1

Claude Code 的 ANTHROPIC_BASE_URL 可以先填写：

https://apiflux.ai

如果出现路径相关错误，再尝试：

https://apiflux.ai/v1

判断标准是：工具可以正常回复，并且 ApiFlux Logs 中出现对应请求。

Q12：如何确认请求真的经过 ApiFlux？

发起一次简单请求，然后打开 ApiFlux 控制台的 Logs。

如果 Logs 中出现该请求，说明工具已经经过 ApiFlux。

如果工具有回复但 Logs 中没有记录，请检查 Base URL、API Key 和当前登录账号。

Q13：Claude Code 报 invalid beta flag 怎么办？

这是 Claude Code 连接第三方网关时可能出现的 beta header 兼容问题。

启动 Claude Code 前，请配置：

Windows PowerShell：

$env:DISABLE_INTERLEAVED_THINKING="1"
$env:CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS="1"

macOS / Linux：

export DISABLE_INTERLEAVED_THINKING=1
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

然后重新执行：

claude --model "YOUR_MODEL_ID"

Q14：OpenCode 报 fn3 is not a function 怎么办？

该错误通常来自 OpenCode 插件异常，不代表 ApiFlux API Key 或 Base URL 配置错误。

可以打开：

~/.config/opencode/opencode.json

将 plugin 临时配置为空数组：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": []
}

确认 OpenCode 能正常启动后，再逐个恢复插件。

Q15：OpenCode 报 function tools 或 reasoning_effort 不支持怎么办？

说明目前模型不适合 OpenCode 的工具调用请求。

可以尝试更适合编码工具调用的模型，例如：

deepseek-v4-pro
qwen3.7-plus
glm-5.2

Q16：Windows 和 macOS / Linux 的命令为什么不一样？

主要区别在环境变量写法。

Windows PowerShell 使用：

$env:APIFLUX_API_KEY="YOUR_APIFLUX_API_KEY"

macOS / Linux 使用：

export APIFLUX_API_KEY="YOUR_APIFLUX_API_KEY"

如果用户复制了不属于自己系统的命令，通常不会损坏电脑，只是命令不会生效。请回到对应系统的小节重新复制。

Q17：提示 command not found 或「不是内部或外部命令」怎么办？

这通常说明工具没有安装成功，或安装目录没有加入 PATH。

处理方式：

关闭终端并重新打开
执行版本检查命令，例如 node -v、codex --version、claude --version、opencode --version
如果仍然失败，重新执行对应工具的安装命令
Windows 用户如果使用 npm 安装，请先确认 npm -v 能正常输出版本号

Q18：npm command not found 怎么办？

说明本机还没有安装 Node.js，或安装后终端没有重新打开。

请前往 Node.js 官网安装 LTS 版本：

https://nodejs.org/

安装完成后，关闭终端并重新打开，再执行：

node -v
npm -v

Windows PowerShell 也可以执行同样的版本检查命令。

Q19：环境变量是暂时的还是永久的？

直接在终端中执行的环境变量通常只对当前窗口有效。

Windows PowerShell 暂时写法：

$env:APIFLUX_API_KEY="YOUR_APIFLUX_API_KEY"

Windows PowerShell 长期写法：

[Environment]::SetEnvironmentVariable("APIFLUX_API_KEY","YOUR_APIFLUX_API_KEY","User")

macOS / Linux 暂时写法：

export APIFLUX_API_KEY="YOUR_APIFLUX_API_KEY"

macOS 长期写法通常写入 ~/.zshrc，Linux 长期写法通常写入 ~/.bashrc。

Q20：Windows 用户一定要安装 WSL 吗？

不一定。

如果只是跟着指南设置工具，PowerShell 通常已经够用。

如果用户经常做开发、需要执行 Linux 命令，或者某些工具在 Windows 原生环境里表现不稳定，可以考虑使用 WSL。使用 WSL 时，请在 WSL 终端里按照 Linux 命令操作。