中/EN
实战 SOP
实战 SOP

自建 OpenMAIC 课堂 SOP：从取码到接 Agent 工作台

从零把 OpenMAIC 跑起来的完整 SOP：①零部署路线（open.maic.chat 取访问码即用）；②本地标准部署（pnpm >= 10，clone → pnpm install → .env → pnpm dev）；③生产化（pnpm build && pnpm start、Vercel 一键、docker compose up --build）；④进阶（Postgres 持久化 profile、ACCESS_CODE 访问码、MP4 导出 profile、Lemonade/FunASR 本地化）；⑤接进 agent 工作台（clawhub install openmaic 或导入 skills/openmaic/，从飞书/Slack 发消息生成课堂）。含 6 条踩坑与 10 项上线自检清单，全部命令逐字取自官方 README。

发布于 2026年9月8日11 分钟阅读
<!-- openmaic-classroom-deploy-sop | sop | 自建 OpenMAIC 课堂 SOP：从取码到接 Agent 工作台 -->

OpenMAIC（THU-MAIC/OpenMAIC，MIT 协议，GitHub 周榜第一）把"一句话进、整门课出"的多智能体互动课堂做成了开源项目：AI 老师讲课、AI 同学讨论、白板推导、随堂测验、互动仿真、项目式学习（PBL）一应俱全。对技术团队最有价值的是它中立、可自托管——自己带模型、自己带存储、自己带部署。但"能跑"和"能上生产"之间隔着一整套操作：选哪条部署路线、.env 配什么、什么时候上 Docker、持久化怎么开、怎么接进飞书/Slack 让同事发条消息就生成课堂。

这篇 SOP 走一遍完整实操，从零部署到上线到接 agent 工作台，五步走。配套的开源篇见 OpenMAIC 开源资源盘点；如果你也在做 API 迁移类的标准化操作，可参考本站 Claude API 迁移 SOP。所有命令均逐字取自官方 README，环境变量名、文件名一律不改写。

一、零部署路线：Hosted 模式取码即用

如果你只是想立刻生成一门课，或者先验证 OpenMAIC 适不适合团队，不要碰命令行。Hosted 模式是成本最低的路：在 open.maic.chat 取一个访问码，零本地搭建，把码贴进配置就能用。

这条路线对应 README 里的 "Hosted mode"：Grab an access code from open.maic.chat, save it in your config, and generate classrooms instantly — no local setup required。它的本质是官方托管了一份完整服务，你只消费能力，不维护进程。适合三类场景：个人先体验、对内做 demo、或者作为后续自托管的前置验证（确认课程质量达标再投入运维）。

在 OpenClaw / ClawHub 体系里，Hosted 模式也是 Skill 的默认首选。OpenClaw 的配置文件 ~/.openclaw/openclaw.json 中写入访问码即可：

jsonc
{
  "skills": {
    "entries": {
      "openmaic": {
        "config": {
          // Hosted mode: paste your access code from open.maic.chat
          "accessCode": "sk-xxx",
          // Self-hosted mode: local repo path and URL
          "repoDir": "/path/to/OpenMAIC",
          "url": "http://localhost:3000"
        }
      }
    }
  }
}

注意 Hosted 模式的 accessCode 不是你自己的 LLM key，而是 open.maic.chat 下发的访问凭证——官方替你解决了模型调用。换句话说，这条路线你连 provider key 都不用配。但它也意味着课程数据和生成过程托管在官方侧，对数据留在自家机房有强要求的团队，应直接跳到下面的自托管路线。

二、本地标准部署：pnpm 路线（clone -> install -> .env -> dev）

要真正自托管、把模型和数据握在自己手里，标准路线是 pnpm 起一个 Next.js 服务。先说门槛，这是第一个常见翻车点。

前置条件（README Prerequisites 原文）：

  • Node.js >= 22.19
  • pnpm >= 10

pnpm 版本是硬门槛，低于 10 直接装不上依赖。先确认版本：

bash
node -v
pnpm -v

低于要求就先升级 pnpm（corepack enable && corepack prepare pnpm@10 --activate，或按官方文档）。然后克隆并安装：

