企业官网建设流程全解析

AIRI 接入 OpenRouter 意识模型：从 API Key 配置到自动校验的完整实战指南

【免费下载链接】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

本文以 AIRI 官方文档 docs/content/ko/docs/manual/config/providers/consciousness/openrouter.md（及英文版 docs/content/en/docs/manual/config/providers/consciousness/openrouter.md）为主体，结合@proj-airi/stage-ui的提供者注册表与校验器源码，完整讲解如何将 OpenRouter 配置为 AIRI"意识"（Consciousness）模块的聊天提供者。读完本文你将掌握 API Key 的获取与安全规范、AIRI 设置界面中的完整配置流程、配置自动校验（Ping API）的底层实现原理，以及常见故障的排查思路。

OpenRouter 是什么：为什么要用它

OpenRouter 是一个聚合式 API 服务提供者：它把多家模型厂商（OpenAI、Google、Anthropic、DeepSeek 等）的模型统一收敛到同一套 API 接口、同一个计费账户之下。对于 AIRI 用户而言，这意味着：

• 一个 API Key 即可访问多个模型厂商，无需为每个上游提供者单独注册账户、单独配置；
• 可以在 OpenRouter 暴露的模型之间自由切换（例如从openai/gpt-*切到google/gemini-*），而无需改动 AIRI 中的提供者配置；
• 可用性仍取决于你的地区、网络、支付方式以及上游提供者政策，配置前应确认所在环境能否正常访问。

官方文档在"为什么选择 OpenRouter"一节的说明（见 docs/content/ko/docs/manual/config/providers/consciousness/openrouter.md）与本仓库实现完全一致：OpenRouter 在 AIRI 中的定位是一个标准、多模型、单一凭证的云端聊天提供者（其目录属性为paid云服务，见 packages/stage-ui/src/libs/providers/attributes.ts）。

第一步：获取 OpenRouter API Key

创建密钥

1. 打开 OpenRouter 的 API Keys 页面，点击创建新 API Key；
2. 为密钥设置合适的名称、有效期与额度（quota）限制——建议按实际使用量设置额度，防止密钥被盗用后产生超额费用；
3. 复制密钥并保存在安全的地方（密码管理器优先）。

安全红线

官方文档明确警告（见英文版 docs/content/en/docs/manual/config/providers/consciousness/openrouter.md）：

• 不要把 API Key 提交到 Git 仓库、包含在截图里，或分享给任何人；
• 一旦密钥疑似泄露，立即在 OpenRouter 控制台撤销该密钥并创建新密钥。

这一点在源码中也有呼应：OpenRouter 提供者的配置模式里apiKey字段在 UI 层被标记为type: 'password'（见 packages/stage-ui/src/libs/providers/providers/openrouter-ai/index.ts），确保输入框以密文形式呈现。

第二步：在 AIRI 中配置 OpenRouter

设置界面操作路径

1. 打开设置 → 服务商（提供者）→ 聊天 → OpenRouter；
2. 在基础设置中粘贴 API Key；
3. 保留默认 Base URL：https://openrouter.ai/api/v1/。

源码中的默认配置

在源码中，OpenRouter 提供者（providerOpenRouterAI，id 为openrouter-ai）的配置 Schema 定义如下（见 packages/stage-ui/src/libs/providers/providers/openrouter-ai/index.ts）：

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

要点解读：

也就是说，即使你在界面中完全不填写 Base URL，AIRI 也会自动使用默认的 OpenRouter 端点；只有在需要走代理或自定义中转时才有必要修改它（通用聊天提供者设置说明可参考 docs/content/ko/docs/manual/config/llm.md）。

自动附加的来源标识请求头

AIRI 在向 OpenRouter 发起请求时，会自动附加两个来源标识（attribution）请求头（见 packages/stage-ui/src/libs/providers/providers/openrouter-ai/index.ts）：

export const OPENROUTER_ATTRIBUTION_HEADERS: Record<string, string> = { 'HTTP-Referer': 'https://airi.moeru.ai/', 'X-OpenRouter-Title': 'Project AIRI', }

这两个头通过包装fetch注入到每一次聊天请求中（index.ts），用于向 OpenRouter 标识流量来源应用，属于 OpenRouter 推荐的接入实践。

推理（Reasoning）模式映射

OpenRouter 提供者声明了聊天推理能力：capabilities: { chat: { reasoning: { modes: ['enabled', 'disabled'] } } }（index.ts）。当你在 AIRI 中为意识模块开启/关闭推理时，源码会把两种模式映射为 OpenRouter 的reasoning.effort参数：

• enabled→reasoning: { effort: 'medium' }
• disabled→reasoning: { effort: 'none' }

