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-samas 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创建密钥打开 OpenRouter 的 API Keys 页面点击创建新 API Key为密钥设置合适的名称、有效期与额度quota限制——建议按实际使用量设置额度防止密钥被盗用后产生超额费用复制密钥并保存在安全的地方密码管理器优先。安全红线官方文档明确警告见英文版 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设置界面操作路径打开设置 → 服务商提供者→ 聊天 → OpenRouter在基础设置中粘贴 API Key保留默认 Base URLhttps://openrouter.ai/api/v1/。源码中的默认配置在源码中OpenRouter 提供者providerOpenRouterAIid 为openrouter-ai的配置 Schema 定义如下见 packages/stage-ui/src/libs/providers/providers/openrouter-ai/index.tsconst openRouterConfigSchema z.object({ apiKey: z.string(API Key), baseUrl: z .string(Base URL) .optional() .default(https://openrouter.ai/api/v1/), })要点解读配置项是否必填默认值说明apiKey是无OpenRouter API KeyUI 中以密码类型输入框呈现baseUrl否https://openrouter.ai/api/v1/接口地址通常保持默认即可也就是说即使你在界面中完全不填写 Base URLAIRI 也会自动使用默认的 OpenRouter 端点只有在需要走代理或自定义中转时才有必要修改它通用聊天提供者设置说明可参考 docs/content/ko/docs/manual/config/llm.md。自动附加的来源标识请求头AIRI 在向 OpenRouter 发起请求时会自动附加两个来源标识attribution请求头见 packages/stage-ui/src/libs/providers/providers/openrouter-ai/index.tsexport const OPENROUTER_ATTRIBUTION_HEADERS: Recordstring, 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 已经可用设置有效性验证Validate configurationAIRI 会在你编辑配置的同时自动进行校验当界面出现Ping API按钮时可以用它对 OpenRouter 发起一次真实请求测试连通性选择模型Select Model →校验通过后点击该按钮跳转到设置 → 模块 → 意识Consciousness从加载出的模型列表中选择一个可用的 OpenRouter 模型例如openai/gpt-*、google/gemini-*等以厂商前缀命名的模型 ID。校验机制的源码实现OpenRouter 提供者复用了 OpenAI 兼容提供者的校验器工厂createOpenAICompatibleValidators并启用了三类运行时检查见 packages/stage-ui/src/libs/providers/providers/openrouter-ai/index.tsvalidators: { ...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 的实现三层校验的实际行为如下校验项校验器 ID底层动作配置合法性openai-compatible:check-config检查 apiKey 非空、baseUrl 非空且为合法绝对 URLopenai-compatible.ts连通性openai-compatible:check-connectivity携带Authorization: Bearer apiKey与来源标识头对{baseUrl}/models发起 GET 请求10 秒超时HTTP ≥ 500 判定为失败openai-compatible.ts模型列表openai-compatible:check-model-list拉取模型列表并验证非空openai-compatible.ts聊天补全openai-compatible:check-chat-completions使用generateText发送一条ping消息做真实小请求结果带缓存与互斥锁去重[openai-compatible.ts](https://link.gitcode.com/i/f918a9b83a112c27134215934130bd83#L117-L206, L297-L322)值得注意的是聊天补全探测中的细节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之类的短消息做最终验证能收到回复即代表链路完全打通。问题排查官方文档给出的排查要点如下结合源码可进一步定位API 校验失败Ping API 报错依次检查API Key 是否正确、是否包含多余空格源码中validationRequiredWhen会对 key 做trim()后判断index.ts账户是否有可用额度credit或 quota 是否已耗尽是否触发了 OpenRouter 或上游的速率限制rate limit网络连接是否可达https://openrouter.ai/api/v1/连通性检查带 10 秒超时见 openai-compatible.ts。模型列表无法加载部分模型或账号权限可能不返回列表此时在设置 → 模块 → 意识页面手动输入 OpenRouter 官方文档中给出的精确模型 ID注意大小写与厂商前缀如openai/gpt-4o须与 OpenRouter 返回的 ID 完全一致。配置已保存但仍无响应回到意识模块确认提供者与模型均已选中——凭证保存 ≠ 提供者激活。相关文档与源码官方配置文档多语言中文版、韩文版、英文版通用聊天模型设置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.tsOpenAI 兼容校验器实现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-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考