AIRI 接入 Cloudflare Workers AI 完整指南：账号级凭据配置、模型接入与故障排查

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-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi

Cloudflare Workers AI 是 AIRI 提供的云端聊天模型提供方（Provider）之一，它采用账号级（account-scoped）凭据体系，除了常规 API Token 之外，还必须提供 Cloudflare Account ID 才能定位到你的 Workers AI 资源。本文以仓库中的官方配置文档 docs/content/ko/docs/manual/config/providers/consciousness/cloudflare-workers-ai.md 为主线，结合 AIRI 源码中该提供方的实际实现，完整讲解从创建 Cloudflare 凭据、在 AIRI 中填入配置、通过校验、选择模型到发送测试消息的全流程，并给出源码级的校验逻辑分析与常见问题排查思路。读完本文，你将能够独立完成 Cloudflare Workers AI 的接入、验证与排障。

为什么选择 Cloudflare Workers AI

在 AIRI 中，聊天提供方（Provider）可以来自本地推理（如 Ollama）或云端服务。Cloudflare Workers AI 属于后者：它直接复用你的 Cloudflare 账号，无需额外注册第三方模型服务平台。

文档明确给出了选择它的理由：

Cloudflare 账户支持的 Workers AI 模型可以通过该提供方在 AIRI 中直接运行。

从源码属性目录 packages/stage-ui/src/libs/providers/attributes.ts 可以看到，cloudflare-workers-ai被标记为paidCloud（pricing: 'paid'、deployment: 'cloud'），即付费云端服务，这与其账号级计费模型一致。在提供方注册文件中，它被声明为tasks: ['chat']（index.ts），说明它在 AIRI 中承担聊天对话任务，可在「设置 → 模块 → 意识（Consciousness）」中被选用。

第一步：准备 Cloudflare 凭据

与 OpenAI 等仅需一个 Key 的提供方不同，Cloudflare Workers AI 使用账号级凭据体系，共需两个字段：

1. 创建 API Token

1. 打开 Cloudflare 的API Tokens面板，创建一个具备Workers AI 访问权限的 API Token（权限范围内勾选 Workers AI 相关权限）。
2. 创建完成后立即复制 Token 字符串（Token 仅在创建时完整显示一次）。

2. 查找 Account ID

在 Cloudflare 控制台首页即可找到 Account ID，将其一并复制。在 AIRI 中，Account ID 与 API Token 配对使用：Account ID 决定「是哪个账号」，API Token 决定「以什么权限访问」，二者缺一不可。

3. 安全注意事项

文档明确给出如下安全警告，配置时务必遵守：

• API Token 绑定的是账号权限，请遵循最小权限原则，只为 AIRI 授予其所需的 Workers AI 权限，不要使用拥有全部权限的全局 Token；
• 切勿将 Token 或 Account ID 写入公开日志、提交到公开仓库或发布到任何公开渠道。

第二步：在 AIRI 中配置提供方

界面入口

按照文档指引，在 AIRI 中打开：

1. 设置（Settings）→ 提供方（Providers）→ 聊天（Chat）→ Cloudflare Workers AI；
2. 在配置表单中依次填入API Token与Account ID。

对应的配置页面源码位于 packages/stage-pages/src/pages/settings/providers/chat/cloudflare-workers-ai.vue：页面通过ProviderApiKeyInput承载 API Token 输入框（类型为密码框），通过ProviderAccountIdInput承载 Account ID 输入框，两个值会实时写入 Pinia 的提供方配置 store（providers.value['cloudflare-workers-ai'].apiKey / accountId）。

表单字段的国际化文案（含韩语标签与占位符）定义在 packages/i18n/src/locales/ko/settings.yaml：

• 계정 ID（Account ID）：描述为「Cloudflare 계정 ID」，占位符为「당신의 Cloudflare 계정 ID」；
• API Key：占位符为「Cloudflare API 키 입력」。

配置项定义（源码视角）

提供方注册文件 packages/stage-ui/src/libs/providers/providers/cloudflare-workers-ai/index.ts 使用 Zod 声明了配置结构：