该映射行为有专门的单元测试覆盖（packages/stage-ui/src/libs/providers/providers/openrouter-ai/index.test.ts），测试同时验证了工具调用场景下 JSON Schema 请求体的正确性（index.test.ts），说明该提供者完整支持 AIRI 的函数调用（工具）协议。

第三步：验证配置

配置完成后，通过两步确认 OpenRouter 已经可用：

1. 设置有效性验证（Validate configuration）：AIRI 会在你编辑配置的同时自动进行校验；当界面出现Ping API按钮时，可以用它对 OpenRouter 发起一次真实请求测试连通性；
2. 选择模型（Select Model →）：校验通过后，点击该按钮跳转到设置 → 模块 → 意识（Consciousness），从加载出的模型列表中选择一个可用的 OpenRouter 模型（例如openai/gpt-*、google/gemini-*等以厂商前缀命名的模型 ID）。

校验机制的源码实现

OpenRouter 提供者复用了 OpenAI 兼容提供者的校验器工厂createOpenAICompatibleValidators，并启用了三类运行时检查（见 packages/stage-ui/src/libs/providers/providers/openrouter-ai/index.ts）：

validators: { ...createOpenAICompatibleValidators({ checks: [ProviderValidationCheck.Connectivity, ProviderValidationCheck.ModelList, ProviderValidationCheck.ChatCompletions], additionalHeaders: OPENROUTER_ATTRIBUTION_HEADERS, }), },

结合 packages/stage-ui/src/libs/providers/types.ts 中的枚举定义与 packages/stage-ui/src/libs/providers/validators/openai-compatible.ts 的实现，三层校验的实际行为如下：

值得注意的是聊天补全探测中的细节：AIRI 会发送max_tokens: 16的最小输出上限——源码注释明确指出，OpenRouter 文档对部分上游提供者规定了 16 token 的输出下限，低于该值会被拒绝（openai-compatible.ts）。这解释了为什么校验请求能覆盖尽可能多的模型。另外，只有当apiKey非空时 AIRI 才触发自动校验（validationRequiredWhen，见 index.ts）。

第四步：在"意识"模块中选择模型

校验通过后，进入设置 → 模块 → 意识：

• 选择此前配置的OpenRouter提供者；
• 在模型下拉列表中选择目标模型。若 AIRI 成功从 OpenRouter 拉取模型列表，这里会展示可用模型（如openai/gpt-*、google/gemini-*、anthropic/claude-*等）；
• 若列表为空或加载失败，可直接在输入框中手动输入OpenRouter 提供的精确模型 ID。

根据 docs/content/ko/docs/manual/config/llm.md 的补充说明，保存提供者凭证并不会自动激活该提供者——你仍需在意识页面明确选中提供者与模型，然后回到聊天界面发送一条Hello之类的短消息做最终验证；能收到回复即代表链路完全打通。

问题排查

官方文档给出的排查要点如下，结合源码可进一步定位：

1. API 校验失败（Ping API 报错）：依次检查
   • API Key 是否正确、是否包含多余空格（源码中validationRequiredWhen会对 key 做trim()后判断，index.ts）；
   • 账户是否有可用额度（credit）或 quota 是否已耗尽；
   • 是否触发了 OpenRouter 或上游的速率限制（rate limit）；
   • 网络连接是否可达https://openrouter.ai/api/v1/（连通性检查带 10 秒超时，见 openai-compatible.ts）。
2. 模型列表无法加载：部分模型或账号权限可能不返回列表，此时在设置 → 模块 → 意识页面手动输入 OpenRouter 官方文档中给出的精确模型 ID（注意大小写与厂商前缀，如openai/gpt-4o，须与 OpenRouter 返回的 ID 完全一致）。
3. 配置已保存但仍无响应：回到意识模块确认提供者与模型均已选中——凭证保存 ≠ 提供者激活。

相关文档与源码

• 官方配置文档（多语言）：中文版、韩文版、英文版
• 通用聊天模型设置：docs/content/ko/docs/manual/config/llm.md（含提供者选择建议、Base URL 修改时机、故障排查）
• 提供者定义源码：packages/stage-ui/src/libs/providers/providers/openrouter-ai/index.ts
• 提供者单元测试：packages/stage-ui/src/libs/providers/providers/openrouter-ai/index.test.ts
• OpenAI 兼容校验器实现：packages/stage-ui/src/libs/providers/validators/openai-compatible.ts
• 校验检查项与提供者类型定义：packages/stage-ui/src/libs/providers/types.ts
• 提供者目录属性（OpenRouter 为云端付费服务）：packages/stage-ui/src/libs/providers/attributes.ts

【免费下载链接】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