使用教程

从这里，接入你的工具

准备地址、Key 和模型，跟着步骤完成配置。

Codex 最小请求 401 / 429

从账户到第一条请求

当前为预生产环境，真实线路与支付尚未开放。以下操作可用于熟悉界面，调用需等待可用线路和测试额度。

注册领测试额度

注册账户，已有账户可直接登录；登录后先确认测试额度已经到账。

创建 API Key

打开API 密钥，选择“创建 API 密钥”。填写名称、可用分组、有效期和配额后保存。复制 Key 并妥善保存。

复制配置开始使用

从控制台概览复制接入地址，到模型目录选择已开放的模型。发送一条短请求后，在使用日志核对请求，并到钱包查看余额变化。

接入前，准备这三项

Base URL: 从控制台复制。OpenAI 兼容工具一般填写到 /v1，避免重复拼接。
API Key: 使用折光控制台创建的 Key。不要发送给他人或放入公开仓库。
模型 ID: 按可用目录原样填写，包含大小写和后缀。

以下 https://YOUR_GATEWAY、YOUR_API_KEY、YOUR_MODEL_ID 都需要替换。本机测试地址为 http://127.0.0.1:18080；手机上的 127.0.0.1 指向手机自身。

发送一个最小请求

以下示例使用 OpenAI 兼容的 Chat Completions 接口。先从模型目录确认可用模型，再替换配置模板，替换后执行会产生请求；当前环境仅用于经安排的测试。

curl https://YOUR_GATEWAY/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_MODEL_ID","messages":[{"role":"user","content":"Reply with OK"}],"max_tokens":64}'

$headers = @{ Authorization = "Bearer YOUR_API_KEY" }
$body = @{ model = "YOUR_MODEL_ID"; messages = @(@{ role = "user"; content = "Reply with OK" }); max_tokens = 64 } | ConvertTo-Json
Invoke-RestMethod -Uri "https://YOUR_GATEWAY/v1/chat/completions" -Method Post -Headers $headers -ContentType "application/json" -Body $body

收到正常回复后，再到使用日志核对。若失败，先查看错误排查，不要连续重试。

选择你的工具

按顺序提供 Codex、Claude Code、Hermes Agent、OpenCode 配置。以下依据官方文档整理于 2026-09-04，本站真实线路兼容性仍待实测。

Codex

通过官方安装页选择 Windows、macOS 或 Linux 的安装方式，安装后在项目目录运行 codex。

先备份已有配置，再将以下内容合并到用户目录的 ~/.codex/config.toml（Windows 为 %USERPROFILE%\.codex\config.toml），保留自己的其他设置。

model = "YOUR_MODEL_ID"
model_provider = "refra"

[model_providers.refra]
name = "折光 REFRA"
base_url = "https://YOUR_GATEWAY/v1"
wire_api = "responses"
env_key = "REFRA_API_KEY"

在同一终端设置 Key，然后启动：

export REFRA_API_KEY="YOUR_API_KEY"
codex

$env:REFRA_API_KEY="YOUR_API_KEY"
codex

使用支持 Responses 的模型。官方自定义提供商配置。

Claude Code

先从官方安装页安装客户端。Windows 可使用 winget install Anthropic.ClaudeCode；macOS / Linux 可按官方脚本安装。

需要已开放的 Anthropic Messages 兼容线路；当前目录中的测试模型不能视为 Claude Code 可用线路。接入地址填写网关根地址，模型使用该线路确认的 ID。

export ANTHROPIC_BASE_URL="https://YOUR_GATEWAY"
export ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY"
claude --model YOUR_MODEL_ID

$env:ANTHROPIC_BASE_URL="https://YOUR_GATEWAY"
$env:ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY"
claude --model YOUR_MODEL_ID

从干净终端开始，避免与已有 Anthropic 凭据混用。官方网关说明。

Hermes Agent

在官方安装页选择 Windows 或 macOS 安装器；Linux 和 WSL 也可按官方终端方式安装。

hermes model

选择 Custom endpoint。
Base URL 填写 https://YOUR_GATEWAY/v1。
填写折光 API Key 和完整模型 ID。
保存后运行 hermes，发送一句短文本测试。

需要 Chat Completions 兼容模型。官方提供商配置。

OpenCode

按官方安装教程选择系统。已安装 Node.js 时，Windows、macOS 和 Linux 可使用：

npm install -g opencode-ai
opencode

输入 /connect，选择 Other，提供商 ID 填 refra，再录入 API Key。将以下内容合并到项目的 opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "refra": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "折光 REFRA",
      "options": {
        "baseURL": "https://YOUR_GATEWAY/v1"
      },
      "models": {
        "YOUR_MODEL_ID": {
          "name": "YOUR_MODEL_ID"
        }
      }
    }
  }
}

输入 /models 选择模型。这份配置适用于官方当前文档的 provider 结构和 Chat Completions 接口；如使用不同大版本，请按对应版本文档配置。官方自定义提供商文档。

在哪里查看用量和余额

使用日志：按时间、模型或 Key 查找请求记录。钱包：查看账户余额。Key 配额是使用上限，不会增加账户余额。

如果客户端超时，先检查对应时间的日志再重试。需要帮助时保留请求时间、模型、错误码和 request_id；隐藏完整 Key。

遇到报错，先检查这里

401 · Key 无效+

重新复制 Key，检查前后空格、是否过期或已被撤销。

403 · 无权使用+

检查 Key 所属分组、模型权限以及客户端是否使用了正确账户。

404 · 地址或模型不存在+

检查 Base URL 是否重复 /v1，模型 ID 是否与目录一致。

429 · 请求受限+

暂停自动重试，降低请求频率，检查余额与配额，再按错误信息处理。

5xx / 超时 · 请求未完成+

先查看服务状态和使用日志。保留时间与 request_id，避免多次重复提交。

仍无法解决？查看常见问题。