bash
git clone https://github.com/THU-MAIC/OpenMAIC.git
cd OpenMAIC
pnpm install

装完后第一步不是直接跑，而是配 .env。从样例复制：

bash
cp .env.example .env.local

接下来要填至少一个 LLM provider key。README 明确：Fill in at least one LLM provider key。支持的 provider 很多——OpenAI、Azure OpenAI、Anthropic、Amazon Bedrock、Google Gemini、DeepSeek、Qwen、Kimi、MiniMax、Grok (xAI)、OpenRouter、Doubao、Tencent Hunyuan/TokenHub、Xiaomi MiMo、GLM、Ollama（本地）、Lemonade（本地）、FunASR（本地）以及任意 OpenAI 兼容 API。最少配一个，例如：

env
OPENAI_API_KEY=sk-...
AZURE_OPENAI_API_KEY=...
AZURE_OPENAI_BASE_URL=https://YOUR-RESOURCE.openai.azure.com/openai
AZURE_OPENAI_MODELS=YOUR-DEPLOYMENT-NAME
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...
GROK_API_KEY=xai-...
OPENROUTER_API_KEY=sk-or-...
TENCENT_API_KEY=sk-...
XIAOMI_API_KEY=...

这里有个关键认知：README 说 all providers are optional（全部 optional），但"可选"是指你可以只配其中一个、不必全配；它不是说"一个都不配也能跑出课程"。一个 key 都不填，生成链路会因为拿不到模型而失败。所以"全 optional"的正确理解是"任选其一"，而不是"全空着跑"。这是第二个常见坑。

除了 .env.local，README 还给了 server-providers.yml 这种声明式配置方式（providers 下写 openai/azure/anthropic/bedrock 等）。两者选其一即可，本地标准部署用 .env.local 最直观。

配好 key 后启动开发服务：

bash
pnpm dev

打开 http://localhost:3000 即可开始学习。dev 模式带热更新，适合调配置、验 provider、做二次开发。生产环境不要停在这里——见下一步。

三、生产与容器化：build+start / Vercel / Docker

开发跑通后，有三种把服务稳定交出去的方式，按运维复杂度递增。

方式一：本机生产构建。 这是自托管最轻量的"生产"形态（仍是单节点，无持久化）：

bash
pnpm build && pnpm start

pnpm build 会做 Next.js 生产构建，pnpm start 起生产服务器。和 dev 的区别是没有热更新、做了产物优化，吞吐和稳定性都更好。适合单机长期跑、内网访问。

方式二：Vercel 一键部署。 README 提供 vercel.com/new/clone 按钮，仓库 URL 已经是 https://github.com/THU-MAIC/OpenMAIC，clone 时强制要求至少配一个 LLM provider key（envDescription 就是 "Configure at least one LLM provider API key"）。手动流程：

  1. Fork this repository
  2. Import into Vercel
  3. Set environment variables (at minimum one LLM API key)
  4. Deploy

Vercel 路线适合已经有 Vercel 账号、想要全球边缘部署、不想管服务器的团队。注意 Vercel 的无状态特性——默认浏览器端存储，不自动带 PostgreSQL，需要持久化请走下面第四步的 server-persistence profile。

方式三：Docker 部署。 这是推荐的生产形态，环境隔离、可复现：

bash
cp .env.example .env.local
# Edit .env.local with your API keys, then:
docker compose up --build

镜像基于 node:22-alpine。国内或弱网环境可加两个构建参数加速 npm/Alpine 拉取（注意：这两个参数只加速 Alpine 和 npm 源，不加速 Docker Hub 拉取，包括 Dockerfile frontend 和 node:22-alpine 基础镜像本身）：

bash
ALPINE_MIRROR=mirrors.tuna.tsinghua.edu.cn \
NPM_REGISTRY=https://registry.npmmirror.com \
docker compose up --build

直接 docker build 时也支持同样的 build-arg：

bash
docker build \
  --build-arg ALPINE_MIRROR=mirrors.tuna.tsinghua.edu.cn \
  --build-arg NPM_REGISTRY=https://registry.npmmirror.com \
  -t openmaic:local .

