在 AIRI 中接入 Cloudflare Workers 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-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airiCloudflare Workers AI 以账户级凭据鉴权AIRI 需要同时持有API Token与Cloudflare Account ID才能定位并调用你的 Workers AI 资源。本指南围绕官方手册的配置流程展开结合 AIRI 源码说明凭据校验、连接测试与模型选用的底层实现帮助你完成从创建 Token 到在聊天模块中真正使用 Workers AI 模型的完整闭环。为什么选择 Cloudflare Workers AI如果模型服务已经部署在 Cloudflare 账户中使用 Workers AI 能直接复用该账户已有的 Token 与 Account ID无需再申请第三方平台的独立密钥。在 AIRI 中该服务商被归类为云端付费服务商paidCloud见 packages/stage-ui/src/libs/providers/attributes.ts其定义声明为Cloudflare Workers AI with account-scoped credentials即账户级凭据——这是它与 OpenAI 兼容服务商最本质的区别鉴权不依赖 Base URL而是由 Account ID 定位账户、由 Token 授权访问。第一步准备凭据1. 创建 API Token打开 Cloudflare API Tokens 管理页面https://dash.cloudflare.com/profile/api-tokens。创建具有 Workers AI 访问权限的 API Token复制该 Token。在创建 Token 时AIRI 内部将其作为apiKey字段保存并在校验前执行trim()去除首尾空白见 packages/provider-inference/src/providers/cloud/cloudflare-workers-ai/index.ts因此粘贴时即使带入多余空格也不会导致校验失败。2. 获取 Account ID在 Cloudflare 控制台https://dash.cloudflare.com/中找到并复制 Account ID。Account ID 用于定位你的 Workers AI 资源与 Token 必须来自同一个 Cloudflare 账户否则 AIRI 会提示凭据无效。安全提醒API Token 与账户权限绑定。请遵循最小权限原则只授予 AIRI 所需的 Workers AI 权限不要将 Token 或 Account ID 与公开日志一同发布。第二步在 AIRI 中配置打开设置 → 服务商 → 聊天 → Cloudflare Workers AI。填写API Token与Account ID两个字段。配置表单的源码实现聊天服务商的配置页面对应 packages/stage-pages/src/pages/settings/providers/chat/cloudflare-workers-ai.vue页面通过useProviderValidation组合式函数见 packages/stage-ui/src/composables/use-provider-validation.ts驱动整条配置链路API Token 输入ProviderApiKeyInput密码类型输入框placeholder 为请输入 Cloudflare Workers AI 的 API KeyAccount ID 输入ProviderAccountIdInput对应字段 label 为Cloudflare Account IDplaceholder 为请输入 Cloudflare Account ID文案定义见 packages/i18n/src/locales/zh-Hans/settings.yaml。两个输入框通过 Pinia store 持久化:on-reset按钮handleResetSettings可将配置一键还原。服务商定义的字段约束在 服务商注册定义 中配置结构由 zod schema 约束const cloudflareWorkersAIConfigSchema z.object({ apiKey: z.string(API Key), accountId: z.string(Account ID), })只有apiKey与accountId两个必填字段——不存在 Base URL 字段这正是此服务商不使用可编辑的 Base URL的代码级依据。服务商通过createWorkersAI(config.apiKey, config.accountId)构造底层客户端来自xsai-ext/providers/special/create两个凭据缺一不可。第三步验证配置基础凭据验证页面挂载后useProviderValidation会自动触发校验见 use-provider-validation.ts校验时机由validationRequiredWhen控制——只有当apiKey与accountId都已填写时才进行见 服务商定义validationRequiredWhen: (config) { return !!config.apiKey !!config.accountId }随后执行内置校验器cloudflare-workers-ai:check-config同一文件对apiKey与accountId执行trim()后判空任一为空即返回错误信息API token is required./Account ID is required.全部通过则返回valid: true。值得注意的细节是自动校验默认跳过聊天 Ping 检查skipChatPingCheck: true见 use-provider-validation.ts以避免意外产生 API 计费自动校验只做字段级格式校验。手动连接测试如需验证 Token 与 Account ID 是否真的能连通 Cloudflare点击页面上的手动测试按钮。runManualTest会以onlyChatPingCheck: true发起真实的聊天 Ping 请求见 use-provider-validation.ts该请求会真实调用 Workers AI 接口成功manualTestPassed置为true显示测试通过信息失败显示validation_failed或provider_error对应的错误文案。校验通过后AIRI 会把该服务商标记为configured并调用markProviderAdded见 use-provider-validation.ts使其出现在后续的模型选择器中。选择模型基础凭据验证通过后点击页面上的前往模型选择按钮页面会跳转到/settings/modules/consciousness聊天配置页或/settings/modules/vision视觉配置页见 packages/stage-pages/src/pages/settings/providers/vision/cloudflare-workers-ai.vue在其中选择你想要使用的具体模型。视觉模型复用同一凭据AIRI 还为 Workers AI 提供了独立的视觉服务商入口vision-cloudflare-workers-ai见 vision 配置页它同样只要求apiKey与accountId两个字段。从源码结构看聊天与视觉两类配置共用同一套云凭据语义apiKey为 API Token、accountId为账户 ID。排查凭据无效的常见原因若 AIRI 提示凭据无效请依次检查检查项说明Token 权限API Token 是否具有 Workers AI 访问权限最小权限原则下最容易遗漏Account ID 归属Account ID 是否与 Token 来自同一个Cloudflare 账户字段空白是否混入了多余空格源码会trim()但建议粘贴时保持干净Base URL此服务商不使用可编辑的 Base URL不应将 Worker URL 或 API 路径填入任何字段关于工具Tool调用的已知限制从测试用例可见Cloudflare Workers AI 可能不支持工具调用。AIRI 在 packages/stage-ui/src/stores/ai/chat-llm/llm.test.ts 中注册了与服务商关联的工具不受支持错误特征[cloudflare, tools is not supported], [cloudflare, tool is not supported for this model], [cloudflare, tools are not supported],这意味着当底层模型返回上述错误时AIRI 会识别出该服务商不支持工具调用并给出相应提示。如果你的对话场景强依赖 Function Calling需要在选型时对此有所预期。小结接入 Cloudflare Workers AI 只需三件事在 Cloudflare 控制台创建具备 Workers AI 权限的 API Token、复制 Account ID、在设置 → 服务商 → 聊天 → Cloudflare Workers AI中填入两者并完成验证。与常规 OpenAI 兼容服务商不同它没有可编辑的 Base URL鉴权完全由apiKeyaccountId组合完成自动校验仅做字段格式检查真实的连通性需通过手动测试确认之后即可前往 Consciousness / Vision 模块选择具体模型。相关源码可进一步参阅 服务商定义、聊天配置页 与 验证组合式函数。【免费下载链接】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），仅供参考