openmaic

OpenMAIC Skill

将此作为一份引导式、以确认为主的 SOP 使用。不要将整个设置过程压缩到一次回复中，也不要在未获得用户明确确认的情况下执行任何会改变状态的操作。

核心规则

• 一次只推进一个阶段。
• 在任何会改变状态的操作之前，先请求确认。
• 如果本地状态已存在，展示你发现的内容，并询问是否保留。
• 不要假设 OpenClaw agent 自身的模型或 API 密钥会被 OpenMAIC 复用。
• OpenMAIC 课堂生成使用 OpenMAIC 的服务端模型配置（openmaic.yml 以及 Web 应用中的模型设置）。
• 本 skill 不得依赖任何请求时的模型或提供商覆盖设置。
• 只有该服务端配置可以控制提供商选择和默认值。
• 不要默认要求用户将 API 密钥粘贴到聊天中。
• 优先引导用户自行编辑本地配置文件。
• 不要主动提出代替用户将 API 密钥写入配置文件。
• 一旦设置完成，并且用户明确要求生成课堂，在提交生成任务之前不要再请求二次确认。
• 对于本地文件读取（例如从磁盘读取 PDF 后再上传），仍需保留确认。

可选的 Skill 配置

如果存在，请从 ~/.openclaw/openclaw.json 中的以下位置读取默认值：

{
  "skills": {
    "entries": {
      "openmaic": {
        "enabled": true,
        "config": {
          "accessCode": "sk-xxx",
          "repoDir": "/path/to/OpenMAIC",
          "url": "http://localhost:3000"
        }
      }
    }
  }
}

• 如果存在 accessCode，默认使用 Live Demo 模式，并跳过模式选择提示——除非用户的意图是基于 OpenMAIC 进行扩展/构建（参见阶段 0 中的例外情况）。
• 仅将 repoDir 和 url 用作本地模式的默认值。
• 执行操作前仍需确认。

SOP 阶段

0. 选择模式

首先检查 skill 配置中的 accessCode。如果存在，声明已找到存储的访问码，并直接进入 Live Demo 模式（加载 references/live-demo.md，跳过阶段 1–4）。不要要求用户再次粘贴该访问码。**例外：**如果用户明确表示的意图是扩展 / 基于 OpenMAIC 构建 / 定制 OpenMAIC，或使用 @openmaic/* SDK（二次开发 / 二开 / SDK），则不要自动走捷径——无论是否存在 accessCode，都转到下方的扩展分支。一位回访的 Live Demo 用户现在想要进行二开，应被引导至扩展分支，而不是被悄然送回 Live Demo。

如果配置中没有 accessCode（或上述扩展例外适用），询问用户希望如何使用 OpenMAIC：

1. 使用 OpenMAIC Live Demo（推荐用于快速开始）——云版本：由 OpenMAIC 团队在 open.maic.chat 正式部署并托管的版本。需要访问码（以 sk- 开头）。在 https://open.maic.chat 登录，点击右上角的账号，打开“访问码设置”，生成一个访问码；然后将其添加到 ~/.openclaw/openclaw.json 中的 skills.entries.openmaic.config.accessCode。无需本地设置。
2. 本地运行——克隆仓库，配置提供商密钥，并在你的机器上运行。
3. 扩展或基于 OpenMAIC 构建（二次开发）——Fork 仓库并定制产品，或使用 @openmaic/* SDK 构建新东西。

如果用户选择 Live Demo 模式，加载 references/live-demo.md 并跳过阶段 1–4。 如果用户选择本地模式，照常继续到阶段 1。 如果用户选择扩展/基于 OpenMAIC 构建，加载 references/extend.md 并跳过设置/生成阶段。

1. 克隆或复用现有仓库

加载 references/clone.md。

当用户尚未安装 OpenMAIC，或当你需要确认使用哪个本地检出时，使用此阶段。

2. 选择启动模式

加载 references/startup-modes.md。

在仓库位置确认后使用此阶段。展示可用的启动模式，推荐一种，并等待用户选择。

3. 配置提供商密钥

加载 references/provider-keys.md。

在开始生成课堂之前使用此步骤。推荐一条提供商路径，并明确告诉用户需要自行编辑哪些内容（openmaic.yml 和 .env.local，或 Web 应用中的模型设置）。如果之后因提供商/模型/认证问题导致生成失败，请返回此阶段并引导用户更新相同的配置。

配置核心大模型密钥后，询问用户是否要启用可选功能（Web 搜索、图像生成、视频生成、TTS）。每项都是一个槽位，各自拥有自己的提供商——请参阅 provider-keys.md 中的“可选功能”部分。

4. 启动并验证 OpenMAIC

在用户选择启动模式并配置密钥后，使用所选方法启动 OpenMAIC，然后通过 GET {url}/api/health 验证服务。

5. 生成课堂

加载 references/generate-flow.md。

仅在服务健康后使用此步骤。在读取本地文件以上传之前先确认。如果用户已明确要求生成，则在提交生成任务前不要再请求二次确认，然后按照轮询循环执行，直到成功或失败（失败的任务可以重试；请参阅生成流程）。生成请求只发送支持的字段（requirement、materialIds）；可选功能遵循服务端的提供商配置。上传和提交必须归属同一所有者：在匿名 cookie 模式下，每个请求都要复用同一个 cookie jar。对于长时间运行的任务，优先使用稀疏轮询，并告知用户如果本轮在完成前结束，可稍后再来查看。

响应风格

• 保持每一步简短明确。
• 当用户必须选择时，优先提供 2-3 个具体选项。
• 始终将推荐选项放在第一位，并用一句话解释原因。
• 一步完成后，说明发生了什么变化以及下一次确认的目的是什么。
• 返回课堂链接时，将原始绝对 URL 单独放在一行，不要使用粗体、Markdown 链接语法、代码格式或表格。