dr-claw

name	dr-claw
description	Dr. Claw skill for OpenClaw project discovery, idea intake, waiting-session triage, structured session control, event-driven notifications, and mobile reporting through the local drclaw CLI.

Dr. Claw for OpenClaw

Use this skill when OpenClaw needs to operate Dr. Claw from chat or mobile, especially for:

• listing Dr. Claw projects
• finding sessions waiting for response
• replying into a session on the user's behalf
• continuing, approving, rejecting, retrying, or resuming workflows
• creating a new project from a fresh idea
• generating daily or per-project digests
• consuming stable openclaw.* JSON schema payloads
• running the background event-driven watcher daemon

Preconditions

Before running Dr. Claw commands:

$DRCLAW_BIN server status

If the server is not running:

$DRCLAW_BIN server on

Assume the local wrapper exports these defaults when OpenClaw runs the skill:

DRCLAW_BIN="${DRCLAW_BIN:-$(which drclaw)}"
DRCLAW_URL=http://localhost:3001

When invoking the CLI from OpenClaw, prefer $DRCLAW_BIN --url "$DRCLAW_URL" ... instead of relying on PATH.

Core operating rule

Prefer direct CLI facts over model guesses. For stateful operations, return the raw CLI result first, then summarize for the user.

When a command returns JSON, prefer the top-level openclaw field over scraping the raw natural-language reply.

Formal schema contract:

cat "$(git rev-parse --show-toplevel)/agent-harness/cli_anything/drclaw/SCHEMA.md"

When calling OpenClaw locally from automation or shell, use:

./scripts/openclaw_drclaw_turn.sh

This serializes openclaw agent --local calls per agent and avoids session-lock collisions.

Project discovery

List projects:

$DRCLAW_BIN --url "$DRCLAW_URL" projects list

Inspect the latest message in a project:

$DRCLAW_BIN --url "$DRCLAW_URL" projects latest <project> --json

Inspect project progress and next actions:

$DRCLAW_BIN --url "$DRCLAW_URL" projects progress <project> --json

Create a new empty project workspace:

$DRCLAW_BIN --url "$DRCLAW_URL" projects create /absolute/path/to/project --name "Display Name" --json

Create a new project from a fresh idea and immediately start discussion:

$DRCLAW_BIN --url "$DRCLAW_URL" projects idea /absolute/path/to/project --name "Display Name" --idea "<idea text>" --json

Use projects idea for the “I suddenly have an idea” flow.

Session lookup and waiting triage

List known sessions for one project:

$DRCLAW_BIN --url "$DRCLAW_URL" chat sessions --project <project> --json

List waiting sessions across all projects or one project:

$DRCLAW_BIN --url "$DRCLAW_URL" chat waiting --json
$DRCLAW_BIN --url "$DRCLAW_URL" chat waiting --project <project> --json

For session replies and workflow actions, use the embedded openclaw.turn.v1 payload to decide:

• whether user input is required
• which quick action to render next
• whether the session is still processing

Recommended triage flow:

1. Resolve the project first if needed.
2. Use chat waiting --json to find actionable sessions.
3. Use chat sessions --project ... --json when the user wants more detail.

Replying to an existing session

Once the user chooses a session:

$DRCLAW_BIN --url "$DRCLAW_URL" chat reply --project <project> --session <session-id> \
  --bypass-permissions --attach /path/to/file -m "<message>" --json

Note: Always use --bypass-permissions in automation to avoid being blocked by server-side tool approval requests.

Timeout & Heartbeat: If you omit --timeout, the CLI will wait indefinitely (with a 1-hour safety cap) and use heartbeat detection. This is preferred for complex tasks like Task 10 that run experiments.

If a specific provider (like Codex) is failing, add --provider gemini to the command to switch.

Immediately after replying, check whether the session is still processing:

$DRCLAW_BIN --url "$DRCLAW_URL" chat waiting --project <project> --json

If you need to wait until the session leaves the waiting list, use:

./scripts/drclaw_wait_until_clear.sh --project <project> --session <session-id>

The script returns JSON indicating whether the session cleared or timed out.

Workflow control

Use these commands for workflow actions:

$DRCLAW_BIN --url "$DRCLAW_URL" workflow status --project <project> --json
$DRCLAW_BIN --url "$DRCLAW_URL" workflow continue --project <project> --session <session-id> --bypass-permissions -m "<instruction>" --json
$DRCLAW_BIN --url "$DRCLAW_URL" workflow approve --project <project> --session <session-id> --json
$DRCLAW_BIN --url "$DRCLAW_URL" workflow reject --project <project> --session <session-id> -m "<reason>" --json
$DRCLAW_BIN --url "$DRCLAW_URL" workflow retry --project <project> --session <session-id> --json
$DRCLAW_BIN --url "$DRCLAW_URL" workflow resume --project <project> --session <session-id> --bypass-permissions --json

