--- name: openlair/dr-claw source: https://app.decimal.ai/s/openlair-dr-claw@1/SKILL.md source_sha256: c4b3e866c6c3 --- # 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: ```bash $DRCLAW_BIN server status ``` If the server is not running: ```bash $DRCLAW_BIN server on ``` Assume the local wrapper exports these defaults when OpenClaw runs the skill: ```bash 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: ```bash cat "$(git rev-parse --show-toplevel)/agent-harness/cli_anything/drclaw/SCHEMA.md" ``` When calling OpenClaw locally from automation or shell, use: ```bash ./scripts/openclaw_drclaw_turn.sh ``` This serializes `openclaw agent --local` calls per agent and avoids session-lock collisions. ## Project discovery List projects: ```bash $DRCLAW_BIN --url "$DRCLAW_URL" projects list ``` Inspect the latest message in a project: ```bash $DRCLAW_BIN --url "$DRCLAW_URL" projects latest --json ``` Inspect project progress and next actions: ```bash $DRCLAW_BIN --url "$DRCLAW_URL" projects progress --json ``` Create a new empty project workspace: ```bash $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: ```bash $DRCLAW_BIN --url "$DRCLAW_URL" projects idea /absolute/path/to/project --name "Display Name" --idea "" --json ``` Use `projects idea` for the “I suddenly have an idea” flow. ## Session lookup and waiting triage List known sessions for one project: ```bash $DRCLAW_BIN --url "$DRCLAW_URL" chat sessions --project --json ``` List waiting sessions across all projects or one project: ```bash $DRCLAW_BIN --url "$DRCLAW_URL" chat waiting --json $DRCLAW_BIN --url "$DRCLAW_URL" chat waiting --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: ```bash $DRCLAW_BIN --url "$DRCLAW_URL" chat reply --project --session \ --bypass-permissions --attach /path/to/file -m "" --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: ```bash $DRCLAW_BIN --url "$DRCLAW_URL" chat waiting --project --json ``` If you need to wait until the session leaves the waiting list, use: ```bash ./scripts/drclaw_wait_until_clear.sh --project --session ``` The script returns JSON indicating whether the session cleared or timed out. ## Workflow control Use these commands for workflow actions: ```bash $DRCLAW_BIN --url "$DRCLAW_URL" workflow status --project --json $DRCLAW_BIN --url "$DRCLAW_URL" workflow continue --project --session --bypass-permissions -m "" --json $DRCLAW_BIN --url "$DRCLAW_URL" workflow approve --project --session --json $DRCLAW_BIN --url "$DRCLAW_URL" workflow reject --project --session -m "" --json $DRCLAW_BIN --url "$DRCLAW_URL" workflow retry --project --session --json $DRCLAW_BIN --url "$DRCLAW_URL" workflow resume --project --session --bypass-permissions --json ``` For project-level UI cards or voice summaries, prefer the embedded `openclaw.project.v1` payload from: ```bash $DRCLAW_BIN --url "$DRCLAW_URL" workflow status --project --json $DRCLAW_BIN --url "$DRCLAW_URL" digest project --project --json ``` ## Digests and reporting Daily digest: ```bash $DRCLAW_BIN --url "$DRCLAW_URL" digest daily --json ``` Per-project digest: ```bash $DRCLAW_BIN --url "$DRCLAW_URL" digest project --project --json ``` Cross-project portfolio digest with recommended follow-ups: ```bash $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: ```bash $DRCLAW_BIN --url "$DRCLAW_URL" workflow status --project --json $DRCLAW_BIN --url "$DRCLAW_URL" taskmaster artifacts --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: ```bash $DRCLAW_BIN --url "$DRCLAW_URL" --json openclaw-watch on --to feishu: $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//vibelab/`. 2. Run `$DRCLAW_BIN --url "$DRCLAW_URL" projects idea --name --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.