第三个坑就在这：有人以为加了 ALPINE_MIRROR / NPM_REGISTRY 就能让 Docker Hub 的 node:22-alpine 拉取变快，其实不会——那两个参数只管镜像内部的 Alpine 包和 npm 源。Docker Hub 慢要单独给 Docker daemon 配 registry mirror。另外，不要把用户名、密码、token 写进这两个 build-arg，因为 Docker 可能把它们记进镜像元数据或构建 provenance。

四、进阶：持久化、访问码、视频导出与本地化

课程跑起来只是起点。要上"真生产"，下面四件进阶配置几乎必做。

1. PostgreSQL 持久化（server-persistence profile）。 默认 OpenMAIC 不依赖数据库，课程文档、学习者运行记录、KV、资源都存在浏览器里。要服务端持久化（重启不丢、可多人共享），用这个 profile：

bash
cp .env.example .env.local
printf '\nDATABASE_URL=postgres://openmaic:openmaic-dev@postgres:5432/openmaic\nPERSISTENCE_DEV_TOKEN=openmaic-local-dev\n' >> .env.local
NEXT_PUBLIC_PERSISTENCE=1 NEXT_PUBLIC_PERSISTENCE_TOKEN=openmaic-local-dev docker compose --profile server-persistence up --build

这里有两个要命的细节。其一是 NEXT_PUBLIC_PERSISTENCE 是构建期开关，被编译进浏览器 bundle——开启了就必须配套可用的 DATABASE_URL 和 PERSISTENCE_DEV_TOKEN，且 NEXT_PUBLIC_PERSISTENCE_TOKEN 在构建时必须和 server token 一致，否则首页会弹 "persistence-unavailable" toast，课程库显示为空。其二是改 Postgres 密码必须先把卷删了：docker compose --profile server-persistence down -v，设新密码和匹配的 DATABASE_URL 再起——因为 PERSISTENCE_POSTGRES_PASSWORD 只在数据目录为空时初始化角色，事后改环境变量不会轮换已有卷里的密码。这是第四个坑。

还要提醒：PERSISTENCE_DEV_TOKEN / NEXT_PUBLIC_PERSISTENCE_TOKEN 不是真密钥，前者被编译进公开的 JS bundle，任何人都能提取并用它读改写所有学习者分区和文档。它只适合 localhost 或可信网络单用户部署。上生产前必须替换 lib/persistence/server-auth.ts 做真正的会话校验。

2. ACCESS_CODE（共享部署的站点级密码）。 把服务暴露给团队时，给 .env.local 加一行：

env
ACCESS_CODE=your-secret-code

设了之后访客先看到密码框，所有 API 路由也被保护；不设则和之前一样。对内的"小范围共享部署"强烈建议加上，至少挡掉无关扫描器。

3. MP4 视频导出（video-export profile）。 想把课堂导出成可发的视频，需要 Chromium + FFmpeg，单独跑在一个 render-service 容器里：

bash
docker compose --profile video-export up --build

应用通过 RENDER_SERVICE_URL（docker-compose.yml 里已预设）自动探测服务并启用一键 MP4 渲染。第五个坑：如果没起这个 profile，或者 RENDER_SERVICE_URL 没配，导出不会报错崩溃，而是降级为下载项目 ZIP 供本地 CLI 渲染。所以"导出按钮点了没出视频"通常不是坏了，而是 render-service 没起来。

4. 本地化（Lemonade / FunASR / 音视频抽取）。 不想把数据送云、想用本地模型的团队：

  • Lemonade 本地 AI（LLM/图像/TTS/ASR，无需 key）：
env
LEMONADE_BASE_URL=http://localhost:13305/v1
TTS_LEMONADE_BASE_URL=http://localhost:13305/v1
ASR_LEMONADE_BASE_URL=http://localhost:13305/v1
IMAGE_LEMONADE_BASE_URL=http://localhost:13305/v1
  • FunASR 本地语音识别（SenseVoiceSmall / Paraformer / Fun-ASR-Nano，无需 key）：
