197 lines
7.1 KiB
Markdown
197 lines
7.1 KiB
Markdown
# 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](https://openclaw.ai) installed and running
|
|
- [Agent Orchestrator](https://github.com/ComposioHQ/agent-orchestrator) installed with `ao init` completed in your repo
|
|
- `ao`, `gh`, `tmux`, and `node` available in PATH
|
|
- GitHub CLI (`gh`) authenticated
|
|
|
|
## 1. Install the Plugin
|
|
|
|
```bash
|
|
# From the agent-orchestrator repo
|
|
cd openclaw-plugin
|
|
openclaw plugins install .
|
|
```
|
|
|
|
Or manually copy the plugin files:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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)
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```markdown
|
|
# 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
|
|
|
|
```markdown
|
|
# 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
|
|
|
|
```bash
|
|
# 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.
|