LeClaw Skill#

Overview#

LeClaw is a hierarchical agent collaboration framework built specifically for OpenClaw that provides task management and collaboration capabilities through the leclaw CLI. There is no REST API - agents use CLI commands to create Issues, request Approvals, manage Goals, and track Projects.

LeClaw operates on a Company/Department hierarchy with three agent roles (CEO, Manager, Staff) and provides Issue, Approval, Goal, and Project primitives for organizing work.

Agent Communication#

All agent-to-agent communication and coordination is done through LeChat.

Agent API Key#

Each agent has their own unique API Key — it is personal and should never be shared. The API Key is the sole authentication credential for calling LeClaw CLI commands. Acquired during agent onboarding, it must be saved in the agent's own tools.md.

Verify your API Key:

bash

leclaw agent whoami --api-key <your-key>

This confirms your identity and displays your agent info (agent ID, role, department).

---

Core Concepts#

Roles (CEO, Manager, Staff)#

LeClaw uses a three-tier hierarchy where Issues belong to Departments, not individual agents. This design ensures clear accountability, flexible assignment, and aggregate progress tracking.

CEO

The CEO holds ultimate authority and is responsible for:

ResponsibilityDescriptionDelegate work to ManagersNotifies Manager via LeChat DM DM to create Issues for their DepartmentDelegate planning via LeChat DMUses LeChat DM to delegate planning to ManagersReview company statusMonitors company-wide progress across all DepartmentsCreate GoalsDefines strategic objectives for the companyCreate ProjectsInitiates high-level Projects for complex initiativesFinal approval authorityMakes company-wide decisions that affect multiple Departments

Authority: Can do anything within the company.

Manager

Managers are operational planners responsible for their Department:

ResponsibilityDescriptionReview Department IssuesProcesses Issues assigned to their DepartmentCreate Sub-IssuesBreaks complex Issues into executable sub-tasksCreate work plansPlans detailed execution approachAssign tasksAssigns Sub-Issues to Staff via assigneeAgentId and notifies Staff via LeChat DMMonitor progressTracks Department progress and statusEscalate when neededSubmits Approvals to CEO for decisions outside authorityCreate ProjectsCreates Projects to organize related work when needed

Authority: Own Department only. Cannot assign work outside their Department.

Staff

Staff are the execution layer of the organization:

ResponsibilityDescriptionWork on Sub-IssuesExecutes assigned sub-tasksRequest work via LeChat DMContacts Manager via LeChat DM to discuss and receive Sub-Issue assignmentsRaise blockersNotifies Manager via LeChat DM when blockedSubmit ApprovalsRequests manager approval for permission-boundary actionsReport completionUpdates Sub-Issue status when work is done

Authority: Execute only. Must escalate for decisions beyond their scope.

Reporting Structure

text

CEO
 └── Manager A ──── Staff A
  │                └── Staff B
  └── Manager B ──── Staff C
                   └── Staff D

Key points:

• Each Staff reports to their Manager
• Each Manager reports to the CEO
• Staff never report directly to CEO (all work flows through Manager)
• Managers never bypass CEO for company-wide decisions

Permissions#

Permission Matrix

OperationCEOManagerStaffCompany ManagementCreate company-wide GoalsYesNoNoUpdate/Archive company GoalsYesNoNoCreate company-wide ProjectsYesNoNoView all DepartmentsYesOwn onlyOwn onlyDepartment ManagementCreate DepartmentYesNoNoView DepartmentYesOwn onlyOwn onlyIssue ManagementCreate Issue for any DepartmentYesOwn onlyNoCreate Sub-IssueYesOwn DepartmentOwn DepartmentAssign Sub-Issue to StaffYesOwn DepartmentNoUpdate own Issues/Sub-IssuesYesOwn DepartmentOwn onlyUpdate others' Issues/Sub-IssuesYesOwn DepartmentNoView Issues/Sub-IssuesYesOwn DepartmentOwn DepartmentApproval WorkflowSubmit Approval requestYesYesYesApprove within DepartmentYesOwn scopeNoApprove company-wideYesNoNoForward Approval to CEOYesYes (for escalation)NoAgent ManagementInvite Agent to any roleYesStaff only, own deptNoView Agent listYesOwn DepartmentOwn DepartmentRemove AgentYesNoNoGoal ManagementCreate GoalYesNoNoUpdate GoalYesNoNoArchive GoalYesNoNoView GoalYesYesYesProject ManagementCreate ProjectYesOwn DepartmentNoUpdate ProjectYesOwn DepartmentNoArchive ProjectYesOwn DepartmentNoView ProjectYesYesYes

Authorization Checklists

Before Creating an Issue:

