OpenMAIC Live Demo 云端模式接入指南：访问码配置、课堂生成与配额策略

OpenMAIC Live Demo 云端模式接入指南访问码配置、课堂生成与配额策略【免费下载链接】OpenMAICOpen Multi-Agent Interactive Classroom — Get an immersive, multi-agent learning experience in just one click项目地址: https://gitcode.com/GitHub_Trending/op/OpenMAIC本文是基于 OpenMAIC 官方 Agent Skill 文档 live-demo.md 编写的一篇技术实战指南讲解 OpenMAIC 官方托管的云端版本open.maic.chat的接入方式。作为 Open Multi-Agent Interactive Classroom 项目仓库根目录见 README.md的云服务形态Live Demo 免去了本地克隆仓库、配置 Provider Key、选择启动模式等全部前期工作。读者读完本文后将掌握如何获取并配置sk-开头的访问码、如何通过Authorization: Bearer调用云端生成 API、如何按capabilities做特性探测、如何优雅地处理配额与错误并理解这套机制在仓库源码中的具体实现。Live Demo 是什么官方托管的云端版本OpenMAIC Live Demo 是 OpenMAIC 团队在https://open.maic.chat官方部署并托管的云端版本。与本地模式需要git clone仓库、配置.env.local或server-providers.yml、自选启动方式不同Live Demo 模式下所有前置条件仓库路径、启动模式、Provider Key都已由服务端满足用户只需要一个访问码access code即可开始生成多智能体互动课堂。该模式主要面向两类场景用户手头已有来自 open.maic.chat 的访问码希望跳过本地部署直接体验生成用户只想“开箱即用”地使用 OpenMAIC而非进行二次开发。在 SKILL.md 定义的 SOP 中只要技能配置里存在accessCodeAgent 就会自动切换到 Live Demo 模式并跳过本地部署的 Phase 1–4唯一的例外是用户明确表达“扩展 / 二次开发 / 使用 openmaic/* SDK”的意图时会改走 extend 分支。这也说明 Live Demo 与本地模式共用同一套POST /api/generate-classroom生成接口只是入口与鉴权方式不同。访问码Access Code配置Live Demo 的鉴权载体是形如sk-xxx的访问码。整个获取与配置流程分为三步1. 从技能配置读取访问码Agent 应首先从 OpenClaw 的配置文件读取访问码配置位置为// ~/.openclaw/openclaw.json { skills: { entries: { openmaic: { enabled: true, config: { accessCode: sk-xxx, repoDir: /path/to/OpenMAIC, url: http://localhost:3000 } } } } }关键规则如果配置中已存在accessCode直接使用绝不要求用户在聊天框里再次粘贴访问码。这与整个 Skill 的“不要默认要求用户把 API Key / 访问码粘贴进聊天”的核心原则一致。2. 获取访问码当配置中不存在accessCode时引导用户前往 open.maic.chat 获取登录https://open.maic.chat点击右上角账号头像打开「访问码设置」生成一个以sk-开头的访问码。获取后写入~/.openclaw/openclaw.json的skills.entries.openmaic.config.accessCode字段等待用户确认后再继续期间不得要求用户在聊天中粘贴访问码。3. 校验连通性配置完成后用下面的请求验证访问码是否有效GET https://open.maic.chat/api/health Authorization: Bearer access-code成功确认连接进入生成流程401访问码无效请用户到 open.maic.chat 检查或重新生成并更新配置文件网络失败建议检查网络或考虑切换到本地模式。服务端的访问码实现在仓库源码中可以找到这套访问码机制的完整实现它并非一个简单的字符串比对app/api/access-code/verify/route.ts当服务端设置了ACCESS_CODE环境变量后POST /api/access-code/verify使用 Nodecrypto.timingSafeEqual做常量时间比较防止时序侧信道攻击验证通过后签发一个 HMAC 签名的 token并写入名为openmaic_access的 httpOnly cookiemaxAge为 7 天生产环境secure: true。lib/server/access-token.tstoken 结构为timestamp.signature签名由createHmac(sha256, accessCode).update(timestamp)生成校验时再次用timingSafeEqual对比。middleware.tsEdge 中间件对所有/api/*请求除/api/access-code/*与/api/health白名单外校验openmaic_accesscookie 的 HMAC 签名签名无效或缺失时返回401与错误体{ success: false, errorCode: INVALID_REQUEST, error: Access code required }。也就是说访问码在“人类用户 浏览器”场景下通过 cookie 完成鉴权而在 Agent / 脚本调用场景下通过Authorization: Bearer access-code头完成鉴权两者在服务端共用同一个 HMAC 验签逻辑。生成课堂Generating a ClassroomLive Demo 模式的生成流程与本地模式基本一致详见 generate-flow.md差异集中体现在三处差异项Live Demo 模式Base URLhttps://open.maic.chat硬编码不可配置鉴权所有 API 请求携带Authorization: Bearer access-code头课堂访问地址https://open.maic.chat/classroom/{id}由于云端是官方部署生成前置条件仓库、启动方式、Provider Key全部已满足只要用户明确提出了生成请求即可直接提交无需二次确认。提交生成任务POST https://open.maic.chat/api/generate-classroom Authorization: Bearer access-code请求体示例{ requirement: Create an introductory classroom on quantum mechanics for high school students }仅发送服务端支持的字段字段是否必填说明requirement必填课堂需求描述pdfContent可选PDF 解析后的文本与图片内容language可选zh-CN|en-US默认zh-CN其他任意值静默回退到zh-CNenableWebSearch可选是否在大纲生成时引入联网搜索上下文默认falseenableImageGeneration可选是否允许在大纲中加入图片生成元数据默认falseenableVideoGeneration可选是否允许在大纲中加入视频生成元数据默认falseenableTTS可选是否开启服务端 TTS 语音生成默认falseagentMode可选default内置默认智能体|generate用 LLM 为课程量身定制智能体档案所有可选布尔字段缺省时均为false缺省发送可保持向后兼容。不要依赖请求时传模型或 Provider 覆盖参数——这是 Skill 的硬性规则Provider 选择与默认值只能由 OpenMAIC 服务端配置文件.env.local/server-providers.yml控制。PDF 驱动的生成解析 PDF 的绝对路径读取前先征求用户确认先调用解析接口POST https://open.maic.chat/api/parse-pdf再将requirement与pdfContent一起发给POST /api/generate-classroom。在仓库中app/api/parse-pdf/route.ts 接收multipart/form-data上传的 PDF 文件通过extractDocument统一走文档抽取管道返回含text、images与metadata含pageCount、fileName、fileSize的结构化内容这些内容即可作为pdfContent回传。任务提交响应与轮询POST /api/generate-classroom的响应仅代表“任务已受理”典型响应如下参考 app/api/generate-classroom/route.ts服务端以202状态返回{ success: true, jobId: abc123, status: queued, step: queued, pollUrl: https://open.maic.chat/api/generate-classroom/abc123, pollIntervalMs: 5000 }随后进入轮询循环保存jobId、pollUrl、pollIntervalMs当前任务仍处于queued/running时不得再次提交新的生成任务按GET {pollUrl}轮询课堂生成任务建议采用保守的约 60 秒轮询间隔即使pollIntervalMs更短仅当status变为succeeded或failed时停止。轮询接口实现在 app/api/generate-classroom/[jobId]/route.ts返回status、step、progress、message、scenesGenerated、totalScenes、result、error与done标志。作业的持久化与状态机定义在 lib/server/classroom-job-store.ts状态流转queued → running → succeeded | failed每个 job 以 JSON 文件形式存储含inputSummary快照与result带有withJobLock按任务粒度的互斥锁保证读改写原子性内置僵死任务回收running状态超过 30 分钟无进度更新会被标记为failedStale job: process may have restarted during generation实际生成由 lib/server/classroom-job-runner.ts 中的runClassroomGenerationJob执行并通过onProgress回调持续回写进度。可靠性规则Reliability Rules一次轮询请求失败绝不重启任务遇到瞬时网络错误或5xx等待约 60 秒后重试同一个pollUrl任务长时间运行属于正常现象告知用户仍在进行并继续轮询而不是重新提交宁少勿多轮询频率越低长任务越不容易在 Agent 循环中被打断单轮 Agent 内活跃轮询上限约10 分钟未完成时告知用户任务仍在后台运行并给出jobId与pollUrl便于后续轮次继续跟踪、无需重新提交仅在status、step或可见进度发生有意义变化时才向用户汇报避免每次轮询都刷屏遇到鉴权 / Provider / 模型 / Base URL 类错误不要通过改请求参数来“绕过”应请用户修复 OpenMAIC 服务端配置后重试失败时透出服务端原始错误并附上jobId成功时取最终轮询响应的result.classroomId与result.url。轮询自然结束时若本回合停止了活跃轮询而任务仍在运行用自然语言告知用户例如The classroom generation is still running in the background. Job ID: abc123 Check back with me in a little while and I can continue tracking this same job without starting over.结果返回格式返回课堂 ID 与可直接点击的课堂 URLURL 以裸绝对 URL 独占一行输出不做加粗、不加 Markdown 链接、不用反引号包裹、不加尖括号、不放进表格。推荐格式Classroom ID: Uyh82Y32ZK Classroom URL: https://open.maic.chat/classroom/Uyh82Y32ZK若生成失败返回 jobId 与服务端错误若错误暗示 Provider / 模型配置问题明确引导用户更新.env.local或server-providers.yml而非尝试运行时覆盖。特性探测Feature Detection由于 Live Demo 实例与本地代码库的更新节奏可能不同云端可能先于或后于本地代码上线新特性生成前必须先做特性探测以保证向前兼容。先调用健康检查接口GET https://open.maic.chat/api/health Authorization: Bearer access-code返回示例{ status: ok, version: ..., capabilities: { webSearch: true, imageGeneration: false, videoGeneration: false, tts: true } }规则仅当对应 capability 为true时才把enableWebSearch、enableImageGeneration、enableVideoGeneration、enableTTS等可选特性开关置为true若服务端不返回capabilities字段老版本不要发送任何新字段永远不要发送服务端不认识的字段。这条探测逻辑在仓库中的实现对应 app/api/health/route.tscapabilities的四个能力并非写死的常量而是动态检查对应 Provider 集合——只有当至少一个相关 Provider 被启用且未被disabled: true强制禁用时对应能力才为true。也就是说云端返回的capabilities直接反映了其服务端 Provider 配置状态Agent 依据它来决定是否携带特性开关正是为了避免向未启用相应 Provider 的服务端发送无效请求。配额QuotaLive Demo 模式有独立的每日配额限制每天 10 次生成与 Web UI 的配额相互独立当生成请求返回403且错误信息为Daily quota exhausted时告知用户每日上限已用尽配额将在午夜重置。在仓库的 API 错误码体系中403通常对应服务端拒绝类错误可参见 lib/server/api-response.ts 中RATE_LIMITED等错误码配额限制属于云端实例的运营策略由服务端统一裁决客户端侧只负责识别403 Daily quota exhausted并向用户说明。错误处理速查表Live Demo 模式下遇到错误时按下表处置HTTP 状态码含义处理动作401访问码无效请用户到 open.maic.chat 检查或重新生成访问码403配额耗尽告知每日上限10 次建议次日再试500服务端错误建议稍后重试或切换到本地模式从实现上看401与云端 middleware.ts 的 cookie/Bearer 验签失败路径对应500则对应生成管道异常如 app/api/generate-classroom/route.ts 中捕获任务创建异常后返回INTERNAL_ERROR。对于这类服务端错误Skill 的纪律是不修改请求参数强行重试而是让用户决定是稍后重试、换时间还是转入本地模式。总结OpenMAIC Live Demo 把“克隆仓库 配置 Provider 启动服务”这一整套本地前置压缩为一个访问码使任何持有sk-访问码的用户都能立即通过https://open.maic.chat提交生成任务拿到形如https://open.maic.chat/classroom/{id}的多智能体互动课堂链接。接入的关键纪律可以概括为四条访问码只在配置文件里流转~/.openclaw/openclaw.json不通过聊天传递每次请求都带Authorization: Bearer头Base URL 固定为 open.maic.chat先探测capabilities再发特性开关保持与云端版本的向前兼容遇到 401 / 403 / 500 分别按访问码、配额、服务端故障处理绝不靠篡改请求参数“硬闯”。结合 middleware.ts、lib/server/access-token.ts、app/api/health/route.ts 与 lib/server/classroom-job-store.ts 等源码可以看出这套云端接入机制与本地模式共用同一套生成与作业系统Live Demo 只是在入口处多了一层访问码鉴权并在服务端统一管理模型与 Provider——这正是“一个点击即可获得沉浸式多智能体学习体验”one-click immersive learning experience的产品承诺在工程上的落地形态。【免费下载链接】OpenMAICOpen Multi-Agent Interactive Classroom — Get an immersive, multi-agent learning experience in just one click项目地址: https://gitcode.com/GitHub_Trending/op/OpenMAIC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考