OpenClaw MCP Sidecar Quick Start

OpenClaw MCP Sidecar Quick Start

Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.

Connect AIWG to OpenClaw as an MCP sidecar for unrestricted workflow access.

Why a sidecar? OpenClaw's native skills handle quick single-step operations. The MCP sidecar (the agent-owned mcp operation) provides the full AIWG workflow engine — artifact management, multi-agent orchestration, template rendering, and staged SDLC execution. Use both together for maximum flexibility.

Architecture

OpenClaw (host)
  ├── Conversation flow, tool orchestration, session state
  ├── Native skills (~/.openclaw/skills/)
  ├── Behaviors (~/.openclaw/behaviors/)
  └── MCP connection
        └── AIWG MCP Server (sidecar)
              └── .aiwg/ artifacts, workflows, templates

OpenClaw owns: conversation flow, tool orchestration, session state, user-facing chat.

AIWG owns: workflow execution, artifact output in `.aiwg/`, template rendering, agent definitions.

MCP is the seam. OpenClaw calls AIWG tools via the protocol boundary — no filesystem coupling, no context duplication.

Prerequisites

  • OpenClaw installed (docs.openclaw.ai)
  • AIWG installed (the agent-assisted AIWG installation procedure)
  • A project with the agent-owned use operation already deployed

Part 1: Install MCP Configuration

Use AIWG to complete this documented outcome: Part 1: Install MCP Configuration
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

This creates or merges into `~/.openclaw/config.yaml`:

mcp_servers:
  aiwg:
    command: "aiwg"
    args: ["mcp", "serve"]
    env: {}

Note: OpenClaw supports both user-level (`~/.openclaw/config.yaml`) and workspace-level MCP configuration. The user-level config makes AIWG available across all projects.

For optimal context usage, limit the exposed tools. Edit the MCP config:

mcp_servers:
  aiwg:
    command: "aiwg"
    args: ["mcp", "serve"]
    tools:
      include:
        - discover
        - command-run
        - artifact-read
        - artifact-write
        - template-render
        - agent-list

Why whitelist? Each MCP tool adds schema overhead to the context window. The lean whitelist keeps discovery, CLI dispatch, artifact IO, templates, and agents available without enabling every opt-in subsystem.

Part 3: Verify the Connection

1. Restart OpenClaw (or run `openclaw reload`) 2. Ask: "What AIWG tools are available?" 3. OpenClaw should list the whitelisted tools

# Verify via CLI
openclaw tools list | grep aiwg

Part 4: Run Your First Workflow

Ask OpenClaw:

Create an architecture decision record for choosing REST over GraphQL for our API. Save it as an AIWG artifact.

What should happen:

1. OpenClaw calls `command-run`, `template-render`, or `artifact-write` via MCP 2. AIWG creates the artifact in `.aiwg/architecture/` 3. OpenClaw receives the result

Verify:

ls .aiwg/architecture/

Part 5: Context Budget

Understanding the token budget helps you configure the whitelist appropriately.

ComponentTokens
OpenClaw system prompt~2,000
AIWG MCP schema (lean tools)bounded
Total AIWG overhead~3,000

Without whitelist (full surface)

ComponentTokens
OpenClaw system prompt~2,000
AIWG MCP schema (20+ tools)~12,000
Total AIWG overhead~12,000

The 5-tool whitelist is a 75% reduction in MCP context overhead.

Part 6: Routing — MCP vs Native Skills

When both modes are active, route requests based on complexity:

Route to MCP whenUse native skills when
SDLC phase work neededQuick single-step operations
Artifact generation requiredSkill trigger phrase matches
Multi-agent orchestration requestedNo artifact persistence needed
Template-driven output neededVoice profile application
Agent loops or iterative executionContent validation

Validation Checklist

CheckActionExpected
ConnectivityAsk OpenClaw "list AIWG tools"Configured AIWG tools listed
Artifact writeAsk for a requirements docFile appears in `.aiwg/`
Artifact readAsk to read an artifactUses `artifact-read`
Failure modeStop the agent-owned mcp operation, try againGraceful error message

Troubleshooting

AIWG tools not visible:

  • Verify the agent-owned mcp operation runs successfully standalone
  • Check `~/.openclaw/config.yaml` MCP server syntax
  • Restart OpenClaw after config changes

Context filling up:

  • Verify the tool whitelist is configured
  • Reduce exposed tools to the 5-tool minimum

Artifacts not appearing:

  • Ensure AIWG is initialized in the project (the agent-owned use operation)
  • Verify the working directory matches the project root
  • Check that `artifact-write` is in the tool whitelist