bash
python -m pip install torch torchaudio
python -m pip install "funasr==1.4.0" fastapi uvicorn python-multipart
# Add vLLM for Fun-ASR-Nano on NVIDIA GPUs
python -m pip install vllm
funasr-server --device cuda --model fun-asr-nano
env
ASR_FUNASR_BASE_URL=http://localhost:8000/v1

CPU -only 用 funasr-server --device cpu --model sensevoice。本地音视频抽取则需装系统 ffmpeg（ffmpeg 和 ffprobe 都在 PATH），应用抽取时再解析可执行文件；ffmpeg 不是 npm 依赖，没装只跳过本地抽取，不影响启动。

五、接进 agent 工作台：从飞书/Slack 发消息生成课堂

OpenMAIC 的杀手锏不是网页点一点，而是它能作为一个 Skill 被你的 agent 工作台调用——在飞书、Slack、Discord、Telegram 这些你已经用的聊天工具里,跟助手说一句"教我量子物理",课堂就生成好了,完全不用碰终端。

OpenMAIC 的 skill 包在仓库 skills/openmaic/，是标准 SKILL.md 格式，除 OpenClaw 外，也兼容 Codex、DeepSeek、WorkBuddy 等 agent 工作台。两种接入方式:

方式一：OpenClaw + ClawHub 一行安装。 在 OpenClaw 里直接：

bash
clawhub install openmaic

或让 Claw 说一句 "install OpenMAIC skill" 也能装。装完后按 README 的 skill 流程走:Clone(检测已有 checkout 或克隆前先问) -> Startup(选 pnpm dev / pnpm build && pnpm start / Docker) -> Provider Keys(推荐 provider 路径,你自己改 .env.local) -> Generation(提交异步生成任务并轮询直到完成)。每个步骤都先问你确认,没有黑盒自动化。