For project-level UI cards or voice summaries, prefer the embedded openclaw.project.v1 payload from:

$DRCLAW_BIN --url "$DRCLAW_URL" workflow status --project <project> --json
$DRCLAW_BIN --url "$DRCLAW_URL" digest project --project <project> --json

Digests and reporting

Daily digest:

$DRCLAW_BIN --url "$DRCLAW_URL" digest daily --json

Per-project digest:

$DRCLAW_BIN --url "$DRCLAW_URL" digest project --project <project> --json

Cross-project portfolio digest with recommended follow-ups:

$DRCLAW_BIN --url "$DRCLAW_URL" digest portfolio --json

For cross-project OpenClaw dashboards, use the embedded openclaw.portfolio.v1 field rather than custom ranking logic.

Artifacts and workflow state:

$DRCLAW_BIN --url "$DRCLAW_URL" workflow status --project <project> --json
$DRCLAW_BIN --url "$DRCLAW_URL" taskmaster artifacts --project <project> --json

Response format guidance for mobile / chat

Keep replies compact:

• first line: direct answer
• then: short project / session / status bullets if relevant
• always include exact session ids when asking the user to choose one
• when reporting a post-reply state, say whether the session is still processing or has cleared

When JSON is available:

• prefer openclaw.decision.needed to decide whether to interrupt the user
• prefer openclaw.next_actions for quick replies or buttons
• prefer openclaw.turn.summary / openclaw.focus for compact rendering

Event-driven watcher daemon

Use the watcher when OpenClaw should proactively notify the user instead of waiting for manual digest polling.

Start / stop / inspect:

$DRCLAW_BIN --url "$DRCLAW_URL" --json openclaw-watch on --to feishu:<chat_id>
$DRCLAW_BIN --url "$DRCLAW_URL" --json openclaw-watch status
$DRCLAW_BIN --url "$DRCLAW_URL" --json openclaw-watch off

Watcher behavior:

• subscribes to Dr. Claw WebSocket events
• reacts to important event types only
• resolves the affected project when possible, including path-based file change events
• compares workflow snapshots to derive higher-level openclaw.event.v1.event.signals
• current useful signals include human_decision_needed, waiting_for_human, blocker_detected, blocker_cleared, task_completed, next_task_changed, attention_needed, and session_aborted
• asks OpenClaw agent to generate the final Feishu/Lark notification when enough project context is available
• parses delivered agent output back into clean human-facing text instead of leaking plugin logs / raw JSON
• enriches events with openclaw.event.v1 and project-level status when possible
• deduplicates repeated notifications for a 6-hour time window
• pushes only attention-worthy updates to the configured OpenClaw channel

Watcher runtime files:

• state: ~/.drclaw/openclaw-watcher-state.json
• log: ~/.drclaw/logs/openclaw-watcher.log

Reliable OpenClaw patterns

Pattern: list projects

1. Run $DRCLAW_BIN --url "$DRCLAW_URL" projects list.
2. Present short names, display names, and paths only when needed.

Pattern: user asks what needs attention

1. Run $DRCLAW_BIN --url "$DRCLAW_URL" digest portfolio --json.
2. Use the embedded openclaw.portfolio.v1.focus field first.
3. Fall back to chat waiting --json if the user explicitly wants raw waiting sessions.

Pattern: user asks OpenClaw to answer a waiting session

1. Run $DRCLAW_BIN --url "$DRCLAW_URL" chat reply --project ... --session ... -m ... --json.
2. Read openclaw.turn.v1 from the response.
3. If decision.needed=true, surface the decision reason and quick actions.
4. If the same session is still present in waiting_sessions, report that it is still processing.
5. Optionally run drclaw_wait_until_clear.sh and report the final clearance.

Pattern: user suddenly has a new idea

1. Pick a workspace path, usually /Users/<user>/vibelab/<slug>.
2. Run $DRCLAW_BIN --url "$DRCLAW_URL" projects idea <path> --name <display-name> --idea <idea> --json.
3. Return the created project, session id, and first Dr. Claw reply.
4. Continue the discussion with $DRCLAW_BIN --url "$DRCLAW_URL" chat reply on that session.

Pattern: user wants an update without opening Dr. Claw

1. Run $DRCLAW_BIN --url "$DRCLAW_URL" digest daily --json, $DRCLAW_BIN --url "$DRCLAW_URL" digest project --project ... --json, or $DRCLAW_BIN --url "$DRCLAW_URL" digest portfolio --json.
2. Use digest portfolio when the user wants cross-project progress, attention recommendations, or suggested replies.
3. Prefer the openclaw.* schema field for rendering.
4. Summarize only the load-bearing items: waiting sessions, task progress, blockers, next actions.