企业官网建设流程全解析

OpenMAIC Provider Keys 配置指南：服务端模型与 API Key 的完整实操与源码级解析

【免费下载链接】OpenMAICOpen Multi-Agent Interactive Classroom — Get an immersive, multi-agent learning experience in just one click项目地址: https://gitcode.com/GitHub_Trending/op/OpenMAIC

本指南系统讲解 OpenMAIC 中 Provider Keys（模型与 API Key）的服务端配置方法，涵盖推荐路径、DEFAULT_MODEL模型字符串规则、.env.local与server-providers.yml两种配置方式的完整对比，以及底层模型解析与校验原理。读完本文，你将掌握如何为 OpenMAIC 一键式多智能体互动课堂正确接入 Anthropic、Google、OpenAI、DeepSeek 等大模型服务，并能为课堂生成配置好 Web Search、图片、视频与 TTS 等增强能力所需的全部 Key。

关键边界：OpenMAIC 不会自动复用 Agent 的模型与 Key

OpenMAIC 的课堂生成链路有一个极易踩坑的硬边界：生成过程不会自动复用 OpenClaw Agent 当前使用的模型或 API Key。OpenMAIC 服务端 API 会从OpenMAIC 自身的服务端配置中解析模型和 Provider Key，这一点在 lib/server/resolve-model.ts 中体现为：所有生成阶段最终都通过服务端配置（或经服务端校验的客户端参数）解析出模型、Key、Base URL 与 Provider 类型。

因此，本技能文档所描述的引导流程不依赖任何运行时覆盖（如请求级的模型覆盖、Key 覆盖、Base URL 覆盖、Provider 类型覆盖）。如果用户想更换其中任何一项，必须修改 OpenMAIC 服务端配置文件，即.env.local或server-providers.yml。

交互流程：先推荐路径，再让用户自行改配置

文档定义的 Agent 引导交互流程共五步，核心原则是"绝不在聊天中索取明文 Key，绝不替用户写 Key，绝不建议请求时临时覆盖"：

1. 先推荐 Provider 路径（见下节"推荐路径"），不要一上来就问用户要 API Key。
2. 询问用户希望在哪里配置：.env.local（对大多数用户推荐）还是server-providers.yml。
3. 精确告知需要修改的变量名或 YAML 字段——由用户自己编辑文件，不替用户写入 Key，不在聊天中索取明文 Key，也不建议请求时临时覆盖。
4. 等待用户确认编辑完成后再继续。
5. 如果后续生成因鉴权、Provider 或模型选择失败，引导用户回到同一个服务端配置文件，等待确认后再重试。

这套流程与源码的"服务端权威"设计完全一致：在 lib/server/provider-config.ts 中，只要某个 Provider 出现在服务端配置里（managed provider），服务端 Key 与 Base URL 就是权威值，客户端发送的任何覆盖都会被忽略（见resolveSectionApiKey/resolveSectionBaseUrl中if (entry) return entry.apiKey的分支）。

推荐路径：三种接入方案的完整对比

路径 1：最低摩擦（Least Configuration）

当用户希望配置量最小时推荐，只需设置：

ANTHROPIC_API_KEY=sk-ant-...

为什么可以"最少"？这背后是 OpenMAIC 一个重要的设计决策：没有硬编码的模型兜底。在 lib/server/resolve-model.ts 的resolveModel中，模型解析顺序是"阶段路由（stage route）> x-model（客户端）> DEFAULT_MODEL"，而当三者全部缺失时，会直接抛出错误：

No model could be resolved. Configure DEFAULT_MODEL (and/or a MODEL_ROUTES entry for this stage), or send a model via x-model.

即生成会明确失败而非静默选中某个默认模型。所以只设置ANTHROPIC_API_KEY还不够，必须同时显式设置DEFAULT_MODEL=anthropic:<model>，否则生成无法启动。

路径 2：速度 / 成本更均衡

当用户愿意多配置一个变量时推荐：

GOOGLE_API_KEY=... DEFAULT_MODEL=google:gemini-2.5-flash

选择理由：

• 质量与速度的平衡较好；
• 比默认兜底更贴合仓库当前的推荐方向；
• google:前缀至关重要——不带 Provider 前缀的模型字符串，默认会被解析为 OpenAI 模型。

这一规则在 lib/ai/providers.ts 的parseModelString中实现：它只在第一个冒号处切分字符串，得到providerId与modelId；若字符串中没有冒号，则providerId直接回退为'openai'（向后兼容，但已被弃用，启动时配置校验会给出[config]警告）。

