中文 | English

📖 README → Getting Started → Core Concepts → Architecture → Customization

Getting Started — From Zero to Multi-Agent Collaboration

This is a complete step-by-step guide. If you just want the quick path, head back to the README's 10-Minute Quickstart.

Prerequisites

Before you begin, make sure:

OpenClaw is installed and working: Running openclaw status shows normal output
A Slack workspace is created: You have admin permissions
Basic command-line skills: You can copy-paste and run commands in a terminal (or have your existing OpenClaw agent do it for you)

Not sure how to install OpenClaw? See the OpenClaw official docs

Phase 1: Slack Setup (~20 minutes)

1.1 If You Haven't Connected Slack to OpenClaw Yet

Follow SLACK_SETUP.md to create a Slack App (Socket Mode) and obtain two tokens:

xapp-... (App-Level Token)
xoxb-... (Bot Token)

Then run:

openclaw channels add --channel slack --app-token "xapp-..." --bot-token "xoxb-..."
openclaw gateway restart

Verify: @mention your bot in any Slack channel. If it replies, you're good.

1.2 Create Agent Channels

Create the following channels in Slack. You can customize the names, but keep them short.

Minimum setup (3 channels):

Channel	Agent	Purpose
`#hq`	CoS (Chief of Staff)	Your primary conversation window. Strategic alignment.
`#cto`	CTO (Technical Co-founder)	Technical direction and task breakdown
`#build`	Builder (Executor)	Implementation and delivery

Recommended additions (add as needed):

Channel	Agent	When to Add
`#invest`	CIO (Domain Expert)	When you need specialized roles for investment, legal, marketing, etc.
`#know`	KO (Knowledge Officer)	When lessons keep getting lost and you keep making the same mistakes
`#ops`	Ops (Operations Officer)	When agent behavior starts drifting off course
`#research`	Research (Researcher)	When you need on-demand research tasks

1.3 Invite the Bot and Record Channel IDs

1. In each channel, type: /invite @your-bot-name
2. Record each channel's Channel ID:
   Right-click the channel name → View channel details → Channel ID at the bottom (starts with C)

All channels should be public — in a single-user workspace there are no privacy concerns, and public channels make auditing and tracking easier.

Phase 2: Deploy OpenCrew Files (~10 minutes)

2.1 Copy Shared Protocols + Workspace Files

Method A: Have your existing OpenClaw agent deploy for you (recommended, zero command-line)

Send the following message to your existing OpenClaw agent:

I want to deploy OpenCrew. Please do the following:

1) Back up ~/.openclaw/openclaw.json (with a timestamp)
2) Copy all .md files from <repo-path>/shared/ to ~/.openclaw/shared/
3) For the cos, cto, and builder agents (minimum setup):
   - Create the ~/.openclaw/workspace-<agent>/memory/ directory
   - Copy files from <repo-path>/workspaces/<agent>/ into it (don't overwrite existing files)
   - Create a symlink: ~/.openclaw/workspace-<agent>/shared → ~/.openclaw/shared
4) Tell me what you did at each step

Boundaries: Do NOT touch my models/auth/gateway configs — only add the OpenCrew increments.

Method B: Manual setup

# 0. Back up
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak-$(date +%Y%m%d%H%M)

