guanbear 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 |
| 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
- For direct answers, use
reply; do not create work. - For delegated work, call
octoclaw_dispatch; do not hand-write spawn args. - After native spawn is accepted, confirm with
octoclaw_dispatch_confirm. - For status/provenance/follow-up questions, use
octoclaw_statusoroctoclaw_task_action; do not dispatch new work just to explain old work. - Do not call or recreate
octoclaw_spawn. - Do not use completion files, child-finalizer recovery, or JSON delivery outbox as the normal final-delivery mechanism.
- Do not treat
task-state.jsonas durable truth. Missing or corrupt task-state must be rebuilt or reported degraded. - 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_spawnas 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.