企业官网建设流程全解析

• 人工智能
• AI Agent
• MCP 服务
• 工具调用
• GUI 自动化
• 语音
• 数字人
• 交互助手

本文围绕 AIRI 中 Cloudflare Workers AI 对话提供程序的完整配置流程展开：如何准备账号级凭证（API Token 与 Account ID）、如何在设置页面填写并通过自动必填项校验、如何进入 Consciousness 模块选择模型并用测试消息验证连通性，同时结合仓库源码解析该提供程序的定义、校验器与调用链，帮助你理解"为什么 AIRI 需要 Account ID"以及校验失败时的排查路径。

Cloudflare Workers AI 使用账号级（account-level）凭证体系：它不像部分第三方网关只需要一个 API Key 加 Base URL，而是必须同时提供API Token与Account ID两项信息，AIRI 才能定位到你 Cloudflare 账号下的 Workers AI 资源。本文以文档docs/content/en/docs/manual/config/providers/consciousness/cloudflare-workers-ai.md描述的实操流程为主线，辅以仓库中的实现证据。

一、准备凭证：API Token 与 Account ID 缺一不可

在 Cloudflare 侧需要准备两样东西：

1. 创建 API Token：在 Cloudflare 控制台的 API Tokens 管理页面（dash.cloudflare.com/profile/api-tokens）创建一个具有 Workers AI 访问权限的 API Token，然后复制该 Token。
2. 获取 Account ID：在 Cloudflare 控制台中找到你的 Account ID 并复制。它是 Workers AI 请求路由所必需的账号标识。

安全提醒：API Token 与账号权限直接绑定。建议遵循最小权限原则，只授予 AIRI 所需的 Workers AI 相关权限，不要给 Token 附带超出需要的管理能力；同时不要把 Token 或 Account ID 写入公开日志、截图或粘贴到公开渠道。

从源码可以印证这一"双凭证"设计。提供程序定义文件 packages/provider-inference/src/providers/cloud/cloudflare-workers-ai/index.ts 中，配置 schema 用 zod 声明了两个必填字符串字段：

const cloudflareWorkersAIConfigSchema = z.object({ apiKey: z.string('API Key'), accountId: z.string('Account ID'), })

这正是设置页面上看到的API Token（底层字段名apiKey，UI 中以 password 类型渲染，见 index.ts#L23-L29）与Account ID（字段名accountId）两个输入框的来源。两者的界面文案来自 i18n 资源 packages/i18n/src/locales/zh-Hans/settings.yaml：Account ID 的占位符为"请输入 Cloudflare Account ID"，API Key 的占位符为"请输入 Cloudflare Workers AI 的 API Key"。

二、在 AIRI 中配置提供程序

配置路径为：Settings → Providers → Chat → Cloudflare Workers AI，填入API Token与Account ID两个字段。

这条路由对应仓库中的通用对话提供程序设置页 packages/stage-pages/src/pages/settings/providers/chat/[providerId].vue。该页面通过useProviderValidation(providerId)组合式函数接管校验状态（见 use-provider-validation.ts），其中accountId被作为一等公民的凭证字段单独管理（use-provider-validation.ts#L70-L77），与apiKey、baseUrl并列读写 Pinia 中的 provider 配置，保证 Account ID 的修改能即时触发自动校验。

需要注意的一点：该提供程序没有可编辑的 Base URL 字段。虽然通用设置页模板里带有 Base URL 输入框，但 Workers AI 的端点由 Cloudflare 官方网关固定决定，凭证中的 Account ID 已经完成资源定位，因此不要在该字段填入 Worker URL 或 API 路径——文档的 Troubleshooting 部分明确警告了这一点。

三、验证配置：自动必填项检查、模型选择与测试消息

文档定义的验证流程分三步，理解每一步"实际验证了什么"能帮你快速定位问题：

1. 等待自动必填项检查通过。AIRI 会自动运行校验，但这个检查只确认两个字段都有值，不会实际联系 Cloudflare 服务，也不会验证凭证本身的正确性。对应源码中注册名为cloudflare-workers-ai:check-config的配置校验器（index.ts#L42-L65）：它对apiKey与accountId分别做trim()后判空，空值时分别报告API token is required.或Account ID is required.。是否触发该检查由validationRequiredWhen决定——只有当两个字段都非空时，设置页才会进入"校验中"状态而非保持"未配置"（index.ts#L39-L41）。
2. 点击 Select Model →，跳转到 Settings → Modules → Consciousness。设置页底部按钮的行为见 [providerId].vue#L99-L102：goToModelSelection()会把当前providerId写入 consciousness store 的activeProvider，然后路由到/settings/modules/consciousness。在 Consciousness 页面选择 Cloudflare Workers AI 及一个可用模型，即完成"提供程序 → 对话模块"的绑定。
3. 回到聊天界面发送测试消息。只有收到成功的模型响应，才说明 Account ID、API Token 权限与所选模型三者真正可用。第 1 步的本地检查通过≠凭证有效，测试消息才是真正的端到端验证。

四、源码视角：定义、注册与底层调用链

为了让配置行为可预期，这里把该提供程序在仓库中的完整位置串一遍：

• 定义与工厂：providerCloudflareWorkersAI通过defineProvider声明（index.ts#L13-L38），tasks: ['chat']表明它只提供对话任务（不提供语音/嵌入等）。其createProvider调用createWorkersAI(config.apiKey, config.accountId)（来自@xsai-ext/providers/special/create），可见 AIRI 将"账号级凭证如何拼进请求"的细节完全委托给底层 SDK 的 Workers AI 适配器，配置页的职责边界就是收集这两个字符串。
• 注册入口：该定义被列入 packages/provider-inference/src/providers/index.ts 的portableProviderDefinitions列表，即无需 Electron/Vue 依赖即可加载的"可移植"定义集合，Web 与桌面端共用。
• 注册表机制：定义经由 registry.ts 的defineProvider（纯函数，导入模块不会改变共享注册表）交给应用侧的createProviderRegistry，后者会对重复 id 抛错并按order/名称排序，保证设置页列表的确定性。
• 协议适配：实例创建后，types.ts 中的getGenerationProvider会检查其是否原生支持 generation 接口，否则把chat方法适配为chat-completions协议的生成请求，进入 core-agent 的统一推理链路。

五、故障排查

对照文档给出的排查顺序，并叠加源码证据：

另外两点适用前提：其一，本地必填项检查永不发起网络请求，因此"检查通过"只说明配置完整，不能替代测试消息验证；其二，由于凭证是账号级绑定，更换 Cloudflare 账号或轮换 Token 后需要重新填写并使 Account ID 与 Token 保持同账号一致，否则即使字段齐全，测试消息仍会失败。

小结

• Cloudflare Workers AI 在 AIRI 中是纯 chat 任务提供程序，配置契约只有apiKey（API Token）+accountId（Account ID）两个必填字段，无 Base URL。
• 配置入口为 Settings → Providers → Chat → Cloudflare Workers AI；模型绑定入口为 Select Model → 跳转 Settings → Modules → Consciousness。
• 自动校验只做"非空"检查（cloudflare-workers-ai:check-config），真实可用性以聊天测试消息为准。
• 凭证最小权限、Token 与 Account ID 同账号，是该提供程序最常见的两类故障根因。

• 人工智能
• AI Agent
• MCP 服务
• 工具调用
• GUI 自动化
• 语音
• 数字人
• 交互助手