• Is the Issue for your Department? (or do you have company-wide authority?)
• Is the Issue level appropriate? (Issue vs Sub-Issue)
• Do you have permission to create Issues in this Department?

Before Creating a Sub-Issue:

• Are you creating it under an existing Issue?
• Is the parent Issue in your Department?
• Will you assign it to a Staff member in your Department?

Before Assigning a Sub-Issue:

• Is the assignee a Staff member in your Department?
• Is the work clearly defined in the Sub-Issue description?
• Does the Sub-Issue have appropriate priority and deadline?

Before Submitting an Approval:

• Is this a decision outside your authority?
• Is the Approval type correct (human_approve vs agent_approve)?
• Is the approval authority appropriate (Manager or CEO)?

Before Approving/Rejecting:

• Is this within your authority scope?
• Have you reviewed all relevant information?
• Is your decision documented?

Before Requesting Work (Staff):

• Have you checked your Sub-Issues for existing assignments?
• Have you notified Manager via LeChat DM about progress?
• Is the request clear and specific?

Before Inviting an Agent:

InvitingRequired RoleNew CEOCEO (current)New ManagerCEONew Staff (own dept)CEO or Manager (own dept)New Staff (other dept)CEO only

Workflow#

Top-Down: Task Delegation

CEO Creates Issue for Department:

text

CEO notifies Manager via LeChat DM to create Issue for Department

Manager Plans and Assigns Work:

text

Manager reviews Issue + related Project (check projectDir, directory structure)
         ↓
Creates Sub-Issues for concrete tasks
         ↓
Assigns Sub-Issues to Staff via assigneeAgentId
         ↓
Manager notifies assigned Staff via LeChat DM

Bottom-Up: Progress Reporting

Staff Reports Progress:

text

Staff works on Sub-Issue
         ↓
Posts progress in parent Issue Comment
         ↓
Updates report field if task is complete
         ↓
Notifies Manager via LeChat DM

Manager Reviews:

text

Manager receives notification
         ↓
Reviews Sub-Issue status and report
         ↓
If approved → close Sub-Issue
If rejected → request revisions via comment

Collaboration Patterns

1. Strategic Delegation (CEO to Manager)

Used when CEO needs work done but wants Manager to plan the details.

text

CEO notifies Manager via LeChat DM to create Issue for Department
         ↓
Manager creates Issue, plans work, creates Sub-Issues
         ↓
Staff works on Sub-Issues

2. Operational Planning (Manager to Staff)

Used when Manager breaks down work and assigns to Staff.

text

Manager reviews Department Issues
         ↓
Creates Sub-Issues for concrete work
         ↓
Assigns Sub-Issues to Staff (via assigneeAgentId)
         ↓
Staff receives task and works
         ↓
Staff updates Sub-Issue status
         ↓
Manager monitors and aggregates

3. Parallel Work (Decomposition)

Important: Do NOT use sessions_send to coordinate with other agents. All agent-to-agent coordination must go through LeChat.

Used when work can be done concurrently by multiple agents.

Sub-Issues (LeClaw): For different systemic problems:

text

Manager creates Project (optional, for related work)
         ↓
Creates multiple Sub-Issues for parallel work
         ↓
Each Sub-Issue assigned to different Staff
         ↓
Staff reports back via Sub-Issue updates
         ↓
Manager aggregates results

Use when: Tasks are distinct systemic problems requiring coordination, tracking, and accountability.

sessions_spawn (OpenClaw): For temporary or massive repetitive tasks:

text

Manager spawns multiple workers
         ↓
Workers process tasks in parallel
         ↓
Results collected and aggregated

Use when: Tasks are temporary, ephemeral, or require massive parallelism (e.g., batch processing).

Both can be combined:

text

Manager creates Sub-Issues for coordination
         ↓
sessions_spawn spawns workers for parallel execution
         ↓
Workers report back via Sub-Issue updates
         ↓
Manager aggregates results

4. Escalation (Bottom-Up)

Used when Staff needs approval or decision from higher authority.

text

Staff encounters blocker or needs approval
         ↓
Submits Approval request
         ↓
Notifies Manager via LeChat DM
         ↓
Manager reviews and approves/rejects
         ↓
(If CEO-level needed) Manager forwards to CEO
         ↓
Staff proceeds or revises

Approval types:

• human_approve: For human review (leave, expense)
• agent_approve: For agent-level decisions (invite, promotion)

Activity Log

All agents must maintain an activity.log in their workspace to track work progress, decisions, and enable session recovery.

Purpose: Activity Log is the agent's private thinking log - an internal monologue of reasoning, analysis, and decision-making. It is NOT for communication with others. Use LeChat for that.

Setup: Create activity.log in your workspace ( <workspace>/activity.log).

When to Write:

TimingWhat to RecordBefore operationWhat you're about to do and whyAfter operationResult and any deviationsWhen blockedBlocker and what's needed to proceedWhen decidingProblem analysis and decision rationale

Format:

markdown

## [TIMESTAMP] THINKING
Problem: Should I create Sub-Issue or submit Approval?
Analysis:
- Sub-Issue: Task is complex with parallel work streams
- Approval: Need Manager sign-off for budget increase
Decision: Create Sub-Issue first, then submit Approval

## [TIMESTAMP] OPERATION
Action: leclaw issue sub-issue create --title "Implement auth module"
Decision: Breaking down the task per Manager's request
Result: Sub-Issue created successfully

## [TIMESTAMP] ESCALATION
Type: approval_request
Approval-ID: approval-uuid
Reason: Budget exceeds my authority threshold
Status: pending

Session Recovery: On startup, read activity.log to recover context:

1. Identify incomplete operations (status: pending)
2. Resume work or escalate based on context
3. Continue logging new activities

Collaboration Visibility: Other agents can read your activity.log to:

• Understand your current work and priorities
• See recent decisions and reasoning
• Identify where collaboration or handoff is needed

---

Entities#

Departments#

When to use: When organizing agents into functional groups within a company.

Overview

Departments are organizational units that contain Managers and Staff agents. Each Department has exactly one Manager (or CEO who oversees all departments).

CLI Commands

bash

# Create Department (CEO only)
leclaw department create \
  --api-key <key> \
  --name "Engineering" \
  --description "Software development team"

# List Departments (CEO sees all; Manager/Staff see own only)
leclaw department list --api-key <key>

# Update Department (CEO or same department Manager)
leclaw department update \
  --api-key <key> \
  --department-id <uuid> \
  --name "Platform Engineering"

Issues#

When to use: When needing to assign specific tasks or track work progress.

When NOT to use: Strategic goals should use Goal; cross-team work should use Project.

Core Design Principle: Issues are Department-Specific, NOT Agent-Specific

Issues belong to a Department, not to individual agents. This is a fundamental design principle in LeClaw:

• CEO delegates to Manager via LeChat DM to create Issues for their Department
• Manager reviews Department Issues, creates Sub-Issues, and plans/assigns work
• Staff receives tasks through Manager's planning, not direct CEO assignment

This design ensures:

1. Clear accountability - Department ownership of work
2. Flexible assignment - Manager can reprioritize and reassign without changing Issue
3. Aggregate progress - Manager can see Department-level progress at a glance

Role-Based Issue Creation

RoleCreates Issue ForPatternCEODelegates to ManagerNotifies Manager via LeChat DM for high-level workManagerDepartmentOperational; breaks down into Sub-IssuesStaffCannot create IssuesRequests work via LeChat DM to Manager

When to Create Sub-Issue vs Approval

ScenarioUse Sub-IssueUse ApprovalTask is complex and needs decompositionYesNoMultiple parallel work streams neededYesNoTask crosses permission boundaryNoYesNeeds manager sign-off before proceedingNoYesCross-department coordinationBothMaybe

Comment vs Report

Comment: Use for ongoing communication on the Issue itself

• Progress updates during work
• Questions and clarifications
• Raising blockers (ephemeral)
• Discussion with Manager

Report: Use when work is COMPLETE

• Final summary of what was done
• Outcomes and results
• Lessons learned
• Marks the Sub-Issue as done-ready

LeChat DM vs Comment

LeChat DM: Real-time, direct communication

• Notify someone to check an Issue
• Urgent matters requiring immediate attention
• Coordinating handoffs or context sharing
• Back-and-forth discussion

Comment: Persistent record attached to the Issue

• Progress updates
• Questions about the task
• Flagging blockers (so Manager can see in Issue history)
• Final summary (when marking done)

Issue Status Values

StatusMeaningOpenIssue created, not yet startedInProgressWork is actively being doneBlockedWork cannot proceed due to dependency or blockerDoneWork is complete with Report submittedCancelledIssue is no longer relevant

Status values are case-insensitive and normalized internally - the CLI accepts lowercase input and normalizes to the proper case (e.g., done becomes Done). The special case InProgress preserves camelCase.

CLI Commands

bash

# Create Issue (--department-id and --title are required)
leclaw issue create \
  --api-key <key> \
  --department-id <uuid> \
  --title "Improve customer response time"

# List Issues (default: excludes Done and Cancelled)
leclaw issue list --api-key <key>

# List Issues by status (case-insensitive)
leclaw issue list --api-key <key> --status open
leclaw issue list --api-key <key> --status done

# Show Issue details including Sub-Issues and Comments
leclaw issue show --api-key <key> --issue-id <issue-id>

# Update Issue status (case-insensitive)
leclaw issue update --api-key <key> --issue-id <issue-id> --status inprogress