createProviderConfig: ({ t }) => z.object({ apiKey: z.string().meta({ labelLocalized: t('...api-key.label'), type: 'password', // API Token 以密码框呈现 }), accountId: z.string().meta({ labelLocalized: t('...account-id.label'), }), })

接入时通过createWorkersAI(config.apiKey, config.accountId)（来自@xsai-ext/providers/special/create）构建实际的模型客户端，也就是说两个字段会被一起送入 Workers AI 客户端——只填 API Token 而缺少 Account ID 时无法完成请求寻址。

第三步：配置校验——「字段校验」不等于「连通性校验」

保存配置后，AIRI 会自动执行必填字段检查（required-field validation）。这一点需要特别注意：文档明确指出——

该检查仅验证两个字段是否都填入了值，并不会连接 Cloudflare，也不会验证凭据的真实有效性。

源码中这段逻辑位于 index.ts：

validationRequiredWhen: (config) => { return !!config.apiKey && !!config.accountId }, validators: { validateConfig: [{ id: 'cloudflare-workers-ai:check-config', validator: async (config) => { const apiKey = typeof config.apiKey === 'string' ? config.apiKey.trim() : '' const accountId = typeof config.accountId === 'string' ? config.accountId.trim() : '' if (!apiKey) errors.push({ error: new Error('API token is required.') }) if (!accountId) errors.push({ error: new Error('Account ID is required.') }) return { errors, valid: errors.length === 0 } }, }], }

关键点：

• 校验发生在本地，仅检查apiKey与accountId是否非空（且会对值做trim()去空格处理）；
• 校验不会发起任何网络请求，因此「校验通过」只能说明字段填写完整，不能说明 Token 权限正确、账号匹配或模型可用；
• 校验结果会通过页面上的ProviderValidationAlerts组件展示，并提供「强制标记为有效（force valid）」与手动测试入口（对应 cloudflare-workers-ai.vue 中的runManualTest/forceValid）。

结论：真正的凭据正确性验证，必须通过实际发送聊天消息来完成（见下一步）。

第四步：选择模型并发送测试消息

校验通过后，按文档继续完成模型选择与连通性验证：

1. 点击「模型选择 →」按钮，进入设置 → 模块 → 意识（Consciousness）；
2. 在模型列表中选择Cloudflare Workers AI提供方下的可用模型；
3. 返回聊天界面，发送一条测试消息。

源码层面，Chat 配置页的「模型选择」按钮会将路由跳转到/settings/modules/consciousness（cloudflare-workers-ai.vue），与文档描述的导航路径完全一致。

文档给出的判定标准是：如果测试消息成功收到响应，则说明 Account ID、API Token 权限与所选模型三者协同正常。反过来，若响应失败，则按下一节的排查步骤定位问题。

提示：仓库中还提供了视觉任务（vision）场景下的 Cloudflare Workers AI 配置页 packages/stage-pages/src/pages/settings/providers/vision/cloudflare-workers-ai.vue，其 providerId 为vision-cloudflare-workers-ai，「模型选择」按钮跳转到/settings/modules/vision。也就是说，同一组 Cloudflare 凭据可在 AIRI 中复用于多个任务模块。

问题排查

场景一：必填字段校验失败

如果配置校验（required-field check）失败，请确认：

• API Token与Account ID两个字段都填入了值（注意粘贴时不要带入首尾空格，源码校验会trim()但尽量保持输入干净）；
• 两个字段确实填入了正确的配置项（Token 填进 API Token，账号 ID 填进 Account ID），不要颠倒。

场景二：测试消息发送失败

如果字段校验通过但测试消息失败，按文档排查：

1. 检查 Token 权限：确认 API Token 拥有Workers AI 权限（在 Cloudflare API Tokens 面板中核对权限范围）；
2. 检查账号匹配：确认 API Token 与 Account ID属于同一个 Cloudflare 账号。Token 是绑定到特定账号权限的，跨账号组合必然失败。

场景三：误填 Base URL / API 路径

文档特别强调：该提供方不使用可编辑的 Base URL。

Workers AI 的 API 地址是由提供方实现内部（createWorkersAI客户端）根据 Account ID 自动推导的，因此：

• 不要在配置中填写 Worker URL、API 路径或自定义端点；
• 若在类似 OpenAI 兼容提供方的习惯影响下填入了 Base URL，应将其清空，否则可能导致请求寻址错误。

适用前提与限制小结

按照「创建最小权限 Token → 复制 Account ID → 填入两个字段 → 通过本地校验 → 在意识模块选择模型 → 发送测试消息」这条链路操作，即可在 AIRI 中稳定启用 Cloudflare Workers AI 聊天能力。相关提供方定义、校验逻辑与配置页面源码分别位于 index.ts、chat 配置页 与 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-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi