agent-orchestrator/docs/openclaw-plugin-setup.md

OpenClaw Plugin Setup Guide

How to set up the Agent Orchestrator (AO) plugin for OpenClaw so the AI bot delegates all coding work to AO agents.

Prerequisites

• OpenClaw installed and running
• Agent Orchestrator installed with ao start completed in your repo
• ao, gh, tmux, and node available in PATH
• GitHub CLI (gh) authenticated

1. Install the Plugin

# From the agent-orchestrator repo
cd openclaw-plugin
openclaw plugins install .

Or manually copy the plugin files:

mkdir -p ~/.openclaw/extensions/agent-orchestrator
cp openclaw-plugin/index.ts ~/.openclaw/extensions/agent-orchestrator/
cp openclaw-plugin/openclaw.plugin.json ~/.openclaw/extensions/agent-orchestrator/
cp openclaw-plugin/package.json ~/.openclaw/extensions/agent-orchestrator/

2. Install the Skill

mkdir -p ~/.openclaw/extensions/skills/agent-orchestrator
cp skills/agent-orchestrator/SKILL.md ~/.openclaw/extensions/skills/agent-orchestrator/
cp -r skills/agent-orchestrator/references ~/.openclaw/extensions/skills/agent-orchestrator/ 2>/dev/null

3. Configure OpenClaw

Run /ao setup in any OpenClaw channel to auto-configure, or run these commands manually:

Required Settings

# 1. Plugin tools need "full" profile to be visible to the AI
#    The "coding" profile only includes built-in tools, NOT plugin tools
openclaw config set tools.profile "full"

# 2. Plugin tools are optional by default — explicitly allow them
openclaw config set tools.allow '["group:plugins"]'

# 3. Trust the plugin
openclaw config set plugins.allow '["agent-orchestrator"]'

Required: Disable Conflicting Built-in Skills

Without these, the bot may ignore AO and write code directly. Run once after setup:

# Prevent the bot from writing code directly — it should delegate to AO instead
openclaw config set tools.deny '["exec", "write", "str_replace_based_edit_tool", "create_file", "str_replace_editor"]'

# Disable the built-in coding skill (it tells the bot to use Codex/Claude Code directly, overriding AO)
openclaw config set skills.entries.coding-agent.enabled false

# Disable the built-in GitHub issues skill (it spawns OpenClaw sub-agents, bypassing AO)
openclaw config set skills.entries.gh-issues.enabled false

Optional Settings

# Discord: respond in server channels when @mentioned (default is DM-only)
openclaw config set channels.discord.groupPolicy "open"
# Read last 100 messages for context when @mentioned in a channel
openclaw config set messages.groupChat.historyLimit 100

Plugin Config (if ao isn't in PATH or repo isn't in default location)

# Set the path to the ao binary
openclaw config set plugins.entries.agent-orchestrator.config.aoPath "/path/to/ao"

# Set the working directory (must contain agent-orchestrator.yaml)
openclaw config set plugins.entries.agent-orchestrator.config.aoCwd "/path/to/your/repo"

# Set the path to gh binary (if not in PATH)
openclaw config set plugins.entries.agent-orchestrator.config.ghPath "/path/to/gh"

4. Set Up Identity Files

Create these files in ~/.openclaw/workspace/ to give the bot its personality and instructions:

IDENTITY.md

# IDENTITY.md

- **Name:** AO
- **Creature:** AI Engineering Manager
- **Vibe:** Sharp, concise, proactive
- **Emoji:** ⚡

## Default Setup

- **GitHub account:** <your-github-username>
- **Primary repo:** <owner/repo>
- **AO project ID:** <project-id-from-agent-orchestrator.yaml>
- **Owner:** <your-name>

## How You Operate

You are a MANAGER. You never write code yourself. You delegate ALL coding work to Agent Orchestrator.

When asked about work → use `ao_issues` tool
When asked about status → use `ao_sessions` or `ao_status` tool
When asked to start work → use `ao_spawn` tool (always include project ID)
When asked to start multiple → use `ao_batch_spawn` tool
When talking to an agent → use `ao_send` tool
When stopping an agent → use `ao_kill` tool (confirm first)

If an AO tool fails, report the error. Do NOT fall back to coding directly.

SOUL.md

# SOUL.md

You are AO — an AI engineering manager. You manage coding agents through Agent Orchestrator.

You NEVER write code directly. You delegate ALL coding to AO agents via ao_spawn.
Even if spawning fails, you report the failure — you don't code directly.

Always include full PR URLs when reporting: https://github.com/<owner>/<repo>/pull/<number>

5. Restart and Verify

# Restart the gateway
pm2 restart openclaw-gateway
# Or however you run OpenClaw

# Verify the plugin loaded
openclaw plugins list | grep agent-orchestrator

# Verify tools are visible
openclaw agent --agent main -m "List your tools"
# Should show ao_sessions, ao_issues, ao_spawn, etc.

# Verify AO works
/ao doctor

Why These Settings Matter

Setting	Why
tools.profile: "full"	The coding profile only includes built-in tools. Plugin tools require full.
tools.allow: ["group:plugins"]	OpenClaw treats ALL plugin tools as optional. Without this, they're invisible to the AI.
tools.deny: [exec, write, ...]	Without this, the bot will write code directly instead of delegating to AO.
skills.entries.coding-agent.enabled: false	This built-in skill tells the bot to use Codex/Claude Code. It overrides AO.
skills.entries.gh-issues.enabled: false	This built-in skill spawns OpenClaw sub-agents. It bypasses AO.
aoCwd	ao spawn must run from the directory containing agent-orchestrator.yaml.

Troubleshooting

Problem	Cause	Fix
Bot says "no ao_* tools available"	tools.profile is not full or tools.allow missing group:plugins	Run /ao setup
Bot writes code directly	coding-agent skill is active or exec/write not denied	Run /ao setup
ao spawn returns "No config found"	aoCwd not set or wrong path	Set plugins.entries.agent-orchestrator.config.aoCwd
ao: not found	ao not in PATH	Create symlink or set aoPath in plugin config
Only 2-3 issues shown (not all)	Bot answering from stale session memory	Clear sessions: rm ~/.openclaw/agents/main/sessions/sessions.json
Bot only responds in DMs	groupPolicy is allowlist	Set channels.discord.groupPolicy to open
Bot responds to every message	mentionPatterns too broad	Remove patterns, rely on native @mentions
Sessions show "exited" immediately	Agent (Claude Code) won't run as root	Run AO as non-root user

Architecture

Discord message → OpenClaw Gateway → AI Model (with AO tools)
                                          ↓
                                    ao_spawn tool
                                          ↓
                              AO CLI (agent-orchestrator)
                                          ↓
                              Git worktree + Claude Code agent
                                          ↓
                              Branch → Commit → PR

The bot (OpenClaw) is the manager. AO is the workforce. The bot never codes — it uses AO tools to spawn agents that do the actual work.