Openmaic

核心用法

OpenMAIC Skill 是一个分阶段、确认密集型的标准作业程序（SOP）向导，专为 OpenClaw 生态中的 OpenMAIC 项目设计。它采用"一次一阶段"的渐进式引导模式，确保用户在每个关键决策点都明确知情并主动确认。

五大执行阶段：
1. 仓库克隆或复用 - 检测本地现有安装，避免重复操作
2. 启动模式选择 - 提供多种部署方案并给出推荐建议
3. 服务商密钥配置 - 指导用户自行编辑本地配置文件，绝不代写敏感凭证
4. 服务启动与健康检查 - 启动后通过 /api/health 验证可用性
5. 课堂生成 - 支持从需求文本或 PDF 文件生成结构化教学内容

显著优点

• 安全优先设计：强制确认机制防止误操作，API 密钥绝不通过聊天传输或由代理代写
• 状态感知：自动检测本地已有配置，智能复用而非重复初始化
• 清晰边界：严格区分 OpenClaw 代理配置与 OpenMAIC 服务端配置，避免混淆
• 灵活配置：支持通过 ~/.openclaw/openclaw.json 预设默认路径
• 长任务友好：生成任务采用稀疏轮询，避免阻塞交互

潜在局限

• 交互密度高：频繁确认可能让熟练用户感到繁琐
• 本地文件依赖：PDF 生成需要本地文件系统访问权限
• 服务端配置限制：所有模型/服务商选择必须通过服务端配置文件控制，缺乏运行时动态切换能力
• 异步等待：长生成任务可能需要用户主动返回检查状态

适合人群

• 初次部署 OpenMAIC 的教育技术从业者
• 需要标准化、可审计部署流程的团队
• 对 API 密钥安全有严格要求的组织环境

常规风险

| 风险类型 | 说明 | 缓解措施 |

|---------|------|---------|

| 密钥泄露 | 不当处理 API 密钥 | 强制用户本地编辑，禁止聊天传输 |

| 服务配置冲突 | 多实例配置混淆 | 严格隔离 OpenClaw/OpenMAIC 配置边界 |

| 误操作覆盖 | 重复初始化丢失数据 | 检测现有状态并主动提示复用 |

| 生成任务失败 | 服务商认证或模型问题 | 自动返回密钥配置阶段重新排查 |

核心用法

OpenMAIC Skill 是一款纯文档型引导工具，专为清华大学 THU-MAIC 实验室的 OpenMAIC 项目设计。其核心价值在于将复杂的本地部署流程拆解为五个确认式阶段：

1. 克隆或复用仓库 — 检测本地是否存在 OpenMAIC 代码库，引导用户选择克隆新仓库或复用已有目录
2. 选择启动模式 — 提供 2-3 种启动方案（如 Docker/npm/yarn 等），首推推荐选项并说明理由
3. 配置 Provider API Keys — 这是安全设计的亮点：Skill 绝不主动索取 API 密钥，而是指引用户手动编辑本地配置文件，从源头避免敏感信息泄露至聊天日志
4. 启动并验证服务 — 执行启动命令后，通过 GET /api/health 确认服务健康状态
5. 生成 Classroom — 支持从文本需求或 PDF 文件生成教学场景，PDF 读取前需二次确认

Skill 遵循严格的确认交互协议：每个状态变更步骤（文件写入、服务启动、配置修改）均需用户显式确认，且当用户明确表达生成意图后，直接提交任务无需重复确认。

显著优点

• 零代码攻击面：纯 Markdown 文档实现，无 .js/.py/.sh 等可执行文件，从根本上消除代码注入风险
• 隐私优先设计：不收集 API 密钥、不读取环境变量、不访问系统信息，符合 GDPR/CCPA 合规要求
• 学术级可信来源：清华大学 THU-MAIC 实验室维护（T2 级来源可信度），GitHub 仓库公开透明
• 渐进式引导体验：分阶段确认机制避免用户误操作，特别适合 CLI 新手
• 配置外置原则：所有敏感配置均存储于用户本地文件系统，Skill 仅提供编辑指引

潜在局限

• 依赖用户手动操作：无法一键自动化部署，需用户逐步执行编辑配置文件、启动服务等操作
• 仅支持本地服务：所有端点固定为 localhost:3000，不支持远程 OpenMAIC 实例管理
• 无错误自愈能力：当健康检查失败或生成任务报错时，仅提供重试指引，不自动修复
• PDF 处理能力有限：读取本地 PDF 需用户确认，且处理流程依赖外部 OpenMAIC 服务端实现
• 配置同步延迟：~/.openclaw/openclaw.json 中的默认值变更后需重启 Skill 会话生效

适合人群

• 需要本地化部署 OpenMAIC 的教育工作者与课程设计者
• 对 API 密钥安全敏感、倾向手动配置的中高级用户
• 熟悉命令行但希望减少配置错误的开发者与研究人员
• 需在离线或内网环境运行 AI 教学场景生成的高校 IT 管理员

常规风险

| 风险类型 | 评估 | 说明 |

|---------|------|------|

| 提示词投毒 | ✅ 无风险 | 纯文档实现，无动态指令注入点 |

| 权限升级 | ✅ 无风险 | 无 sudo/管理员权限诱导逻辑 |

| 数据外泄 | ✅ 极低风险 | 仅访问 localhost 与 GitHub，无第三方遥测 |

| 供应链攻击 | ✅ 极低风险 | 无 npm/pip 依赖，仅依赖用户自主克隆的官方仓库 |

| 配置泄露 | ⚠️ 用户责任 | Skill 不保管密钥，但用户需自行确保 `repoDir` 路径安全 |

建议配合防火墙规则限制 localhost:3000 的访问来源，并定期关注 THU-MAIC 官方安全公告。