Add Nexus to my product

Goal

从一个空 Workspace 开始，让一名真实应用用户通过 Nexus Gateway 完成请求，并在 Console 中看到该用户、ProviderConnection、Quota 和 Usage 的归因。

Outcome

完成后，你的应用后端保留 Nexus 管理权限；应用用户只收到一个带有不可变 providerConnectionId UUID 的 Gateway Base URL 和一次性展示的 Nexus Inference Key。

Who this is for

负责接入 Nexus、管理 Provider 凭证并把 AI 能力分配给应用用户的平台开发者。

Prerequisites

• 一个可登录的 Nexus Console 和可创建 Workspace 的 Organization。
• 目标 Provider 的上游 Base URL、Provider Key，以及该 Provider 接受的原始模型名。
• 应用中的稳定用户 ID 和邮箱。
• 本地 Node.js 22.12+；示例使用 E2E 锁定的 OpenAI JavaScript SDK。

1. Create a Workspace

在 Console 打开 Workspaces，填写名称和小写 kebab-case Slug，然后选择 Create Workspace。Workspace 是 ProviderConnection、Plan、Access、Quota 和 Usage 的隔离边界。

2. Connect your provider

进入 Workspace 的 Providers 页面，选择 Connect provider：

1. 选择与上游协议一致的 Adapter。
2. 确认连接名称和上游 Base URL。
3. 输入 Provider Key 并创建连接。
4. 选择 Verify，确认 Nexus 能用已加密保存的凭证访问上游。
5. 复制 Console 展示的 Gateway Base URL。URL 中的最后一个路径段是服务生成、不可变的 providerConnectionId UUID。

客户端不能提交上游 Host；Gateway 只按 (workspaceId, providerConnectionId) 查找已保存的连接。

3. Create a Plan

进入 Plans 并创建一个 Plan + QuotaStrategy。填写 Plan 名称、稳定 Key、重置周期、Quota Units、输入/输出倍率和最大输出 Token。Console 会按已接受的管理流程创建 Plan 与策略、发布策略、绑定策略并发布 Plan。

首次验证可以使用一组足够完成单次请求的本地测试值；Quota Unit 是 AI 使用权，不是货币余额。

4. Provision a user

进入 Users，选择 Provision user，填写应用的 externalUserId、邮箱、可选姓名并选择刚发布的 Plan。选择 Provision User + Inference Key。

立即安全保存一次性展示的 Inference Key。关闭对话框后不能再次读取明文；丢失时应签发新 Key，而不是查询旧值。

5. Call a model

安装与 E2E 相同的 SDK 版本：

npm install openai@6.48.0

下面的环境值来自公开 Fake Provider 兼容性 Fixture。把 Base URL 替换为 Console 复制的值，把 Key 占位符替换为刚签发的 Inference Key，并使用所选 Provider 接受的原始模型名。

export NEXUS_BASE_URL="https://gateway.nexus.microvoid.io/providers/00000000-0000-0000-0000-000000000141"
export NEXUS_API_KEY="<NEXUS_INFERENCE_KEY>"
export NEXUS_MODEL="provider/opaque-model-v9"

保存并运行 E2E 实际执行的示例：

import OpenAI from 'openai';

function requiredEnvironment(name) {
  const value = process.env[name]?.trim();
  if (!value) throw new Error(`${name} is required`);
  return value;
}

const client = new OpenAI({
  baseURL: requiredEnvironment('NEXUS_BASE_URL'),
  apiKey: requiredEnvironment('NEXUS_API_KEY'),
  maxRetries: 0,
});

const completion = await client.chat.completions.create({
  model: requiredEnvironment('NEXUS_MODEL'),
  messages: [{ role: 'user', content: 'Keep this request unchanged.' }],
  temperature: 0.37,
});

console.log(
  JSON.stringify({
    model: completion.model,
    content: completion.choices[0]?.message.content,
  }),
);

node openai-javascript.mjs

Nexus 不改写 model 或 Provider Payload。显式选择另一条 ProviderConnection 时，必须改用该 Provider 接受的模型名。

6. Verify usage

回到同一 Workspace：

1. Usage 应显示所选 ProviderConnection、请求模型、WorkspaceAccess、Token、Quota Units、状态和 Request ID。
2. Activity → Logs 应把请求归因到 Provision 的 externalUserId。
3. Activity → Audit 应保留管理面操作，而不包含 Provider Key 或 Inference Key 明文。

Check your work

What Nexus stored

Workspace 边界、加密 Provider Secret、不可变 ProviderConnection ID、WorkspacePlan/QuotaStrategy、WorkspaceAccess、Key Binding、QuotaPeriod，以及请求后的 Invocation、UsageEvent 和 Audit 事实。

What the user received

一个 Gateway Base URL、一次性 Inference Key 和所选 Provider 接受的原始模型名。用户没有得到 Provider Key、Management Key 或任意上游 Host 的选择权。

Troubleshooting

Next steps

• 把 Use my Nexus access 交给应用用户。
• 比较 JavaScript、Python 和 OpenCode 的受测接入方式。
• 在轮换前复核 Credential model。