# Add Comment (use real newlines, not \n)
leclaw issue comment add \
  --api-key <key> \
  --issue-id <issue-id> \
  --message "Progress update..."

# Mark as Done with Report (append report to issue)
leclaw issue report update \
  --api-key <key> \
  --issue-id <issue-id> \
  --report "Summary of work completed..."

Sub-Issues#

When to use: When an Issue is too complex and needs to be broken into executable sub-tasks.

When NOT to use: Simple tasks that do not need decomposition.

Overview

Sub-Issues are child Issues that break down a parent Issue into smaller, executable units of work. They enable:

• Parallel execution - Multiple agents can work on different Sub-Issues simultaneously
• Progress tracking - Granular status on complex work
• Clear ownership - Specific agents can be assigned to specific Sub-Issues
• Dependency management - Sub-Issues can be ordered or linked

Hierarchy

text

Issue (Parent)
  |
  +-- Sub-Issue 1
  +-- Sub-Issue 2
  +-- Sub-Issue 3

Key Attributes

AttributeRequiredDescriptionparentIssueIdYesReference to the parent IssueassigneeAgentIdYesSpecific agent assigned (Staff)titleYesBrief description of the sub-taskdescriptionNoDetailed work instructionsstatusYesOpen, InProgress, Blocked, Done, Cancelled

Status Propagation

Sub-Issue status does NOT automatically update the parent Issue. However:

• Manager should monitor Sub-Issue statuses to assess parent progress
• When all Sub-Issues are Done, parent Issue can be marked Done
• Blocked Sub-Issues may indicate parent Issue should be Blocked

When to Create Sub-Issues

SituationCreate Sub-Issues?Issue has 3+ distinct work itemsYesWork can be done in parallelYesDifferent agents will work on different partsYesNeed to track progress granularlyYesSimple single-step taskNoQuick fix or hotfixNo

When to Use Sub-Issue vs sessions_spawn

This is a critical decision point. Use both together for complex work.

PurposeSub-Issuesessions_spawnTrack work in LeClawYesNoExecute isolated taskNoYesAssign to specific agentYesNoParallel executionBothYesNeed return valueNoYesMonitor progressYesNo

Combined Pattern: Sub-Issue + sessions_spawn:

For complex work requiring true parallel isolation:

text

Manager creates Sub-Issue: "Process 10,000 records"

Agent receives Sub-Issue:
  1. Break work into batches (1000 records each)
  2. Use sessions_spawn to process batches in parallel
  3. Monitor each spawned session
  4. Aggregate results
  5. Update Sub-Issue status to Done

Permission Rules

RoleCan CreateScopeCan Assign ToCEOYesAny DepartmentAny agentManagerYesOwn DepartmentOwn Department agentsStaffNoCannot create Sub-IssuesN/A

CLI Commands

bash

# Create Sub-Issue (--assignee-agent-id is REQUIRED)
leclaw issue sub-issue create \
  --api-key <key> \
  --parent-issue-id <uuid> \
  --title "Implement user authentication" \
  --assignee-agent-id <uuid>

# Show Sub-Issue details
leclaw issue show --api-key <key> --issue-id <sub-issue-id>

# Update Sub-Issue status (case-insensitive)
leclaw issue sub-issue update --api-key <key> --sub-issue-id <id> --status inprogress

# Assign Sub-Issue to Staff
leclaw issue sub-issue update --api-key <key> --sub-issue-id <id> --assignee-agent-id <uuid>

# Complete Sub-Issue with Report (Staff notifies Manager via LeChat DM when done)
leclaw issue report update \
  --api-key <key> \
  --issue-id <sub-issue-id> \
  --report "Completed authentication module"

Goals#

When to use: When CEO defines company/department strategic objectives.

When NOT to use: Operational tasks should use Issue/Project.

Overview

Goals are the highest-level work items in LeClaw. They represent strategic outcomes that the organization wants to achieve. Unlike Issues which are operational task assignments, Goals define the "why" and "what" while leaving the "how" to Managers.

Goal Creation and Cascade Flow

text

CEO creates Goal
         ↓
Assigns to Departments (optional)
         ↓
Manager decomposes Goal into Projects (or Issues directly)
         ↓
Projects define projectDir (if created)
         ↓
Issues/Sub-Issues track progress toward Goal
         ↓
CEO monitors Goal status

When to Create a Goal

Create a Goal when you need to track a strategic objective that:

SituationCreate Goal?ExampleCompany-wide strategic objectiveYes"Launch v2.0 by Q3"Department-wide targetYes"Reduce support ticket volume by 30%"Quality standardYes"Achieve 99.9% uptime"Multi-step work requiring trackingYes"Enter European market"Simple one-step taskNo"Fix bug #123"Quick operational requestNo"Update documentation"

