在 AIRI 中配置 302.AI 聚合 API：从获取 API Key 到接入 Consciousness 的完整指南

在 AIRI 中配置 302.AI 聚合 API：从获取 API Key 到接入 Consciousness 的完整指南

【免费下载链接】airi💖🧸 Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi

302.AI 是一个 API 聚合服务商，通过一个 API Key 即可调用多种 LLM 模型。本文以 AIRI 项目中的官方配置文档为主线，结合仓库内的 provider 实现源码，完整讲解如何获取 302.AI 的 API Key、在 AIRI 的Settings → Providers → Chat中完成接入与自动校验，并将其模型挂载到Settings → Modules → Consciousness（意识）模块作为角色的大模型大脑，最后给出常见连接故障的排查路径。

读完本文，你将掌握：在 AIRI 中配置 OpenAI 兼容聚合服务商的标准流程、自动验证机制（Ping API / 模型列表 / Chat Completions）的底层原理，以及当校验失败或模型列表加载不出来时的处理方法。

为什么选择 302.AI：聚合 API 的适用场景

302.AI 属于 API 聚合提供商（API aggregation provider），核心价值在于"一把 Key 测多模型"：

• 它把多家上游模型厂商的接口聚合到统一的 OpenAI 兼容端点，配置完成后即可在 AIRI 的Settings → Modules → Consciousness下选择任意 302.AI 上架的 chat 模型。
• 如果你主要在中国大陆网络环境下使用 AIRI，可以先尝试 302.AI。官方文档同时提醒：实际可用性仍取决于你的网络环境、支付方式与服务商政策。

在 AIRI 的 provider 目录体系中，302.AI 被归类为付费云服务（paid + cloud）。这一点可以在 attributes.ts 中看到：'302-ai': paidCloud，即{ pricing: 'paid', deployment: 'cloud' }，因此在设置界面的 provider 来源筛选器中会出现在"付费 / 云端"分类下。

获取 API Key

1. 打开 302.AI Console（https://302.ai/），登录或注册账号。
2. 在控制台中创建 API Key。
3. 复制 Key 并妥善保存。

⚠️API Key 安全不要把 API Key 提交到代码仓库、截图分享或泄露给任何人。一旦 Key 疑似泄露，应立即在 302.AI 控制台吊销并重新生成。

在 AIRI 中配置 302.AI Provider

配置入口为Settings → Providers → Chat → 302.AI，只需两项配置：

配置项的源码视角

从源码看，302.AI provider 的配置结构由 zod schema 定义（302-ai/index.ts）：

const ai302ConfigSchema = z.object({ apiKey: z.string('API Key'), baseUrl: z .string('Base URL') .optional() .default('https://api.302.ai/v1/'), })

• apiKey为必填字符串，在设置表单中渲染为密码框（type: 'password'）；
• baseUrl可留空，默认值即官方文档中的https://api.302.ai/v1/。

provider 定义通过defineProvider注册到全局注册表（registry.ts），注册信息包括：

export const provider302AI = defineProvider<AI302Config>({ id: '302-ai', order: 7, name: '302.AI', tasks: ['chat'], icon: 'i-lobe-icons:ai302', ... })

tasks: ['chat']表明它作为 chat 类 provider 提供能力。真正发起请求时，createProvider会把配置合并为三种 provider 能力（302-ai/index.ts）：

createProvider(config) { return merge( createChatProvider({ apiKey: config.apiKey, baseURL: config.baseUrl! }), createEmbedProvider({ apiKey: config.apiKey, baseURL: config.baseUrl! }), createModelProvider({ apiKey: config.apiKey, baseURL: config.baseUrl! }), ) }

也就是说，302.AI 除了 chat 对话，还同时具备 Embedding（向量嵌入）与模型列表查询能力——这三者共用同一份 API Key 与 Base URL。

验证配置：AIRI 如何自动检查 302.AI

AIRI 会在你编辑配置时自动触发校验。302.AI 走的是 OpenAI 兼容验证器（createOpenAICompatibleValidators），并为它启用了两类检查（302-ai/index.ts）：