路径 3：复用已有 Provider

当用户已配置过 OpenAI 或其他受支持的 Provider 并希望沿用：

OPENAI_API_KEY=sk-... DEFAULT_MODEL=openai:gpt-5.4-mini

DEEPSEEK_API_KEY=... DEFAULT_MODEL=deepseek:deepseek-chat

OpenMAIC 的 Provider 注册表（同样位于 lib/ai/providers.ts 的PROVIDERS常量）覆盖了 OpenAI、Anthropic、Google、Amazon Bedrock、MiniMax（Anthropic 兼容端点），以及 DeepSeek、Qwen、Kimi、GLM、SiliconFlow、Doubao、Tencent、Xiaomi、Ollama、Lemonade 等 OpenAI 兼容 Provider。完整的环境变量清单以 .env.example 为准，其中每个 LLM Provider 都支持{PROVIDER}_API_KEY、可选的{PROVIDER}_BASE_URL与可选的{PROVIDER}_MODELS（逗号分隔的模型白名单）。

模型字符串规则：永远带上 Provider 前缀

在推荐或展示DEFAULT_MODEL时，必须始终包含 Provider 前缀：

• google:gemini-2.5-flash
• anthropic:claude-sonnet-4
• openai:gpt-5.4-mini
• deepseek:deepseek-chat

不要推荐裸模型 ID（如单独的gemini-2.5-flash），否则 OpenMAIC 会将其解析为 OpenAI 模型（见上文parseModelString的冒号回退逻辑）。

需要注意：

• 上文模型 ID 仅为示例。模型名称会随供应商发布新版本而变化——如果推荐的 ID 被拒绝，应引导用户去查阅供应商官方文档中的当前模型名，并保留provider:前缀；
• 不要通过修改请求参数来绕过错误的DEFAULT_MODEL。用户应该修正服务端配置，而不是在请求层做临时 workaround。

若在请求时发送了providerType头，但与注册表中该 Provider 的类型（如openai、anthropic、google）不一致，resolveModel会直接抛错Provider type mismatch for ...，这一校验同样位于 lib/server/resolve-model.ts。

首选配置方式：.env.local与server-providers.yml对照

方式 A：.env.local（首次配置推荐）

cp .env.example .env.local

然后填入所选 Key。.env.example 是完整的环境变量参考模板，所有变量都是可选的，只配置你想用的 Provider 即可。其中与本文直接相关的关键项：

DEFAULT_MODEL=

.env.example对它的注释明确说明：它是/api/generate-classroom等服务端 API 路由的默认模型；对于不接收客户端x-model的服务端阶段，resolveModel会在"无MODEL_ROUTES条目、无x-model、无DEFAULT_MODEL"时直接抛错——刻意不提供硬编码的厂商兜底。示例值包括anthropic:claude-3-5-haiku-20241022、google:gemini-3-flash-preview、openai:gpt-5.5、minimax:MiniMax-M2.7-highspeed、bedrock:us.anthropic.claude-sonnet-5等。

方式 B：server-providers.yml（仓库根目录，可选替代）

providers: anthropic: apiKey: sk-ant-... google: apiKey: ... openai: apiKey: sk-...

若为非默认 Provider 配置课堂生成，还必须显式设置模型选择：

DEFAULT_MODEL=google:gemini-2.5-flash

从 lib/server/provider-config.ts 的实现看，两种方式其实是统一的加载管线：启动时读取server-providers.yml作为默认值，再以环境变量覆盖（env 优先于 YAML）；Provider 通过apiKey（或 keyless Provider 的baseUrl）被激活。一个 Provider 一旦被服务端配置（managed），其 Key 与 Base URL 即具有服务端权威，客户端无法覆盖——这也是文档强调"编辑服务端配置"的根本原因。另外注意该文件支持enabled: false做运维级强制关闭，环境变量<CAP>_<PREFIX>_ENABLED=false也是同等的强制关闭开关（仅用于 TTS、ASR、图片、视频、Web Search 五个能力区，LLM 与 PDF 不参与）。

深层原理：模型解析的优先级与启动期校验

理解以下两点，可以帮你诊断绝大多数"生成失败"问题。

解析顺序：阶段路由 > x-model > DEFAULT_MODEL

在 lib/server/resolve-model.ts 中，resolveModel的注释与实现明确写出三层解析顺序：