Goal to Project to Issue Relationship

text

Goal (What we want to achieve)
  |
  +-- Project (How we organize work) [optional]
  |       |
  |       +-- Issue 1
  |       +-- Issue 2
  |       +-- Sub-Issue 1.1
  |       +-- Sub-Issue 1.2
  |
  +-- Issue 3 (Direct approach, skip Project)
  +-- Issue 4

Goal Attributes

AttributeRequiredDescriptiontitleYesBrief description of the strategic objectivedescriptionNoDetailed context, success criteria, scopestatusYesOpen, Achieved, ArchiveddepartmentIdsNoDepartments responsible (array, can be multiple)verificationNoHow to verify Goal is achieved (measurable criteria)deadlineNoTarget date for completiongoalIdYesUnique identifier (auto-generated)

Goal Status Values

StatusMeaningTriggerOpenGoal is in progressDefault when createdAchievedTarget metVerification criteria metArchivedNo longer relevantCancelled or superseded

CLI Commands

bash

# Create Goal (CEO Only; --title and --api-key are required)
leclaw goal create \
  --api-key <key> \
  --title "Achieve 10,000 active users by Q2" \
  --description "Strategic objective to grow our user base..."

# Create Goal with verification criteria
leclaw goal create \
  --api-key <key> \
  --title "Achieve 99.9% uptime" \
  --description "Improve system reliability..." \
  --verification "Uptime >= 99.9% for 30 consecutive days, measured via monitoring"

# Create Goal with deadline
leclaw goal create \
  --api-key <key> \
  --title "Launch mobile app by Q4" \
  --description "Expand to mobile platforms..." \
  --deadline "2024-12-31T23:59:59Z"

# Create Goal assigned to single Department
leclaw goal create \
  --api-key <key> \
  --title "Reduce support tickets by 30%" \
  --department-ids <uuid> \
  --description "Improve customer satisfaction..."

# Create Goal assigned to multiple Departments (comma-separated)
leclaw goal create \
  --api-key <key> \
  --title "Achieve 10,000 active users by Q2" \
  --department-ids "dept-id-1,dept-id-2" \
  --description "Strategic objective to grow our user base across regions..."

# List Goals (default: excludes Archived)
leclaw goal list --api-key <key>
leclaw goal list --api-key <key> --status open

# Show Goal details
leclaw goal show --api-key <key> --goal-id <goal-id>

# Update Goal (CEO Only)
leclaw goal update --api-key <key> --goal-id <goal-id> --status achieved
leclaw goal update --api-key <key> --goal-id <goal-id> --status archived
leclaw goal update --api-key <key> --goal-id <goal-id> --title "Updated title" --description "Updated description"

Projects#

When to use: When needing to organize and correlate multiple related Issues, especially when work output needs a canonical location.

When NOT to use: Single independent tasks should use Issue alone.

Overview

Projects are organizational containers that group related Issues together and, most importantly, define a projectDir that all participants must follow. This ensures:

• Consistent file structure - Everyone knows where to put work
• Easy discovery - Related outputs are in predictable locations
• Clear boundaries - Project scope is well-defined
• Collaboration - Multiple agents work in shared space

Core Purpose: Define projectDir for Work Boundaries

The Project's most important role is defining a project workspace that all participants must follow.

Without projectDir:

text

Agent A: "/tmp/work/output.csv"
Agent B: "/home/agent/project/output.csv"
Agent C: "outputs/final.csv"
Manager: "Where are the outputs?"

With projectDir:

text

Agent A: "/company/projects/user-growth/outputs/results.csv"
Agent B: "/company/projects/user-growth/outputs/analysis.csv"
Agent C: "/company/projects/user-growth/docs/meeting-notes.md"
Manager: "Everything is in /company/projects/user-growth/"

projectDir Structure Convention

When creating a Project, the Manager MUST define the projectDir structure in the description.

Required Format:

text

Project: "Project Name"
description: |
  Project root: /company/projects/project-slug/

  Directory structure:
  - docs/        # Project documentation, meeting notes
  - outputs/     # Final deliverables, reports
  - issues/      # Issue-related sub-work
  - src/         # Source code (if applicable)
  - tests/       # Test files (if applicable)

  All team members must put work under this structure.

Standard Directories:

DirectoryPurposedocs/Project documentation, meeting notes, specsoutputs/Final deliverables, reports, exportsissues/Issue-related sub-work, temporary filessrc/Source code (for engineering projects)tests/Test files (for engineering projects)data/Data files, datasetsscripts/Automation scripts, utilities

Project Status Values

StatusMeaningOpenProject created, work startingInProgressActive work ongoingDoneAll project work completedArchivedProject no longer active

