How to Configure and Deploy the OpenMAIC Skill with OpenClaw Workbench Integration

The OpenMAIC Skill deploys to OpenClaw through a standard SKILL.md package located in skills/openmaic/, requiring configuration in ~/.openclaw/openclaw.json and a running OpenMAIC server instance with valid LLM provider keys.

The THU-MAIC/OpenMAIC repository provides a ready-to-use skill package that integrates with the OpenClaw agent workbench, enabling natural language classroom generation workflows. This guide walks through the complete OpenMAIC Skill OpenClaw workbench integration, from installation to asynchronous classroom deployment.

Understanding the OpenMAIC Skill Architecture

The skill follows the standard SKILL.md format recognized by OpenClaw and other compliant workbenches. According to the source code analysis, the integration operates through four logical phases defined in skills/openmaic/SKILL.md:

• Clone: Detects whether the OpenMAIC repository exists locally and prompts for installation if missing.
• Startup: Guides server initialization via pnpm dev, production builds, or Docker, verifying that the instance is reachable.
• Provider Keys: Surfaces required environment variables from .env.local and suggests optimal LLM providers.
• Generation: Submits async jobs to the /api/generate-classroom endpoint, polls for completion, and returns classroom URLs.

The runtime logic resides in lib/server/agent-runtime/, which handles session management, material processing, and job polling during the generation phase.

Installing the OpenMAIC Skill in OpenClaw

Install the skill through the OpenClaw CLI to register it with your workbench.

clawhub install openmaic

If you are using an alternative workbench (such as Codex, DeepSeek, or WorkBuddy), manually import the skills/openmaic/ directory or its compressed archive into your workbench's skill repository. The package contains the SKILL.md router and the references/ folder containing inline help fragments.

Configuring the Skill in OpenClaw

OpenClaw reads per-skill configuration from ~/.openclaw/openclaw.json. You must add an openmaic entry specifying either hosted or self-hosted mode.

Hosted Mode Configuration

For the managed service at https://open.maic.chat/, provide your access code:

{
  "skills": {
    "entries": {
      "openmaic": {
        "config": {
          "accessCode": "sk-YOUR-ACCESS-CODE"
        }
      }
    }
  }
}

Self-Hosted Mode Configuration

For local development or private deployments, specify the repository path and server URL:

{
  "skills": {
    "entries": {
      "openmaic": {
        "config": {
          "repoDir": "/path/to/OpenMAIC",
          "url": "http://localhost:3000"
        }
      }
    }
  }
}

Place this file at ~/.openclaw/openclaw.json as documented in the README under the OpenClaw Integration section.

Setting Up the OpenMAIC Server

The skill requires a running OpenMAIC server instance. Deploy this through Node.js or Docker before invoking the skill.

Clone and Install Dependencies

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

Configure Environment Variables

Copy the template and configure at least one LLM provider:

cp .env.example .env.local

Edit .env.local to include your provider credentials:

# Required: At least one LLM provider

OPENAI_API_KEY=sk-xxxxxxxxxxxx
DEFAULT_MODEL=openai:gpt-5.5

# Optional: Azure OpenAI configuration

# AZURE_OPENAI_API_KEY=your-azure-key

# AZURE_OPENAI_BASE_URL=https://YOUR-RESOURCE.openai.azure.com/openai

# Optional: Local Lemonade provider

LEMONADE_BASE_URL=http://localhost:13305/v1

The repository's .env.example contains the full list of supported providers and variables.

Start the Server

Run the development server:

pnpm dev

For production deployments:

pnpm build && pnpm start

The server listens on http://localhost:3000 by default. Alternatively, use Docker for persistent deployments:

services:
  openmaic:
    build: .
    env_file: .env.local
    ports:
      - "3000:3000"
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: openmaic
      POSTGRES_PASSWORD: openmaic-dev
      POSTGRES_DB: openmaic
    volumes:
      - pgdata:/var/lib/postgresql/data
volumes:
  pgdata:

Using the OpenMAIC Skill Integration

With the server running and skill configured, invoke classroom generation through natural language commands in any OpenClaw chat window:

teach me quantum physics

OpenClaw executes the following workflow:

1. Configuration Verification: Validates accessCode for hosted mode or repoDir/url for self-hosted mode.
2. Endpoint Communication: POSTs to /api/generate-classroom with any attached material files.
3. Job Polling: Monitors the async generation job status through the agent runtime.
4. Result Delivery: Returns a clickable link to the generated classroom (e.g., http://localhost:3000/classroom/abc123).

Each step requires explicit user confirmation, preventing unauthorized automation.

Extending the Skill for Custom Workflows

Advanced users can modify the skill behavior by editing files under skills/openmaic/:

• SKILL.md: Defines the SOP flow and routing logic between clone, startup, and generation phases.
• references/: Contains Markdown snippets rendered as contextual help during each step.

After modification, re-import the directory into your workbench to deploy custom classroom generation workflows.

Summary

• The OpenMAIC Skill package resides in skills/openmaic/SKILL.md and follows the standard skill format.
• Configure OpenClaw through ~/.openclaw/openclaw.json using either accessCode (hosted) or repoDir/url (self-hosted).
• The OpenMAIC server requires pnpm install, a populated .env.local file, and at least one LLM provider key.
• Natural language commands trigger the /api/generate-classroom endpoint via the lib/server/agent-runtime/ subsystem.
• Docker and secondary development options support production deployments and custom SOP modifications.

Frequently Asked Questions

What file format does the OpenMAIC Skill use for workbench integration?

The skill uses the SKILL.md format located at skills/openmaic/SKILL.md. This Markdown-based specification defines the standard operating procedure (SOP) flow that OpenClaw and other compliant workbenches parse to execute the clone, startup, provider configuration, and generation phases.

Where does OpenClaw store the OpenMAIC Skill configuration?

OpenClaw stores skill-specific configuration in the ~/.openclaw/openclaw.json file. The openmaic entry within the skills.entries object accepts accessCode for hosted mode or repoDir and url for self-hosted deployments.

Which LLM providers can I use with the OpenMAIC server?

The OpenMAIC server supports OpenAI, Azure OpenAI, and local providers like Lemonade. Configure these in the .env.local file by setting OPENAI_API_KEY, AZURE_OPENAI_API_KEY with AZURE_OPENAI_BASE_URL, or LEMONADE_BASE_URL respectively. The DEFAULT_MODEL variable specifies which provider to use by default.

How does the skill handle classroom generation asynchronously?

When you submit a generation request, the skill calls the /api/generate-classroom endpoint and creates a durable job managed by lib/server/agent-runtime/. The skill polls this job status until completion, then returns the final classroom URL, ensuring reliable handling of long-running generation tasks without blocking the workbench interface.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}