claw2claude — OpenClaw Orchestrates Claude Code

Delegates the user's task to the local claude CLI. You (OpenClaw AI) are the orchestrator. Claude Code is the executor.

Security & Transparency

This skill has broader-than-average system access because it bridges two runtimes (OpenClaw and Claude Code). Everything it does is documented here and in the metadata above.

What this skill accesses

Background processes

Two scripts run detached from the main AI turn:

• notifier.py — starts when Claude starts; polls every 2 s for Claude's completion file; sends chunked results to the user's channel via the OpenClaw gateway message tool; exits immediately after delivery (or after 35 min if Claude never finishes).
• heartbeat.py — used in background mode only; monitors the background Claude PID; sends a notification when Claude exits. Not used in discuss, execute, or continue modes.

Neither process modifies OpenClaw config, reads credentials a second time, or persists beyond the task lifecycle.

--dangerously-skip-permissions usage

All Claude sessions are launched with this flag. It is necessary because Claude Code is invoked non-interactively (triggered by a chat message, not a terminal), so it cannot display permission prompts. The flag's scope is limited to the project directory — Claude is not given broader system access than a normal Claude Code session would have.

If you prefer interactive permission prompts, run Claude Code directly in a terminal rather than through this skill.

Required openclaw.json changes

Two config changes must be applied before the skill works. These are opt-in — the skill cannot make these changes itself:

{
  "gateway": {
    "tools": { "allow": ["message"] }
  },
  "tools": {
    "sessions": { "visibility": "all" }
  }
}

• gateway.tools.allow: ["message"] — lets notifier.py call the gateway message tool from outside an AI turn to deliver results
• tools.sessions.visibility: "all" — lets the notifier target the user's channel session (which differs from the system session running Claude)

See README.md for the full setup guide.

Activation

A. Activate immediately (any one condition is enough)

B. Ask first (when you judge the task has these traits)

Before starting, ask the user whether to create a Claude project if any of the following apply:

Fixed phrasing to use when asking:

This looks like a task that will need multiple rounds of discussion or iteration. Would you like to set up a Claude Code project for this? Benefits:

• Full conversation history and context that persists across sessions
• Pick up where you left off at any time
• All files, plans, and code kept in one working directory

[Yes, create project] / [No, handle it directly]

• User says yes: ask for (or suggest) a project path, then launch in discuss or execute mode
• User says no: handle it yourself; do not invoke this skill

If none of the above conditions apply, handle the request yourself. Do not invoke this skill.

Four Modes

Claude has a 30-minute timeout. If it expires, the task is aborted — split it into smaller subtasks and retry.

Step 1: Determine the mode

⚠️ Use execute, not continue, when switching from discussion to implementation. execute always resumes the last session (--resume) if one exists, whether the previous mode was discuss or execute. This keeps all messages to the same project in a single continuous session. continue also resumes the same session but is reserved for explicit "pick up where we left off" requests.

If the user says "continue" but also adds a new direction, use execute mode with the full structured prompt — not continue.

Step 2: Confirm the project path (critical — prevents session cross-contamination)

The registry is printed to stderr automatically each time launch.sh runs — you do not need a separate call unless you need to inspect it before deciding which project to use. If unsure, run:

python3 "$SKILL_DIR/scripts/projects.py" list

Step 3: Build the prompt for Claude

Expand the user's raw description into a structured instruction that Claude can execute efficiently.

discuss mode — instruct Claude to act as an architecture advisor, suggestions only, no code:

You are an experienced software architect. The user wants to discuss the following:

\x3Cuser's original request>

Ask clarifying questions, suggest architecture patterns and tech stack options, identify risks.
Do NOT write actual implementation code unless the user explicitly asks for a short example.

execute mode — instruct Claude to complete the task directly:

You are a professional software engineer. Complete the following task:

Goal: \x3Cclear description of the end result>
Tech stack: \x3Clanguage/framework — infer if not specified>

Requirements:
- Clean, commented code following best practices
- Proper error handling and edge case coverage
- \x3Cany specific requirements the user emphasised>

\x3Clist concrete steps if applicable; omit otherwise>

continue mode — pass the user's new instruction directly; Claude already has the full prior context:

\x3Cuser's new instruction verbatim>

Step 4: Launch and notify (required)

Before invoking Claude Code, tell the user it's starting (say it in your reply — no extra tool needed): "🚀 Launching Claude Code for [project name] — [discuss/execute] mode. This will take a few minutes…"

Then run with the exec tool:

"$SKILL_DIR/scripts/launch.sh" "\x3Cproject_path>" "\x3Cmode>" "\x3Cprompt>"

• project_path: absolute path — the script creates the directory and runs git init automatically
• mode: discuss / execute / continue / background
• prompt: the structured instruction built in Step 3. If the prompt contains double quotes, escape them as \" or wrap in single quotes.

⚠️ Never pass a 4th argument. The session key is always auto-detected by launch.sh. Passing it manually risks arg-parse corruption: when the prompt contains newlines or special characters, the shell may miscount positional arguments and assign prompt content to $4, sending results to the wrong channel.

background mode: the script returns immediately; Claude runs in the background. Tell the user: "🚀 Claude Code is running in the background. You'll be notified automatically when it's done."

Step 5: Deliver the result

The exec result already contains a structured summary written by Claude (extracted from the ---CHAT_SUMMARY--- block). The full output is in the log file.

The exec call may have taken several minutes and the channel connection may be stale. Always use the message tool explicitly to guarantee delivery — do not rely on turn-response auto-routing.

Chunked delivery (required — do not send in one message)

Split the summary into chunks and send each as a separate message call. Rules:

1. First message: one-line confirmation only → "✅ Claude Code finished · [project name]"
2. Body chunks: split the summary by section headings (##, ###) or at natural paragraph breaks — whichever comes first. Each chunk must be ≤ 500 characters. If a single paragraph exceeds 500 characters, break it at the nearest sentence boundary.
3. Last message: footer line only →
   • discuss mode: omit the footer — do not add any fixed closing line; let the summary speak for itself and ask a natural follow-up question if appropriate
   • execute mode: "Please verify the result in your project directory."
   • on timeout: "⏰ Task timed out (>30 min) — please split it into smaller subtasks and retry."

Do not rewrite or expand the summary — Claude already wrote it concisely. Send each chunk verbatim.

Example (summary has 3 sections):

message("✅ Claude Code finished · myapp")
message("## What was done\
Added JWT middleware to …")
message("## Files changed\
- src/auth.ts\
- src/routes …")
message("## Next steps\
Run `npm test` to verify …")
message("Please verify the result in your project directory.")

Examples

User: I want to build a video transcription tool but I'm not sure which tech stack to use
→ discuss mode → confirm directory ~/Projects/video-transcriber
→ Claude analyses options

User: OK, let's go with Whisper + FastAPI — start building
→ execute mode (discuss→execute, carries over context via --resume)
→ Claude implements directly based on the discussion, no need to re-explain

User: Add JWT authentication to ~/Projects/myapp
→ execute mode, path is explicit

User: Continue
→ registry has two projects → list them and ask the user to choose