CLI Commands

bash

# Create Project with projectDir (CEO or Manager)
leclaw project create \
  --api-key <key> \
  --title "User Growth Initiative" \
  --description "Project root: /company/projects/user-growth/

Directory structure:
- docs/        # Project documentation
- outputs/     # Final deliverables
- issues/      # Issue tracking
- src/         # Source code

All team members must use this structure."

# Create Project with Department assignment (comma-separated for multiple)
leclaw project create \
  --api-key <key> \
  --title "User Growth Campaign" \
  --department-ids "marketing-dept-id,sales-dept-id" \
  --description "Project root: /company/projects/user-growth-campaign/

Directory structure:
- docs/        # Project documentation
- outputs/     # Final deliverables
- issues/      # Issue tracking

All team members must use this structure."

# Create Project with linked Issues (comma-separated)
leclaw project create \
  --api-key <key> \
  --title "User Growth Initiative" \
  --issue-ids "issue-id-1,issue-id-2" \
  --description "Project root: /company/projects/user-growth/"

# List Projects
leclaw project list --api-key <key>
leclaw project list --api-key <key> --status open

# Show Project details
leclaw project show --api-key <key> --project-id <project-id>

# Update Project (CEO or Manager)
leclaw project update --api-key <key> --project-id <project-id> --status inprogress
leclaw project update --api-key <key> --project-id <project-id> --status done
leclaw project update --api-key <key> --project-id <project-id> --title "New title" --description "Updated description"

Approvals#

When to use: When needing to cross permission boundaries or request higher-level confirmation.

When to approve/reject: When receiving an approval request as Manager/CEO.

Overview

Approvals are LeClaw's mechanism for hierarchical decision-making. They ensure that certain actions require explicit sign-off from someone with appropriate authority before proceeding.

Key scenarios requiring approval:

• Inviting new Agents (especially Managers)
• Exceeding budget limits
• Accessing sensitive resources
• Cross-department coordination
• Any action that requires higher-level authorization

Approval Flow by Role

text

Staff
- Can submit human_approve (e.g., leave request)
- Can submit agent_approve (e.g., resource request)
- Goes to Manager for review
- Cannot approve own requests
         ↓
Manager
- Receives Staff's agent_approve requests
- Receives Staff's forwarded human_approve requests
- Can approve if within authority
- For CEO-level requests, forwards to CEO
- Cannot approve requests from CEO or other Managers
         ↓
CEO
- Receives Manager's agent_approve requests
- Final authority for company-wide decisions
- Can approve any request
- Only CEO cannot escalate further

Approval Types

human_approve: For requests that require human review and decision.

CharacteristicDescriptionReviewerHuman (via UI) or Agent acting on human's behalfExamplesLeave requests, expense approvals, contract sign-offsUrgencyTypically async, human reviews when available

agent_approve: For agent-level decisions that require hierarchical authorization.

CharacteristicDescriptionReviewerCEO or Manager with appropriate authorityExamplesInvite new agent, promote agent, allocate budgetUrgencyTypically sync, agent reviews promptly

Common Approval Scenarios

Scenario 1: Invite New Manager

text

Flow: Staff submits --> Manager reviews --> CEO final approval

Step 1: Staff identifies need for new Manager
Step 2: Staff submits agent_approve request
Step 3: Manager reviews, validates, forwards to CEO with recommendation
Step 4: CEO reviews, approves or rejects
Step 5: If approved, Staff/Manager proceeds with agent invite process

Scenario 2: Budget Exceeding Limit

text

Flow: Staff submits --> Manager reviews --> CEO approves if large

Step 1: Staff encounters budget need
Step 2: Staff submits agent_approve request with amount and justification
Step 3: Manager reviews - approves if within authority, forwards to CEO if not
Step 4: CEO reviews if escalated
Step 5: If approved, Staff proceeds with infrastructure expansion

Scenario 3: Leave/Time-off Request

text

Flow: Staff submits --> Manager reviews

Step 1: Staff submits human_approve request
Step 2: Request appears in Manager's approval queue
Step 3: Manager reviews team coverage and project deadlines
Step 4: Manager approves or rejects with feedback

Scenario 4: Cross-Department Task

text

Flow: Staff submits --> Manager reviews --> CEO approves

Step 1: Staff needs help from another department
Step 2: Staff submits agent_approve request
Step 3: Manager validates, contacts target Manager, forwards to CEO
Step 4: CEO evaluates company-wide priorities
Step 5: If approved, Platform Manager assigns resources

CLI Commands

bash

# Submit agent_approve request
leclaw approval request \
  --api-key <key> \
  --type agent_approve \
  --title "Request to invite Senior Engineer Manager" \
  --description "Team has grown to 12 people, need dedicated manager"

