OPENSHUNT DOCS / START

使用教程

从本地环境到 AI 编程工具，按照步骤接入 OpenShunt 统一 API 网关。只需一枚 Key，即可开始调用主流模型。

API 接口地址https://api.novarelay.cn/v1

获取 API Key →预计 10 分钟完成

准备 OpenShunt 账号登录 sub2api 控制台

创建 API Key请妥善保管

选择接入方式按章节完成 SDK 或工具配置

环境准备 · 01 / PREPARATION

Node.js 环境安装

Claude Code、Codex 和 Gemini CLI 都可以通过 npm 安装。建议使用 Node.js 20 LTS 或更高版本。

第一步

安装 Node.js

选择与你的操作系统匹配的 LTS 版本。安装完成后重新打开终端，让环境变量生效。

下载 Node.js LTS →

第二步

验证安装

两条命令都能输出版本号即可继续，建议 Node.js 版本为 v20 或更高。

TERMINAL

node -v
npm -v

02 / API KEY

创建密钥时设置访问边界

在创建 API 密钥时配置用量上限、有效期和访问限制，让每个项目从第一次调用起就保持清晰的安全边界。

第一步

打开密钥设置

进入 OpenShunt 控制台的「密钥管理」，点击“创建密钥”。填写便于识别的名称，并在提交前完成可用选项设置。

登录控制台 →

按使用目标配置三项能力

USAGE LIMIT

用量上限

按项目设置可接受的调用额度，达到上限后停止继续消费。

EXPIRATION

有效期

临时测试使用短期 Key，生产密钥也应按周期轮换。

ACCESS CONTROL

访问限制

可用时绑定来源 IP 或项目权限，缩小密钥泄露后的影响范围。

推荐组合

先设置可接受的用量上限，再配置有效期与访问限制。不要把 Key 写入前端代码、截图、日志或公开仓库。

03 / OPENAI SDK

接入 OpenAI 兼容接口

现有 OpenAI SDK 通常只需替换 API Key 和 Base URL，无需重写业务调用逻辑。

CURL

curl https://api.novarelay.cn/v1/chat/completions \
  -H "Authorization: Bearer nr_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"你好"}]}'

PYTHON

from openai import OpenAI

client = OpenAI(
    api_key="nr_live_xxx",
    base_url="https://api.novarelay.cn/v1",
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "你好"}],
)

print(response.choices[0].message.content)

04 / CLAUDE CODE

配置 Claude Code

安装 Claude Code 后，将认证令牌与请求地址指向 OpenShunt。

第一步

安装命令行工具

NPM

npm install -g @anthropic-ai/claude-code
claude --version

第二步

写入用户配置

将以下内容保存到 ~/.claude/settings.json，并替换示例密钥。

JSON

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.novarelay.cn",
    "ANTHROPIC_AUTH_TOKEN": "nr_live_xxx"
  }
}

05 / CODEX

配置 Codex CLI

通过自定义模型提供商使用 OpenAI 兼容端点，配置保存在用户目录中。

第一步

安装 Codex

NPM

npm install -g @openai/codex@latest
codex --version

第二步

添加模型提供商

编辑 ~/.codex/config.toml。模型名称以控制台当前支持列表为准。

TOML

model = "gpt-4o"
model_provider = "openshunt"

[model_providers.openshunt]
name = "OpenShunt"
base_url = "https://api.novarelay.cn/v1"
wire_api = "responses"
requires_openai_auth = true

第三步

修改凭据文件

将以下内容保存到 ~/.codex/auth.json，并替换示例密钥。

JSON

{
  "OPENAI_API_KEY": "nr_live_xxx",
  "auth_mode": "apikey"
}

保护配置文件

本地配置可能包含明文 Key，请限制文件权限并排除版本控制。

AI 编程工具 · 06 / GEMINI CLI

Gemini CLI 配置教程

使用 API Key 鉴权模式，将 Gemini CLI 的请求转发到 OpenShunt 兼容网关。

第一步

安装 Gemini CLI

NPM

npm install -g @google/gemini-cli
gemini --version

第二步

写入用户配置文件

将以下内容保存到 ~/.gemini/.env。使用前请确认控制台已提供 Gemini 兼容端点与模型。

ENV

GEMINI_API_KEY=nr_live_xxx
GOOGLE_GEMINI_BASE_URL=https://api.novarelay.cn
GEMINI_MODEL=gemini-2.5-pro

第三步

开始使用

在项目目录运行 gemini，首次启动时选择 API Key 鉴权方式。

07 / TROUBLESHOOTING

常见问题排查

返回 401 或 403

确认 Authorization 使用 Bearer 格式、Key 未被停用，并检查密钥权限或来源限制。

请求成功但模型不可用

确认模型名称与控制台一致。不同兼容客户端可能需要使用对应的模型别名。

请求超时或频繁失败

先查看控制台请求日志，确认错误来自本地网络、参数格式还是上游服务；保留请求 ID 便于技术支持定位。

READY TO BUILD

配置完成，开始构建

在控制台管理 API Key、用量和请求日志。

进入后台 →