中文 | English
README > Getting Started > Core Concepts > Architecture > Customization
This page brings together all of OpenCrew's key mechanisms in one place. You don't need to read it all at once -- come back whenever you hit a concept you don't understand.
This is the most fundamental mapping in OpenCrew. Understand this, and everything else falls into place.
A channel is a role. Each Slack channel corresponds to an Agent's "workstation." Want to talk to the CTO? Go to #cto. Want the Builder to do something? Start a thread in #build.
A thread is a task. One thread = one task = one independent session. Context is fully isolated between threads. You can have multiple threads running in the same channel (i.e., multiple tasks in parallel).
Unreads are your to-do list. Slack's unread messages automatically become your decision queue -- which threads have updates, which Agents are waiting for your confirmation. Open your phone and see it all at a glance.
| Slack Feature | Meaning in OpenCrew |
|---|---|
| Channel | Agent's role |
| Thread | Independent task / session |
| Unreads / Later | Your decision queue |
| Root message | Task anchor (ensures A2A visibility) |
| Mobile app | Spare moments = management time |
Agents don't need to ask you about everything. The Autonomy Ladder defines "when should an Agent act on its own, and when must it come to you."
| Level | Meaning | Agent Behavior | Example |
|---|---|---|---|
| L0 | Suggest only | Takes no action | "I suggest doing X -- confirm and I'll proceed" |
| L1 | Reversible ops | Acts directly | Write drafts, do research, organize docs, edit code |
| L2 | Impactful but rollbackable | Acts, then writes Closeout | Open PRs, modify config files, write investment analysis |
| L3 | Irreversible ops | Must get your confirmation | Publish releases, execute transactions, delete data, send externally |
Design principle: L1/L2 proceed autonomously by default; L3 always requires human confirmation. This lets Agents maximize output within safe boundaries while handing you control at critical moments.
Each Agent's SOUL.md specifies its autonomy boundaries. For example, Builder:
Can do directly: write code, open PRs, run tests
Must confirm: merge to main, publish releases, delete branches
Different types of tasks require different levels of rigor. QAPS tells Agents "how thorough do I need to be for this task."
| Type | Full Name | Characteristics | Output Requirements | Typical Scenario |
|---|---|---|---|---|
| Q | Query | One-off question | No Closeout needed | "What is Socket Mode?" |
| A | Artifact | Small task with a deliverable | Must Closeout | "Write me an API doc" |
| P | Project | Multi-step, may span days | Task Card + Checkpoint + Closeout | "Migrate the database schema" |
| S | System | System-level change | Ops Review + Closeout + rollback plan | "Modify an Agent's SOUL.md" |
Why classify? If every task followed the same process, small questions would be over-handled (waste) and big problems would be under-handled (risk). QAPS matches "level of rigor" to "task importance."
By default, all Agents in OpenCrew share a single Slack bot identity -- the bot ignores its own messages (to prevent self-loops). This means Agents cannot directly talk to each other in Slack.
Give a few Agents their own independent Slack App, then invite them into other Agents' channels for direct @mention conversations:
Independent Slack App Shared Slack App (existing)
┌──────────────┐ ┌─────────────────┐
│ Orchestrator │ │ Default-Bot │
└──────┬───────┘ └───┬───┬───┬─────┘
│ │ │ │
Channels: #home #cto #build #cto #build #invest ...
──────────────────────────────────────────────────
Agents: Orch ← collaborates → CTO Builder CIO ...
Not every Agent needs its own App -- execution-layer Agents keep sharing. Only cross-domain Agents (like the Orchestrator) get their own App. You can watch the discussion in Slack in real-time and intervene at any point.
Borrows a core insight from Anthropic's Harness Design:
- When an AI both executes and does QA, it goes easy on its own mistakes
- When an AI both plans and executes, it tends to cut corners
Separating "thinking" and "doing" into different Agents -- Orchestrator handles planning and evaluation, Worker handles implementation -- is the most effective lever for solving AI self-evaluation failure.
You → @Orchestrator: "Discuss approach X"
Phase 0: Orchestrator creates DISCUSSION SPEC (goals + acceptance criteria)
Round 1: Orchestrator → @Worker: question
Worker → @Orchestrator: answer
Round 2: Orchestrator evaluates → continue / terminate
...
Termination: ✅ criteria met | ⚠️ max rounds | 🔄 no progress → DISCUSSION_CLOSE
| Layer | Mechanism | Scope | Type |
|---|---|---|---|
| Config | requireMention: true |
Channel root messages | Hard constraint |
| Prompt | Explicit @mention protocol | Within threads | Soft constraint |
In threads, requireMention is bypassed by implicitMention (once a bot has participated, it's always true). So each participating Agent also needs prompt rules: check for explicit <@MyBotID> in the message text, respond NO_REPLY if absent.
| Platform | A2A v2 (Native Collaboration) |
|---|---|
| Slack | ✅ Verified |
| Discord | ❌ OpenClaw code-level bug (#11199, #45300) |
| Feishu | ❌ Platform limitation (bot messages not delivered to other bots) |
Discord/Feishu users needing Agent collaboration can refer to
shared/A2A_PROTOCOL.mdAppendix C (legacy Delegation mode).
For detailed setup guide, see Discussion Mode Setup Guide. Full protocol in shared/A2A_PROTOCOL.md.
After every A/P/S task is completed, the executor must write a 10-15 line Closeout:
CLOSEOUT A | Implement rate limiting | 20260210
---
## What was done
- Added Token Bucket rate limiting to API gateway
- Test coverage at 89%
## Key decisions
1. Chose Token Bucket over Sliding Window (reason: simpler in distributed scenarios)
2. Limit set to 100 req/sec per IP (based on capacity model)
## Pitfalls
- Redis sync latency caused race condition -> switched to in-memory + graceful degradation
## Signal: 3 (general technical pattern, worth distilling)
Why Closeouts?
- Information compression: 50K tokens of conversation -> 1-2K summary (~25x compression)
- KO only reads Closeouts, not massive conversations
- You only need to read Closeouts to know what happened
For P-type tasks that span multiple days, write one at the end of each day or at each key milestone:
CHECKPOINT P | Database migration | 20260210 | Progress: 40%
---
Completed: ✅ schema design ✅ test environment setup
In progress: 🔄 data migration script (50%)
Blocked: ⚠️ awaiting DBA approval (expected 2/12)
How does experience go from "chat logs" to "organizational assets"? Through three layers of filtering:
Layer 0: Raw conversation
| Fully retained for audit, not directly reused
|
v Closeout compression (~25x)
|
Layer 1: Closeouts (structured summaries)
| Output from all A/P/S tasks
| Signal score 0-3
|
v KO distillation (only Signal >= 2 enters)
|
Layer 2: Abstract knowledge
|-- Principles: "In scenario X, you should do Y"
|-- Patterns: "The general solution for this type of problem is Z"
+-- Scars: "Never do W, because..."
Not every Closeout deserves a spot in the knowledge base. Signal scoring acts as the filter:
| Score | Meaning | How It's Handled |
|---|---|---|
| 0 | One-off fix, no reuse value | Agent keeps internally |
| 1 | Useful in specific scenarios, hard to generalize | Agent keeps internally |
| 2 | Likely reusable by other tasks | KO distills -> knowledge base |
| 3 | General pattern, applicable across domains | KO prioritizes -> knowledge base |
Each Agent's workspace is its "brain":
| File | Purpose | Read Priority | Update Frequency |
|---|---|---|---|
| SOUL.md | Role definition, core principles, autonomy boundaries | Highest (must read on startup) | Very low |
| AGENTS.md | Workflows, task processing logic | High | Medium |
| USER.md | User profile: preferences, style, constraints | Medium | Low |
| MEMORY.md | Long-term memory: stable preferences, principles, lessons | Medium | Medium |
| IDENTITY.md | Name, emoji, one-line positioning | Low | Very low |
| TOOLS.md | Tool and environment configuration | Low | Low |
| TASKS.md | Current task board | On demand | High |
| HEARTBEAT.md | Periodic check-in checklist | On demand | On demand |
Key design: SOUL.md is read first, ensuring "who you are" takes priority over "how you work." Separating role definition from operational process (SOUL vs AGENTS) prevents procedural details from diluting role identity.
The shared/ directory holds the "employee handbook" shared by all Agents -- unified protocols and templates that prevent each Agent from writing its own version and drifting apart.
| File | Content |
|---|---|
SYSTEM_RULES.md |
Autonomy Ladder + QAPS + artifact requirements |
A2A_PROTOCOL.md |
Native Agent collaboration protocol (independent Bot + @mention) |
TASK_PROTOCOL.md |
Task classification and handling standards |
CLOSEOUT_TEMPLATE.md |
Closeout template |
CHECKPOINT_TEMPLATE.md |
Checkpoint template |
OPS_REVIEW_PROTOCOL.md |
Five-dimension audit for S-type changes |
KNOWLEDGE_PIPELINE.md |
Knowledge distillation pipeline |
SUBAGENT_PACKET_TEMPLATE.md |
Task packet template for spawning sub-tasks |
SELF_UPDATE_TEMPLATE.md |
Agent self-iteration record template |
These files are not decorative documentation -- they are referenced by each Agent's AGENTS.md as part of its workflow. Critical constraints also sink down to the OpenClaw configuration layer (hard constraints > soft constraints).
Some rules rely on "Agents following them voluntarily" (document layer). Others are enforced directly in configuration (config layer). The latter is more reliable.
| Constraint | Type | Config Key | Why It's Needed |
|---|---|---|---|
| Bot message visibility | Hard | allowBots: true |
Prerequisite for Agent collaboration |
| Explicit trigger | Hard | requireMention: true |
Prevent channel root message dual-trigger |
| Sub-Agent permission | Hard | tools.subagents.tools.deny |
Sub-Agents cannot spawn further |
| Channel isolation | Hard | groupPolicy = "allowlist" |
Only respond in allowed channels |
| Thread isolation | Hard | historyScope = "thread" |
Each thread is an independent session |
| Reply mode | Hard | replyToMode = "all" |
Replies automatically go into threads |
| Multi-account safety | Hard | accounts.default must be declared |
Prevent main bot disconnection |
Practical advice: If a constraint can go into config, don't just put it in documentation. Document-layer rules can be "forgotten" by Agents. Config-layer rules cannot be bypassed.
You (decision-maker)
|
|-- Converse in Slack channels (= roles)
| +-- Each thread (= task) is an independent session
|
|-- Agents progress autonomously per the Autonomy Ladder
| +-- L1/L2 act directly, L3 asks for your confirmation
|
|-- Tasks are classified and handled via QAPS
| +-- Q gets lightweight handling; A/P/S require Closeout
|
|-- Agents collaborate via A2A native collaboration
| +-- Independent Bot + @mention protocol [Verified]
|
+-- Knowledge accumulates through three-layer distillation
+-- Conversation -> Closeout -> KO abstract knowledge
Next steps: Architecture Deep Dive | Customize Your Agents | Known Issues