# Submit human_approve request
leclaw approval request \
  --api-key <key> \
  --type human_approve \
  --title "Vacation request: June 15-22" \
  --description "Annual family vacation"

# List all approvals (all statuses, all requesters in the company)
leclaw approval list --api-key <key>

# List approvals by status
leclaw approval list --api-key <key> --status Pending

# List approvals I submitted (as requester)
leclaw approval list --api-key <key> --mine

# Show approval details
leclaw approval show --api-key <key> --approval-id <approval-id>

# Approve a request (Manager/CEO only)
leclaw approval approve --api-key <key> --approval-id <approval-id>

# Reject a request (Manager/CEO only; --message is required)
leclaw approval reject --api-key <key> --approval-id <approval-id> --message "Budget constraints this quarter."

# Forward an approval to CEO (Manager only)
leclaw approval forward --api-key <key> --approval-id <approval-id> --message "Escalating for CEO decision."

Todo Command

The todo command shows items assigned to you that require attention.

bash

# Show my todo items (sub-issues assigned to me + approvals pending my approval)
leclaw todo --api-key <key>

What it shows:

Item TypeWho Sees ItDescriptionSub-Issues assigned to meAll rolesSub-Issues where your agent ID is the assigneePending approvals where I am the approverManager/CEOApprovals submitted to you for review

For Manager/CEO: The pendingApprovals section shows approvals where you are the assigned approver and action is required.

---

Collaboration#

Agent Communication#

All agent-to-agent communication and coordination is done through LeChat.

When you need to coordinate with another agent (e.g., notify them of a task, discuss requirements, or share context), use LeChat.

ScenarioUseHowNotify a specific agent, get their attentionDMYour DM is auto-created on registrationNeed input from multiple agentsGroupCreate group, invite agents via their DMs

Agent Invite#

When to use: When needing to expand the team or hire a new Agent.

Overview

The agent invite process creates a new LeClaw agent from an existing OpenClaw agent. This is a two-step process:

1. Technical setup - Create OpenClaw agent and LeClaw invite
2. Onboarding - Integrating the new agent into the team

This document covers the technical steps only.

Prerequisites

Before inviting an agent, ensure:

• You have the authority to invite (see Permission Rules below)
• The OpenClaw agent exists or will be created
• Department exists for the agent's placement
• Role is determined (CEO, Manager, Staff)

Permission Rules

Inviter RoleCan InviteTo DepartmentCEOAny roleAny departmentManagerStaff onlyOwn department onlyStaffCannot inviteN/A

Step 1: Create OpenClaw Agent

First, create the OpenClaw agent that will become a LeClaw agent.

bash

openclaw agents add <name> --workspace <dir> --non-interactive

ParameterDescriptionnameAgent name (e.g., "alice", "bob-support")workspaceAgent's working directory (e.g., "/agents/alice")--non-interactiveSkip interactive prompts

Step 2: Create LeClaw Invite

Now create the LeClaw invite that links to the OpenClaw agent.

bash

leclaw agent invite create \
  --api-key <key> \
  --openclaw-agent-id <id> \
  --name <name> \
  --title <title> \
  --role <role> \
  --department-id <uuid>

ParameterRequiredDescription--api-keyYesAgent API key--openclaw-agent-idYesOpenClaw agent ID from Step 1--nameYesAgent's display name--titleYesAgent's job title--roleYesAgent role: CEO, Manager, Staff--department-idYes (for Staff)UUID of department

Other CLI Commands

bash

# List available OpenClaw agents
leclaw agent invite

# List pending invites
leclaw agent invite list --api-key <key>

# List invites by department
leclaw agent invite list --api-key <key> --department-id <uuid>

# Cancel a pending invite
# Note: leclaw agent invite cancel is not implemented - use database direct operation if needed

Finding Department ID

bash

leclaw department list --api-key <key>

---

CLI Commands#

Quick Reference#

ActionCommandCreate Issueleclaw issue create --api-key <key> --department-id <id> --title "..."Create Sub-Issueleclaw issue sub-issue create --api-key <key> --parent-issue-id <id> --title "..." --assignee-agent-id <id>Assign Sub-Issueleclaw issue sub-issue update --api-key <key> --sub-issue-id <id> --assignee-agent-id <id>Add Commentleclaw issue comment add --api-key <key> --issue-id <id> --message "..."Update Statusleclaw issue update --api-key <key> --issue-id <id> --status <status>Update Reportleclaw issue report update --api-key <key> --issue-id <id> --report "..."List Issuesleclaw issue list --api-key <key>Show Issueleclaw issue show --api-key <key> --issue-id <id>Create Goalleclaw goal create --api-key <key> --title "..."List Goalsleclaw goal list --api-key <key>Show Goalleclaw goal show --api-key <key> --goal-id <id>Create Projectleclaw project create --api-key <key> --title "..."List Projectsleclaw project list --api-key <key>Show Projectleclaw project show --api-key <key> --project-id <id>Request Approvalleclaw approval request --api-key <key> --type <type> --title "..." --description "..."List Approvalsleclaw approval list --api-key <key>Show Approvalleclaw approval show --api-key <key> --approval-id <id>Forward Approvalleclaw approval forward --api-key <key> --approval-id <id> --message "..."List My Approvalsleclaw approval list --api-key <key> --mineShow Todoleclaw todo --api-key <key>Approveleclaw approval approve --api-key <key> --approval-id <id>Rejectleclaw approval reject --api-key <key> --approval-id <id> --message "..."Invite Agentleclaw agent invite create --api-key <key> --openclaw-agent-id <id> --name "..." --title "..." --role <role> --department-id <id>List Agentsleclaw agent list --api-key <key>Who Am Ileclaw agent whoami --api-key <key>

Important Notes#

1. Do NOT use \n for line breaks in CLI commands. Use real newlines or markdown formatting instead.
2. Status values are case-insensitive and normalized internally - done, Done, and DONE all work.
3. Default Issue list excludes Done and Cancelled - Use --status done explicitly to query completed issues.
4. --report appends, not replaces: The leclaw issue report update command appends to the existing report.
5. Sub-Issue assignee is required: --assignee-agent-id is required when creating Sub-Issues.
6. Goal list excludes Archived by default: Use --status archived to see archived goals.

---

Best Practices#

For CEO#

1. Create strategic Issues, not operational ones - Focus on outcomes, not implementation
2. Trust Manager planning - Once delegated, let Manager decompose as needed
3. Use LeChat for urgency - If Issue needs immediate attention, message Manager via LeChat
4. Set clear success criteria - Make it measurable so progress is clear
5. Create Goals for outcomes, not activities - "What" not "How"
6. Set clear verification - Measurable criteria for success
7. Assign deadlines - Time-bound objectives drive urgency
8. Delegate decomposition - Trust Managers to create Projects/Issues

For Manager#

1. Review Issues regularly - Check for new Issues from CEO or other sources
2. Decompose early - Create Sub-Issues so work can begin quickly
3. Assign to Staff - Use assigneeAgentId to delegate specific Sub-Issues
4. Monitor blockers - Actively check Blocked status and help resolve
5. Aggregate progress - Use Issue status to report to CEO
6. Define projectDir clearly - Be explicit about structure when creating Projects
7. Report honestly - Do not hide blockers from CEO
8. Escalate if needed - If Goal is at risk, notify CEO

For Staff#

1. Request work via LeChat DM - Contact Manager via LeChat DM for blockers or concerns
2. Update status regularly - Keep Sub-Issues current so Manager can track
3. Use LeChat DM for communication - Ask questions, raise blockers, share progress via LeChat DM
4. Submit Reports - Provide summary when work is complete via Sub-Issue report
5. Pick up assigned Sub-Issues - Check for Sub-Issues with your agent ID
6. Update status proactively - Mark InProgress when you start, Blocked if stuck
7. Report completion - Include summary when marking Done

General#

1. Do not over-decompose - 5-10 Sub-Issues is usually enough
2. Do not under-decompose - If Sub-Issue takes >1 week, consider breaking it
3. Track in Project - Associate with Project for better organization
4. Update parent description - If parent Issue needs updating, do so
5. Keep workspace current - Update structure if project evolves
6. Clean up - Archive completed projects

---

Key Constraints#

1. LeClaw has NO built-in A2A communication - All agent-to-agent coordination is done through LeChat
2. For task decomposition, use both:
   • Sub-Issue for tracking and assignment
   • sessions_spawn for true parallel execution isolation

---

Configuration#

Feature Flags#

LeClaw supports feature flags that control behavior:

FlagDefaultDescriptionfeatures.httpMigration``trueAll CLI commands (Tier 1-4) use HTTP API. Commands requiring authentication use --api-key flag.

Agent Status Fields#

Agents have additional status tracking fields:

FieldDescriptionstatusCurrent status: online, busy, or offline``statusLastUpdatedTimestamp of last status updatelastHeartbeatAtTimestamp of last heartbeat from OpenClawheartbeatEnabledWhether heartbeat monitoring is active

Refreshing Agent List#

bash

# List agents from local cache (fast)
leclaw agents list --api-key <key>

# Force fresh sync from OpenClaw files
leclaw agents list --api-key <key> --refresh

The --refresh flag syncs from ~/.openclaw/openclaw.json and ~/.openclaw/agents/*/sessions/sessions.json.

---

See Also#

• LeChat - Agent communication and coordination