refactor: alias ClawTeam CLI usage to 'oh' and update config for multi-agent coordination

2026-04-03 11:24:09 +07:00
parent e9fd48950c
commit e9a3a623a5
12 changed files with 563 additions and 124 deletions
@@ -13,7 +13,7 @@ description: >
  single agent can efficiently handle alone. Provides comprehensive guidance for
  using the ClawTeam CLI to orchestrate multi-agent teams with task management,
  messaging, monitoring, runtime profiles, git context, and recovery tooling.
-version: 0.3.1
+version: 0.4.0
 ---

 # ClawTeam Multi-Agent Coordination
@@ -22,7 +22,9 @@ ClawTeam is a framework-agnostic CLI tool for coordinating multiple AI agents as
 It provides team/task management, inter-agent messaging, git worktree isolation, provider-aware
 runtime profiles, git context injection, snapshots, and terminal-based monitoring dashboards.

-All operations are performed via the `clawteam` CLI. Data is stored in `~/.clawteam/` by default.
+All operations are performed via the `oh` CLI (shorthand for `clawteam`). Data is stored in `~/.clawteam/` by default.
+
+**Official repo:** https://github.com/HKUDS/ClawTeam

 ## Installation

@@ -35,9 +37,9 @@ Requires Python 3.10+. For P2P transport support: `pip install clawteam[p2p]`.
 ## Prerequisites

 - `tmux` installed (default spawn backend)
- A CLI coding agent such as `openclaw`
+- A CLI coding agent such as `openclaw`, `claude`, `codex`
 - A git repository for worktree isolation and context features
- Default dependencies installed if you want the TUI wizard (`clawteam profile wizard`)
+- Default dependencies installed if you want the TUI wizard (`oh profile wizard`)

 ## Core Concepts

@@ -65,91 +67,97 @@ export CLAWTEAM_AGENT_ID="leader-001"
 export CLAWTEAM_AGENT_NAME="leader"
 export CLAWTEAM_AGENT_TYPE="leader"

-clawteam team spawn-team my-team -d "Project team" -n leader
-clawteam task create my-team "Design system" -o leader
-clawteam task create my-team "Implement feature" -o worker1
-clawteam task create my-team "Write tests" -o worker2
-clawteam board show my-team
+oh team spawn-team my-team -d "Project team" -n leader
+oh task create my-team "Design system" -o leader
+oh task create my-team "Implement feature" -o worker1
+oh task create my-team "Write tests" -o worker2
+oh board show my-team
 ```

 ### Configure Runtime Profiles

 ```bash
 # Inspect built-in provider templates
-clawteam preset list
-clawteam preset show moonshot-cn
+oh preset list
+oh preset show moonshot-cn

 # Generate a reusable profile from a preset
-clawteam preset generate-profile moonshot-cn claude --name claude-kimi
+oh preset generate-profile moonshot-cn claude --name claude-kimi

 # Or use the interactive TUI
-clawteam profile wizard
+oh profile wizard

 # Claude Code on a fresh machine/home may need onboarding repair once
-clawteam profile doctor claude
+oh profile doctor claude

 # Smoke-test the profile before using it in a team
-MOONSHOT_API_KEY=... clawteam profile test claude-kimi
+MOONSHOT_API_KEY=... oh profile test claude-kimi
 ```

 ### Spawn and Coordinate Agents

+> **⚠️ CRITICAL for OpenClaw environments:** `oh spawn` defaults to `claude` as backend+command. ALWAYS explicitly specify `tmux openclaw`:
+> ```bash
+> oh spawn tmux openclaw --team <team> --agent-name <name> --task "..."
+> ```
+
 ```bash
-# Default path: tmux backend, claude command, git worktree isolation, skip-permissions on
-clawteam spawn --team my-team --agent-name worker1 --task "Implement the auth module"
-clawteam spawn --team my-team --agent-name worker2 --task "Write unit tests"
+# ✅ CORRECT for OpenClaw — ALWAYS use tmux openclaw
+oh spawn tmux openclaw --team my-team --agent-name worker1 --task "Implement the auth module"
+oh spawn tmux openclaw --team my-team --agent-name worker2 --task "Write unit tests"

-# Explicit backend and command
-clawteam spawn tmux claude --team my-team --agent-name worker3 --task "Build API endpoints"
-clawteam spawn subprocess claude --team my-team --agent-name worker4 --task "Run linting"
+# With non-default provider/model via profile
+oh spawn tmux --profile claude-kimi --team my-team --agent-name worker5 --task "Build API endpoints"

-# Recommended for non-default providers/models
-clawteam spawn tmux --profile claude-kimi --team my-team --agent-name worker5 --task "Build API endpoints"
-clawteam spawn subprocess --profile gemini-vertex --team my-team --agent-name worker6 --task "Run linting"
+# ❌ WRONG — will fail, defaults to claude
+oh spawn --team my-team --agent-name worker1 --task "..."
+oh spawn tmux claude --team my-team --agent-name worker1 --task "..."

-clawteam board attach my-team
-clawteam inbox send my-team worker1 "Start implementing the auth module"
-clawteam board live my-team --interval 3
+oh board attach my-team
+oh inbox send my-team worker1 "Start implementing the auth module"
+oh board live my-team --interval 3
 ```

 ### Spawn Defaults

 | Setting | Default | Override |
 |---------|---------|----------|
-| Backend | `tmux` | `clawteam spawn subprocess ...` |
-| Command | `claude` | `clawteam spawn tmux my-cmd ...` |
+| Backend | `tmux` | `oh spawn subprocess ...` |
+| Command | `claude` (default) / `openclaw` (ours) | `oh spawn tmux openclaw` for our setup |
 | Workspace | `auto` (git worktree) | `--no-workspace` or config `workspace=never` |
 | Permissions | skip | `--no-skip-permissions` or config `skip_permissions=false` |
 | Runtime profile | none | `--profile <name>` |

+> **Important:** For OpenClaw setups, use `oh spawn tmux openclaw` — NOT `oh spawn` (default=claude).
+
 Use `--profile` whenever you need a non-default provider, model, endpoint, or auth mapping.

 ### Task Lifecycle

 ```bash
 # Create with dependencies
-clawteam task create my-team "Deploy" --blocked-by <impl-task-id>,<test-task-id>
+oh task create my-team "Deploy" --blocked-by <impl-task-id>,<test-task-id>

 # Create with priority
-clawteam task create my-team "Hotfix prod issue" --priority high
+oh task create my-team "Hotfix prod issue" --priority high

 # Update status
-clawteam task update my-team <task-id> --status in_progress
-clawteam task update my-team <task-id> --status completed
+oh task update my-team <task-id> --status in_progress
+oh task update my-team <task-id> --status completed

 # Filter tasks
-clawteam task list my-team --status blocked
-clawteam task list my-team --owner worker1
-clawteam task list my-team --priority high
+oh task list my-team --status blocked
+oh task list my-team --owner worker1
+oh task list my-team --priority high
 ```

 ### Waiting for Sub-Agents

 ```bash
-clawteam task wait my-team
-clawteam task wait my-team --timeout 300 --poll-interval 10
-clawteam task wait my-team --agent coordinator
-clawteam --json task wait my-team --timeout 600
+oh task wait my-team
+oh task wait my-team --timeout 300 --poll-interval 10
+oh task wait my-team --agent coordinator
+oh --json task wait my-team --timeout 600
 ```

 ### Worker Loop Protocol
@@ -158,13 +166,13 @@ Workers should not stop after completing the initial `--task`. The expected loop

 ```bash
 # 1. Check tasks assigned to you
-clawteam task list my-team --owner worker1
+oh task list my-team --owner worker1

 # 2. Finish any pending work, then check for new instructions
-clawteam inbox receive my-team --agent worker1
+oh inbox receive my-team --agent worker1

 # 3. If idle, notify the leader and keep monitoring for follow-ups
-clawteam lifecycle idle my-team
+oh lifecycle idle my-team
 ```

 Repeat the loop until the leader explicitly shuts the worker down.
@@ -172,9 +180,9 @@ Repeat the loop until the leader explicitly shuts the worker down.
 ### Git Context and Conflict Checks

 ```bash
-clawteam context log my-team
-clawteam context conflicts my-team
-clawteam context inject my-team --agent worker1
+oh context log my-team
+oh context conflicts my-team
+oh context inject my-team --agent worker1
 ```

 Use these before reassigning work, continuing another worker's task, or merging overlapping changes.
@@ -182,16 +190,16 @@ Use these before reassigning work, continuing another worker's task, or merging
 ### Snapshots and Recovery

 ```bash
-clawteam team snapshot my-team --tag before-refactor
-clawteam team snapshots my-team
-clawteam team restore my-team --snapshot before-refactor
+oh team snapshot my-team --tag before-refactor
+oh team snapshots my-team
+oh team restore my-team --snapshot before-refactor
 ```

 ### Activity Visualization

 ```bash
-clawteam board gource my-team --log-only
-clawteam board gource my-team --live
+oh board gource my-team --log-only
+oh board gource my-team --live
 ```

 Prefer `--log-only` in headless environments.
@@ -232,9 +240,9 @@ Configure non-default providers through `profile` + `preset` instead of hardcodi
 All commands support `--json` for machine-readable output. Put the flag before the subcommand:

 ```bash
-clawteam --json team discover
-clawteam --json board show my-team
-clawteam --json task list my-team --status pending
+oh --json team discover
+oh --json board show my-team
+oh --json task list my-team --status pending
 ```

 ## Important Notes
@@ -244,15 +252,15 @@ clawteam --json task list my-team --status pending
 - Completing a task auto-unblocks tasks that list it in `blockedBy`.
 - Tasks also support `priority`; use `high` for urgent unblockers and production fixes.
 - Workers are expected to keep polling tasks/inbox after the first task instead of exiting immediately.
- `clawteam spawn` defaults to tmux, git worktree isolation, and skip-permissions.
- `clawteam launch` also respects `skip_permissions`, so template workers no longer stall on approval prompts.
+- `oh spawn` defaults to tmux, git worktree isolation, and skip-permissions.
+- `oh launch` also respects `skip_permissions`, so template workers no longer stall on approval prompts.
 - All file writes use atomic tmp+rename to prevent corruption.
- Identity env vars are set automatically when spawning via `clawteam spawn`.
+- Identity env vars are set automatically when spawning via `oh spawn`.
 - Use `board attach <team>` to watch all agents in a tiled tmux layout.
 - `board show` JSON and the browser board now include message history with member-aware aliases, which is useful for inbox triage and handoffs.
 - Prefer `--profile` for non-default providers/models instead of manually exporting provider env vars.
 - `profile` is the final runtime object; `preset` is a reusable template for generating profiles.
- For Claude Code on a fresh machine/home, run `clawteam profile doctor claude` once before spawning.
+- For Claude Code on a fresh machine/home, run `oh profile doctor claude` once before spawning.
 - `context inject` and `context conflicts` are the recommended way to hand off cross-worktree tasks safely.

 ## Additional Resources