# 1. Copy global protocols
mkdir -p ~/.openclaw/shared
cp shared/*.md ~/.openclaw/shared/

# 2. Copy workspaces (minimum 3 agents)
for a in cos cto builder; do
  mkdir -p ~/.openclaw/workspace-$a/memory
  rsync -a --ignore-existing "workspaces/$a/" "$HOME/.openclaw/workspace-$a/"
done

# 3. Symlink shared (so agents can read global protocols)
for a in cos cto builder; do
  if [ ! -e "$HOME/.openclaw/workspace-$a/shared" ]; then
    ln -s "$HOME/.openclaw/shared" "$HOME/.openclaw/workspace-$a/shared"
  fi
done

# 4. Verify
ls ~/.openclaw/workspace-cto/SOUL.md && echo "✅ workspace ready"
ls ~/.openclaw/shared/SYSTEM_RULES.md && echo "✅ shared protocols ready"

2.2 Deploying All 7 Agents

Replace for a in cos cto builder with for a in cos cto builder cio ko ops research, and also run:

# Special subdirectories for KO and CIO
mkdir -p ~/.openclaw/workspace-ko/{inbox,knowledge}
mkdir -p ~/.openclaw/workspace-cto/{scars,patterns}
mkdir -p ~/.openclaw/workspace-cio/{decisions,principles,signals,watchlist}

Phase 3: Write the Configuration (~5 minutes)

3.1 Merge the Minimum Incremental Config

Follow CONFIG_SNIPPET_2026.2.9.md. It includes:

New agents entries (IDs, workspace paths)
Slack channel bindings (Channel ID to Agent)
Slack allowlist (only these channels trigger agents)
A2A safeguards (maxPingPongTurns, initiation permissions, subagent limits)

Key config items explained (so you understand what each one does):

Config Item	Purpose	Why It's Needed
`agents.list`	Registers each agent's ID and workspace	Without this, the agent doesn't exist
`bindings`	Maps Channel ID to Agent	Without this, messages in channels won't be routed to agents
`channels.slack.channels.allowlist`	Only allows specified channels to trigger agents	Prevents the bot from being accidentally triggered in other channels
`maxPingPongTurns = 4`	Caps A2A back-and-forth	Prevents two agents from triggering each other in a message storm
`tools.agentToAgent.allow`	Only CoS/CTO/Ops can initiate A2A	Organizational discipline — not everyone can dispatch tasks
`thread.historyScope = "thread"`	Isolates history within threads	Keeps each task's context separate
`replyToMode = "all"`	All replies go into threads	Keeps channels clean and uncluttered

3.2 Token Security

Important: Do not hardcode Slack tokens in config files.

Recommended approach:

Local development: Use a ~/.openclaw/.env file (permissions set to 600)
Production: Use Bitwarden Secrets Manager or an equivalent tool

# Create .env
touch ~/.openclaw/.env
chmod 600 ~/.openclaw/.env

# Write tokens (replace with your actual values)
echo 'SLACK_APP_TOKEN=xapp-1-your-token' >> ~/.openclaw/.env
echo 'SLACK_BOT_TOKEN=xoxb-your-token' >> ~/.openclaw/.env

3.3 Restart

openclaw gateway restart
openclaw status

Phase 4: Verification (~5 minutes)

Basic Verification

Test 1: Send a message in #hq → CoS replies → ✅
Test 2: Send a message in #cto → CTO replies → ✅
Test 3: In #cto, ask CTO to dispatch a task to Builder
        → A thread appears in #build → Builder replies in the thread → ✅

A2A Verification (already covered if Test 3 passed)

In #cto, tell the CTO: "Have Builder write a hello world script." Watch for:

CTO creates a root message in #build (the A2A anchor)
Builder replies and executes within that thread
CTO syncs Builder's progress back in #cto

If all of the above works, congratulations — your multi-agent system is up and running! 🎉

Troubleshooting

Bot Not Responding

Check	Command
Is the gateway online?	`openclaw gateway status`
Is the bot invited to the channel?	Check the channel's member list
Is the Channel ID correct?	Compare the ID in your config with the one in Slack
requireMention setting	`#ops` requires @mention by default

not_in_channel Error

The bot hasn't been invited to the target channel. Run /invite @your-bot-name in the channel.

Target Agent Doesn't Reply After A2A Dispatch

This is a known issue (KNOWN_ISSUES.md P1). Current best practices:

Confirm the target agent's channel ID and binding are correct
Check that sessions_send's sessionKey includes the correct thread ts
If it happens intermittently, the agent usually recovers on the next message

Variable Expansion Issues in zsh

In zsh, $variable inside double quotes gets expanded. Use single quotes around arguments containing $.

Permission Denied

# Check directory permissions
ls -la ~/.openclaw/
# Fix
sudo chown -R $USER:$USER ~/.openclaw/

Quick Reference: Common Commands

# System status
openclaw status
openclaw gateway status
openclaw gateway restart

# Agent management
openclaw agents list

# Config queries
openclaw config get agents
openclaw config get slack.channels

# Logs
openclaw logs tail -f

What to Do After Deployment

Run with 3 agents for a few days — get a feel for the collaboration rhythm
Watch for Closeout output — are CTO and Builder writing structured summaries?
Add KO/Ops as needed — when you notice lessons getting lost or agent behavior drifting
Read Core Concepts — understand the system's operating logic in depth
Read Development Journey — learn the "why" behind each design decision

📖 Next → Core Concepts · Architecture · Customize Your Agents

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Getting Started — From Zero to Multi-Agent Collaboration

Prerequisites

Phase 1: Slack Setup (~20 minutes)

1.1 If You Haven't Connected Slack to OpenClaw Yet

1.2 Create Agent Channels

1.3 Invite the Bot and Record Channel IDs

Phase 2: Deploy OpenCrew Files (~10 minutes)

2.1 Copy Shared Protocols + Workspace Files

2.2 Deploying All 7 Agents

Phase 3: Write the Configuration (~5 minutes)

3.1 Merge the Minimum Incremental Config

3.2 Token Security

3.3 Restart

Phase 4: Verification (~5 minutes)

Basic Verification

A2A Verification (already covered if Test 3 passed)

Troubleshooting

Bot Not Responding

not_in_channel Error

Target Agent Doesn't Reply After A2A Dispatch

Variable Expansion Issues in zsh

Permission Denied

Quick Reference: Common Commands

What to Do After Deployment

FilesExpand file tree

GETTING_STARTED.md

Latest commit

History

GETTING_STARTED.md

File metadata and controls

Getting Started — From Zero to Multi-Agent Collaboration

Prerequisites

Phase 1: Slack Setup (~20 minutes)

1.1 If You Haven't Connected Slack to OpenClaw Yet

1.2 Create Agent Channels

1.3 Invite the Bot and Record Channel IDs

Phase 2: Deploy OpenCrew Files (~10 minutes)

2.1 Copy Shared Protocols + Workspace Files

2.2 Deploying All 7 Agents

Phase 3: Write the Configuration (~5 minutes)

3.1 Merge the Minimum Incremental Config

3.2 Token Security

3.3 Restart

Phase 4: Verification (~5 minutes)

Basic Verification

A2A Verification (already covered if Test 3 passed)

Troubleshooting

Bot Not Responding

not_in_channel Error

Target Agent Doesn't Reply After A2A Dispatch

Variable Expansion Issues in zsh

Permission Denied

Quick Reference: Common Commands

What to Do After Deployment