yeachan-heo--oh-my-claudecode/docs/OPENCLAW-ROUTING.md

OpenClaw / Clawhip Routing Contract

This document defines the normalized event contract OMC emits through the OpenClaw bridge for native Clawhip-style consumers.

Goals

• Keep the raw hook event (event) for backward compatibility.
• Add a normalized signal object for routing and dedupe-friendly filtering.
• Make command/native gateways receive the same logical payload shape as HTTP gateways.

Payload shape

HTTP gateways receive JSON with this structure:

{
  "event": "post-tool-use",
  "instruction": "...",
  "timestamp": "2026-03-09T00:00:00.000Z",
  "sessionId": "...",
  "projectPath": "...",
  "projectName": "...",
  "tmuxSession": "...",
  "tmuxTail": "...",
  "signal": {
    "kind": "test",
    "name": "test-run",
    "phase": "failed",
    "routeKey": "test.failed",
    "priority": "high",
    "toolName": "Bash",
    "command": "pnpm test",
    "testRunner": "package-test",
    "summary": "FAIL src/example.test.ts | ..."
  },
  "context": {
    "sessionId": "...",
    "projectPath": "...",
    "toolName": "Bash"
  }
}

signal contract

Field	Meaning
kind	Routing family: session, tool, test, pull-request, question, keyword
name	Stable logical signal name
phase	Lifecycle phase: started, finished, failed, idle, detected, requested
routeKey	Canonical routing key for downstream consumers
priority	high for operational signals, low for generic tool noise

Additional fields may appear when applicable:

• toolName
• command
• testRunner
• prUrl
• summary

Native command gateway contract

Command gateways now get the same normalized payload through both:

• template variable: {{payloadJson}}
• env var: OPENCLAW_PAYLOAD_JSON

They also receive convenience env vars:

• OPENCLAW_SIGNAL_ROUTE_KEY
• OPENCLAW_SIGNAL_PHASE
• OPENCLAW_SIGNAL_KIND

That lets native Clawhip routing consume one contract whether the transport is HTTP or shell-command based.

Current high-priority route keys

• session.started
• session.finished
• session.idle
• question.requested
• test.started
• test.finished
• test.failed
• pull-request.started
• pull-request.created
• pull-request.failed
• tool.failed

Generic tool.started / tool.finished remain available as low-priority fallback signals.

Noise reduction

• AskUserQuestion now emits only the dedicated question.requested signal instead of also emitting generic tool lifecycle events.
• OpenClaw now collapses repeated attached-tmux lifecycle bursts before dispatching them to downstream native gateways.
  • session-start collapses on {projectPath, tmuxSession} for a short burst window.
  • keyword-detector (the UserPromptSubmit bridge surface) collapses prompt-submitted bursts on {projectPath, tmuxSession, normalized prompt}.
  • stop / session-end collapse on {projectPath, tmuxSession} for a short burst window.
• Consumers should prefer signal.priority === "high" or explicit signal.routeKey filters instead of routing directly on raw hook names.

Stability notes

• Raw event names are preserved for backward compatibility.
• signal is the preferred routing surface for new native Clawhip integrations.
• context remains a whitelisted subset; internal raw tool input/output are used only to derive normalized signals and are not forwarded in payload.context.