方式二：导入 skills/openmaic/ 目录。 在 Codex、DeepSeek、WorkBuddy 这类工作台,把仓库里的 skills/openmaic/ 文件夹(或其 zip)导入工作台即可。Skill 内置的 SOP 会覆盖 live demo、本地搭建、课堂生成,以及基于 @openmaic/* SDK 的二次开发引导。

接进来后,Hosted 模式是体验最快的:在 open.maic.chat 取访问码存进配置,零本地搭建就能生成;Self-hosted 模式则 clone、装依赖、配 key、起服务,skill 一步步带你走。生成是异步任务——skill 会轮询进度,完成后把链接发给你。对技术团队而言,这意味着把"做课"这件事沉淀成可对话、可复用的工作流:新人进飞书群,@一下助手就能拉起一门口径统一的培训课,而不用每个人去研究怎么部署。

踩坑记录

坑一：pnpm 版本不够。 README 白纸黑字 pnpm >= 10,用老版本 pnpm install 直接报依赖解析错误。先 pnpm -v 确认,不够就 corepack prepare pnpm@10 --activate。Node 也要 >= 22.19,两个门槛一个都绕不过。

坑二：provider key 全空着跑。 README 说 "all providers are optional" 容易被误读成"都不用配"。optional 指你可以只配其中一个、不必全配,但至少填一个,否则生成链路拿不到模型会失败。配一个最顺手的(OpenAI / Anthropic 都行),先在 .env.local 落地。

坑三：Docker 构建参数不加速 Hub 拉取。 ALPINE_MIRROR 和 NPM_REGISTRY 只管镜像内部的 Alpine 包和 npm 源,管不到 Docker Hub 的 node:22-alpine 基础镜像拉取。Hub 慢要单独给 Docker daemon 配 registry mirror,别指望这两个参数。另外 build-arg 里别塞账号密码 token,Docker 可能写进镜像元数据。

坑四：改 Postgres 密码没先 down -v。 PERSISTENCE_POSTGRES_PASSWORD 只在数据目录为空时初始化角色。事后改环境变量不会轮换已有 openmaic-postgres 卷的密码。要换密码必须先 docker compose --profile server-persistence down -v,再设新密码和匹配 DATABASE_URL 重启。

坑五：RENDER_SERVICE_URL 没配则导出降级。 没起 video-export profile 或 RENDER_SERVICE_URL 未配置时,MP4 导出不会报错,而是降级为下载项目 ZIP 本地渲染。以为"导出坏了"其实是 render-service 没起来——该 profile 单独 docker compose --profile video-export up --build 起一下就好。

坑六：NEXT_PUBLIC_PERSISTENCE 是构建期开关。 开了却不配套可用的 DATABASE_URL、或 NEXT_PUBLIC_PERSISTENCE_TOKEN 与 server token 不一致,首页弹 persistence-unavailable,课程库显示空。这是构建期编译进 bundle 的,改 env 不生效,必须重新 build。

十项上线前自检清单

  1. 确认 node -v >= 22.19 且 pnpm -v >= 10,版本门槛不过一切免谈。
  2. 从 .env.example 复制出 .env.local,不要把配置直接写进 .env.example。
  3. 至少一个 LLM provider key 已填入 .env.local(如 OPENAI_API_KEY 或 ANTHROPIC_API_KEY),切勿全空运行。
  4. 开发验证用 pnpm dev 打开 http://localhost:3000,确认能正常生成一门测试课。
  5. 生产交付走 pnpm build && pnpm start 或 Docker,不要拿 dev 当生产。
  6. 对内共享部署加 ACCESS_CODE=your-secret-code 做站点级密码保护。
  7. 需要持久化就启 server-persistence profile,且 NEXT_PUBLIC_PERSISTENCE、NEXT_PUBLIC_PERSISTENCE_TOKEN 与 DATABASE_URL 三处一致。
  8. 要导出 MP4 就单独起 video-export profile,确认 RENDER_SERVICE_URL 被探测到;否则接受 ZIP 降级。
  9. 改 Postgres 密码前务必 docker compose --profile server-persistence down -v,否则密码不轮换。
  10. 接 agent 工作台:OpenClaw 跑 clawhub install openmaic,或把 skills/openmaic/ 导入 Codex/DeepSeek/WorkBuddy;Hosted 模式取 open.maic.chat 访问码零部署。

常见问题

Q1：我一个代码都不想写，最快怎么用上 OpenMAIC？ 走 Hosted 模式。打开 open.maic.chat 取一个访问码，把它贴进 OpenClaw 的 ~/.openclaw/openclaw.json 配置（或任何兼容工作台的 skill 配置），就能在飞书/Slack 里直接让助手生成课堂，零本地部署。先验证课程质量，再决定是否自托管。

Q2：README 说 provider 都是 optional，是不是不配 key 也能跑？ 不是。"optional" 指你只需任选其一、不必全配，但至少填一个 LLM provider key（如 OPENAI_API_KEY 或 ANTHROPIC_API_KEY），否则生成链路拿不到模型会失败。全空着跑是最大的新手坑。

Q3：Docker 部署时国内拉取慢，加 ALPINE_MIRROR 和 NPM_REGISTRY 有用吗？ 只对镜像内部的 Alpine 包和 npm 源有效，能加速构建期依赖安装；但管不到 Docker Hub 的 node:22-alpine 基础镜像拉取。Hub 慢要单独给 Docker daemon 配 registry mirror。另外不要把账号密码写进这两个 build-arg。

Q4：开了 server-persistence 后想改 Postgres 密码，直接改环境变量行不行？ 不行。PERSISTENCE_POSTGRES_PASSWORD 只在数据目录为空时初始化角色，事后改环境变量不会轮换已有卷的密码。正确做法：docker compose --profile server-persistence down -v 删卷，设新密码和匹配 DATABASE_URL，再起 profile。注意 down -v 会清掉该卷数据，重要数据请先 ALTER ROLE 在线改密。

Q5：点"导出视频"没出 MP4，是坏了还是配置问题？ 多半是 render-service 没起来。MP4 导出依赖 video-export profile（应用经 RENDER_SERVICE_URL 自动探测）。若没起该 profile 或 RENDER_SERVICE_URL 未配，导出会降级为下载项目 ZIP 供本地 CLI 渲染，而非报错。单独 docker compose --profile video-export up --build 起一下即可。

参考来源

本文由 AI 辅助生成，经人工审核编辑。最后更新：2026-09-08

常见问题

我一个代码都不想写，最快怎么用上 OpenMAIC？
走 Hosted 模式。打开 open.maic.chat 取一个访问码，把它贴进 OpenClaw 的 `~/.openclaw/openclaw.json` 配置（或任何兼容工作台的 skill 配置），就能在飞书/Slack 里直接让助手生成课堂，零本地部署。先验证课程质量，再决定是否自托管。
README 说 provider 都是 optional，是不是不配 key 也能跑？
不是。"optional" 指你只需任选其一、不必全配，但至少填一个 LLM provider key（如 `OPENAI_API_KEY` 或 `ANTHROPIC_API_KEY`），否则生成链路拿不到模型会失败。全空着跑是最大的新手坑。
Docker 部署时国内拉取慢，加 ALPINE_MIRROR 和 NPM_REGISTRY 有用吗？
只对镜像内部的 Alpine 包和 npm 源有效，能加速构建期依赖安装；但管不到 Docker Hub 的 `node:22-alpine` 基础镜像拉取。Hub 慢要单独给 Docker daemon 配 registry mirror。另外不要把账号密码写进这两个 build-arg。
开了 server-persistence 后想改 Postgres 密码，直接改环境变量行不行？
不行。`PERSISTENCE_POSTGRES_PASSWORD` 只在数据目录为空时初始化角色，事后改环境变量不会轮换已有卷的密码。正确做法：`docker compose --profile server-persistence down -v` 删卷，设新密码和匹配 `DATABASE_URL`，再起 profile。注意 `down -v` 会清掉该卷数据，重要数据请先 `ALTER ROLE` 在线改密。
点"导出视频"没出 MP4，是坏了还是配置问题？
多半是 render-service 没起来。MP4 导出依赖 `video-export` profile（应用经 `RENDER_SERVICE_URL` 自动探测）。若没起该 profile 或 `RENDER_SERVICE_URL` 未配，导出会**降级**为下载项目 ZIP 供本地 CLI 渲染，而非报错。单独 `docker compose --profile video-export up --build` 起一下即可。

相关文章

实战 SOP

block/buzz 自托管部署 SOP：从 Docker 到 agent 入组

block/buzz 自托管部署完整 SOP（与 buzz-hive-mind 热点文成对）：本地开发栈（just setup/build/dev）+ 生产单节点（deploy/compose Docker，Postgres/Redis/MinIO）+ 配置（.env：RELAY_URL/BUZZ_RELAY_PRIVATE_KEY/RELAY_OWNER_PUBKEY）+ agent 入组（Nostr keypair NIP-98 签名，buzz-admin 管成员）+ 闭门 relay + 5 FAQ。部署命令全据 README/compose/.env/CLI/ARCHITECTURE，未编造。

2026年8月6日9 分钟阅读
实战 SOP

n8n 搭建 AI agent 工作流实战 SOP：部署与避坑

在 n8n 画布里搭一个能自主调用工具的 AI agent 工作流的完整 SOP：Docker 自托管一条命令部署、AI Agent 节点四件套解剖（Language Model+Memory+Tools+System Prompt）、分步搭建（选触发器->配节点->加工具->输出->测试发布）、五个避坑（Memory 失忆/API Key 硬编码/过度设计/上下文漂移/数据格式不匹配）+5 FAQ。节点参数以 n8n 官方文档为准，给配置逻辑不伪造完整 JSON。

2026年8月6日9 分钟阅读
实战 SOP

LLaDA-Image 本地部署 SOP：五步跑通 6B 生图模型

把蚂蚁开源 6B 生图模型 LLaDA-Image 跑起来的五步 SOP：①环境准备（依赖与国内镜像加速下载）；②四档权重怎么选（Base 50 步 / Turbo 4 步 × BF16 / FP8，国内走 ModelScope）；③跑通第一张图（Base 与 Turbo 最小可用命令）；④进阶（参考图编辑、文字渲染、ComfyUI 接入、显存不足时的降级策略）；⑤生产化（批量队列、并发容量规划、成本监控、结果入库与故障降级）。含 6 条踩坑与 10 项上线自检清单，命令逐字取自官方 README；仓库 license 为 null，商用前须确权。

2026年9月9日11 分钟阅读