validationRequiredWhen(config) { return !!config.apiKey?.trim() }, validators: { ...createOpenAICompatibleValidators({ checks: [ProviderValidationCheck.ModelList, ProviderValidationCheck.ChatCompletions], }), },

validationRequiredWhen表示：只要填入了非空 API Key 就进入可验证状态。验证器实现在 validators/openai-compatible.ts，具体包含：

1. 配置合法性检查（check-config）：apiKey不能为空；baseUrl必须存在且是合法的绝对 URL（否则提示 "Base URL is invalid. It must be an absolute URL."）。
2. 连通性检查（check-connectivity）：对${baseUrl}/models发起带 10 秒超时（AbortController+setTimeout(…, 10_000)）的 GET 请求，携带Authorization: Bearer <apiKey>头，HTTP 5xx 或网络错误即判定失败。
3. Chat Completions 检查（check-chat-completions）：先拉取模型列表挑一个可用于验证的模型，然后用generateText发送内容为ping的探测请求（openai-compatible.ts）：

await generateText({ apiKey: config.apiKey, baseURL: config.baseUrl!, model: normalizedModel, messages: message.messages(message.user('ping')), ...(options?.chatCompletionTokenParameter === 'max_completion_tokens' ? { max_completion_tokens: 16 } : { max_tokens: 16 }), })

探测请求显式设置max_tokens: 16，这是为了兼容部分 OpenAI 兼容服务商不接受低于 16 的输出上限。该检查带缓存与互斥锁（Mutex），同一轮校验内重复的 chat 探测只会执行一次。 4.模型列表检查（check-model-list）：调用listModels拉取 302.AI 的模型列表，若列表为空则报 "no models found"。

这些检查在 UI 上对应着Ping API按钮与各检查项的实时状态。当校验通过后，provider 定义中的ProviderValidationCheck枚举（types.ts）对应的检查结果会逐项呈现——连通性、模型列表、Chat Completions 全部 green 即可继续选择模型。

选择模型：接入 Consciousness（意识）模块

验证成功后，点击Select Model →按钮会跳转到Settings → Modules → Consciousness页面，选择 provider（302.AI）和具体模型。Consciousness 模块承担角色的"人格与所选模型"职责，其界面文案定义在 i18n settings.yaml 中，关键交互包括：

• 模型下拉搜索：按关键词搜索模型（Search models...），显示Found {count} of {total} models，支持展开/收起全部模型；
• 手动输入模型名：当 provider 不支持模型列表、或列表加载失败时，可切换到Model Name输入框，直接填入 302.AI 提供的精确模型 ID（Enter the model name to use with this provider）；
• Thinking 选项：部分模型支持 Thinking（推理）模式的开关；
• 未配置提示：若没有任何 provider，页面会显示 "No Providers Configured"，引导你先回到 Providers 设置页完成 LLM provider 的配置。

故障排查

如果 API 检查失败，请按顺序排查：

1. API Key 是否正确：确认 Key 完整、无多余空格，且未过期/被吊销；
2. 账户余额是否充足：302.AI 为付费云服务（pricing: 'paid'），欠费会导致鉴权或请求失败；
3. 网络连接是否可达：确认你的网络环境能访问https://api.302.ai/（结合连通性检查对/models端点的 10 秒超时探测，网络不通会直接报网络错误）；
4. 模型列表加载失败：如果 AIRI 无法从 302.AI 拉取模型列表，可绕开列表查询，直接在Consciousness页面手动输入 302.AI 提供的精确模型 ID（对应 i18n 中的manual_model_placeholder: Enter the model name to use with this provider）。注意确保模型 ID 拼写与 302.AI 控制台 / 官方模型文档完全一致。

小结

302.AI 是 AIRI 在中国大陆网络环境下快速上手多模型的一个务实选择。整个接入流程可以归纳为三步：控制台获取 Key → Settings → Providers 填入 Key 并保持默认 Base URL → 验证通过后在 Consciousness 模块选择模型。AIRI 的 OpenAI 兼容验证器会以/models连通性探测、模型列表拉取和ping对话探测三层检查替你确认配置有效性；即使模型列表接口异常，手动输入模型 ID 也能让 302.AI 正常工作。

【免费下载链接】airi💖🧸 Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi