# Octoclaw

> Routes agent turns through policy-based delegation, runtime status, and feedback loops using a TypeScript-first runtime layer for OpenClaw.

- Skill: `guanbear/octoclaw` (Agent Skill, multi-file: 17 files)
- Install (CLI): `npx skillmds add guanbear/octoclaw`
- Raw SKILL.md: https://api.skillmd.com/api/skills/guanbear/octoclaw/raw
- Safety review: CAUTION (external: skill-scanner PASS, skillspector WARNING)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools, DevOps & Infra, Deployment & Release, Dev Tooling
- Tags: Delegation, Openclaw, Policy, Router, Runtime, Sqlite, Typescript, Workcontract
- Author: guanbear (https://skillmd.com/u/guanbear)
- Updated: 2026-08-22
- Page: https://skillmd.com/skills/guanbear/octoclaw

---


# OctoClaw Runtime Skill

This skill describes the current `v0.6.0` runtime line. It intentionally does
not describe the old Python `octoclaw_spawn.py`, completion-file finalizer, or
JSON delivery-outbox runtime. Those were historical mechanisms and must not be
reintroduced as compatibility paths.

## Current Authority

| Layer | Authority |
|------|-----------|
| live route | `reply | delegate` only |
| execution lifecycle | OpenClaw native TaskFlow / `sessions_spawn` / native announce |
| OctoClaw metadata | SQLite runtime ledger: WorkContract, route seal, native refs, spawn intent, audit events |
| status display | generated projection from metadata + native lifecycle |
| `task-state.json` | rebuildable read-model cache, not truth |
| replay log | observability and evaluation evidence, not runtime truth |

## Main-Agent Rules

1. For direct answers, use `reply`; do not create work.
2. For delegated work, call `octoclaw_dispatch`; do not hand-write spawn args.
3. After native spawn is accepted, confirm with `octoclaw_dispatch_confirm`.
4. For status/provenance/follow-up questions, use `octoclaw_status` or
   `octoclaw_task_action`; do not dispatch new work just to explain old work.
5. Do not call or recreate `octoclaw_spawn`.
6. Do not use completion files, child-finalizer recovery, or JSON delivery
   outbox as the normal final-delivery mechanism.
7. Do not treat `task-state.json` as durable truth. Missing or corrupt
   task-state must be rebuilt or reported degraded.
8. Do not inject raw child transcripts into the parent context.

## Tool Use

| Tool | Use |
|------|-----|
| `octoclaw_route_hint` | Ask the runtime for route guidance before model/tool escalation. |
| `octoclaw_policy_decide` / `octoclaw_route` | Resolve policy and route facts. |
| `octoclaw_dispatch` | Create a WorkContract-backed delegation plan and native spawn intent. |
| `octoclaw_dispatch_confirm` | Bind accepted native `runId` / `childSessionKey` evidence back to OctoClaw metadata. |
| `octoclaw_task_action` | Read task details, queue, artifacts, or supported task operations. |
| `octoclaw_status` | Render status/details/queue/timeline from projection. |

## Auto Router Commands

| Command | Use |
|---------|-----|
| `octoclawctl router wizard [--incremental] [--config answers.json]` | Create or update local router plan/budget/privacy/language/restricted/same-provider config. |
| `octoclawctl router promotion review [--input shadow.jsonl]` | Evaluate local shadow samples and append promotion decisions. |
| `octoclawctl router decisions [--since 7d]` | Inspect shadow-to-live promotion decisions. |
| `octoclawctl router cost report [--period 7d]` | Review local cost grouped by model, complexity, and route, including prediction and budget status. |
| `octoclawctl router cost budget set --monthly <usd>` | Store the local monthly router budget. |
| `octoclawctl router score override <model> <tier>=<score>` | Override a model score for a complexity tier. |
| `octoclawctl router model mark <model> --dispreferred-for <tier>` | Soft-avoid a model for a tier. |
| `octoclawctl router model ban <model> --for <tier>` | Hard-exclude a model for a tier. |

## Delegation Contract

Delegated work must carry:

- WorkContract id and route seal.
- scope and allowed tools.
- role / worker-pool / model profile metadata.
- native spawn intent id.
- accepted native refs after confirm.
- status projection derived from native lifecycle and OctoClaw metadata.

`spawnExecuted=true` requires accepted native run evidence. A child session key by
itself is only a reference; it is not execution proof.

## Status Questions

These are status-surface requests, not new work:

- "OctoClaw status"
- "task status"
- "which task is running?"
- "why did it not dispatch?"
- "who handled the previous task?"
- "show queue/details/timeline"

Answer through `octoclaw_status` or `octoclaw_task_action`. If no verifiable
record exists, say that clearly and do not invent a task.

## Current Docs

- `README.md` / `README.zh-CN.md`: operator-facing overview.
- `docs/octoclaw-architecture-map-2026-05-09.md`: detailed module graph.
- `docs/octoclaw-ts-rebuild-design-v2.md`: architecture baseline.
- `docs/octoclaw-runtime-convergence-cleanup-plan-2026-05-07.md`: runtime cleanup handoff.
- `docs/octoclaw-repo-debt-cleanup-plan-2026-05-09.md`: archive/version/terminology cleanup.
- `docs/archive/`: historical material only.

## Forbidden Legacy Paths

Do not reintroduce these as product runtime behavior:

- `octoclaw_spawn` as a public tool or alias.
- plugin `runtime.subagent.run()` fallback.
- fake detached runtime capability registration.
- child completion files as normal final protocol.
- child-finalizer recovery loop.
- JSON delivery outbox for new planner/native runtime tasks.
- resident runner / tmux / ClawTeam as required substrate.