1. 阶段路由（MODEL_ROUTES）：按生成阶段（如scene-content、scene-actions、quiz-grade、pbl-chat等）精确指定模型。配置了路由的阶段，其模型选择权完全属于运维者，即使浏览器通过x-model发送了已保存的模型也不会覆盖路由；
2. 客户端x-model：未路由的阶段回退到客户端请求头x-model指定的模型；
3. DEFAULT_MODEL：前两者都缺失时的最终服务端默认值。

三者全缺则直接抛错，绝不静默兜底。此外MODEL_ROUTES还支持scene-content:slide、scene-content:quiz这类按场景类型的复合键，以及带完整 ThinkingConfig 的路由对象，完整说明见 .env.example 中MODEL_ROUTES一段的注释。

启动期校验：[config]警告而非启动失败

lib/server/config-validation.ts 的validateServerConfig在启动时（经 instrumentation.ts 触发）对模型路由配置做一次 warn-first 校验，包括：

• MODEL_ROUTES不是合法 JSON；
• 路由键不是可路由阶段（拼写错误检测）；
• 路由或DEFAULT_MODEL的 Provider 前缀未注册，或需要 Key 的 Provider 没有配置 Key（Ollama 等 keyless Provider 通过）；
• 裸模型 ID（无provider:前缀）——仍会按 OpenAI 处理但已弃用；
• 为未配置 Key 的 Provider 设置了<PREFIX>_MODELS固定模型列表（疑似拼写错误）；
• Agent 运行时开关已开但未设置DATABASE_URL。

这些都是警告而不是异常：配置不完整的部署依然能启动，但日志里的[config]警告会精确指出哪里有问题，从而避免把错误留到请求期才暴露。

对应地，tests/server/resolve-model.test.ts、tests/server/config-validation.test.ts 与 tests/server/model-routes.test.ts 分别覆盖了模型解析、启动校验与阶段路由的行为，可作为阅读源码时的补充参考。

推荐给用户的对话措辞（可直接套用）

以下示例措辞来自本文档，Agent 可以按需调整：

• "I recommend configuring OpenMAIC through.env.localfirst. Please edit that file locally and tell me when you're done."
• "For the simplest setup, I recommend Anthropic. For better speed/cost balance, I recommend Google plus aDEFAULT_MODELlikegoogle:gemini-2.5-flash. Which path do you want?"

"不要在聊天中索取 Key、不要替用户写 Key"的约束与上文"交互流程"一节一致——不要以索取 Key 作为开场。

可选功能：核心 LLM 之外的增强 Provider Key

以下能力在核心 LLM Key 配好之后按需启用。全部可选——课堂生成不依赖它们也能工作，配置它们只是为了解锁更丰富的内容。

.env.example 中还有这些能力区更完整的变量清单（含可选*_BASE_URL、MiniMax/Grok 等其他供应商、以及本地免 Key 的 Lemonade / VoxCPM / ComfyUI 等选项）。各能力区的运维级强制关闭开关同样见 .env.example 与 lib/server/provider-config.ts 的DISABLE_ENV_MAPS。

对应的server-providers.yml写法：

web-search: tavily: apiKey: tvly-... # Or use Exa: # exa: # apiKey: ... image: seedream: apiKey: ... video: seedance: apiKey: ... tts: openai-tts: apiKey: sk-...

注意 YAML 中 TTS 的 Provider ID 与.env.example的变量前缀并不完全相同（例如TTS_OPENAI_API_KEY对应 YAML 键openai-tts），这正是 lib/server/provider-config.ts 中TTS_ENV_MAP等映射表的作用——环境变量前缀到 Provider ID 的映射关系在源码中有完整定义，配置前可据此核对。

小结：一次成功的 Provider 配置长什么样

一次成功的接入流程可归纳为：推荐路径 → 选配置方式 → 用户自行编辑服务端文件 → 确认 → 生成验证。核心成功条件只有两个：其一，Provider 的 API Key 出现在服务端配置中（.env.local或server-providers.yml）；其二，DEFAULT_MODEL（或对应阶段的MODEL_ROUTES）显式设置为带provider:前缀的合法模型 ID。满足这两点，OpenMAIC 的多智能体互动课堂生成即可正常调用所选大模型；之后若再配置 Web Search、图片、视频或 TTS 的任意一个 Key，课堂内容就能进一步解锁实时联网、配图、短视频与语音旁白等增强能力。

【免费下载链接】OpenMAICOpen Multi-Agent Interactive Classroom — Get an immersive, multi-agent learning experience in just one click项目地址: https://gitcode.com/GitHub_Trending/op/OpenMAIC