Run Codex CLI, Claude Code, OpenCode, or Pi Coding Agent via background process for programmatic control.
npxskills add clawdbot/clawdbot--skill coding-agentLoading…
Use for background feature builds, PR reviews, large refactors, and issue-to-PR loops. Do not use for simple edits, read-only lookup, ACP thread-bound work, or any run inside ~/.openclaw, $OPENCLAW_STATE_DIR, or active OpenClaw state dirs.
background:true.pty:true.claude --permission-mode bypassPermissions --print.openclaw message send.process; do not kill slow workers without cause.~/Projects/openclaw; use an isolated checkout.Before launching Codex, Claude Code, or OpenCode for work that modifies a Git-backed project:
upstream when it exists and matches that target; otherwise verify origin. Resolve the selected remote's default branch dynamically. Determine the target base from an explicit task branch or authoritative existing-PR metadata; for other shared branches, prove the configured/tracked base or ask. Use the canonical default only for new work with no other specified base. Stop if the repository, remote, or target base cannot be proven.git fetch --prune <canonical> immediately before creating a new isolated worktree and branch from <canonical>/<targetBaseBranch>.HEAD equals the fetched target-base SHA. Record the canonical remote, canonical default branch, target base branch, base SHA, worktree path, and branch.~/Projects/openclaw remains forbidden.For tasks that modify a Git-backed project, append this block to the worker prompt with real values:
Git preparation (mandatory before edits):
- canonical remote: <canonicalRemote>
- canonical default branch: <canonicalDefaultBranch>
- target base branch: <targetBaseBranch>
- fetched target base SHA: <targetBaseSha>
- preparation mode: <new work | existing PR/shared branch>
- checkout trust: trusted
- prepared source ref: <canonicalRemote/targetBaseBranch | fetched trusted source ref>
- prepared start SHA: <preparedStartSha>
- isolated worktree: <worktreePath>
- working branch: <branch>
- preparation receipt: <new work: `git fetch --prune <canonicalRemote>` ran immediately before creation from `<canonicalRemote>/<targetBaseBranch>` | existing branch: the canonical target base and trusted source ref were fetched immediately before the worktree was created from `<preparedSourceRef>` at `<preparedStartSha>`>
Before editing, verify the current directory is the isolated worktree and its initial HEAD equals <preparedStartSha>. For new work, that SHA must equal <targetBaseSha>. Never edit the primary checkout. For existing PR/shared-branch work, report divergence and do not rebase, merge, reset, force-push, or otherwise rewrite shared history unless explicitly asked.
Immediately before the final push or PR for newly authored work, run `git fetch --prune <canonicalRemote>` and `git merge-base --is-ancestor <canonicalRemote>/<targetBaseBranch> HEAD`. If the ancestry check fails, update the new branch onto the latest target base, rerun the relevant proof, and only then push without force. For existing PR/shared-branch work, report a failed ancestry check and follow the repository workflow without rewriting the branch.
For trusted refs, the launcher must create and verify the worktree before starting the editing worker; do not delegate worktree creation to that worker. The approved untrusted-PR workflow must instead own checkout and worktree materialization inside its sandbox. Never start a worker in ~/Projects/openclaw. Read-only tasks and non-project scratch work do not require the Git preparation block.
Append this shape to every worker prompt with real values:
Notification route:
- channel: <notifyChannel>
- target: <notifyTarget>
- account: <notifyAccount or omit>
- reply_to: <notifyReplyTo or omit>
- thread_id: <notifyThreadId or omit>
When finished, send exactly one completion or failure message using:
openclaw message send --channel <channel> --target '<target>' --message '<brief result>'
Add --account, --reply-to, or --thread-id only when present above.
Do not use openclaw system event or heartbeat.
If no trustworthy route exists, say completion auto-notify is unavailable.
Write the worker prompt to a temp file first. This avoids shell quoting bugs when the required notification block contains quotes or newlines.
PROMPT=$(mktemp -t openclaw-worker-prompt.XXXXXX)
cat >"$PROMPT" <<'EOF'
Task.
<mandatory Git preparation block>
<notification block>
EOF
printf 'prompt file: %s\n' "$PROMPT"
Use $PROMPT when launching from the same shell/session. If using a separate tool call, substitute the printed path. The launch forms below are for trusted checkouts only; untrusted contributor refs require the repository's approved sandbox/review workflow.
Codex:
bash pty:true background:true workdir:/path/isolated-worktree command:"codex exec - < \"$PROMPT\""
Claude Code:
bash background:true workdir:/path/isolated-worktree command:"claude --permission-mode bypassPermissions --print < \"$PROMPT\""
OpenCode:
bash pty:true background:true workdir:/path/isolated-worktree command:"opencode run < \"$PROMPT\""
sessionId immediately.process; cancel through Task Registry if mirrored there.Codex needs a trusted git repo. This throwaway scaffold is not project work and has no canonical remote, so the Git preparation block does not apply:
SCRATCH=$(mktemp -d)
git -C "$SCRATCH" init
PROMPT=$(mktemp -t openclaw-worker-prompt.XXXXXX)
cat >"$PROMPT" <<'EOF'
Build X.
<notification block>
EOF
printf 'prompt file: %s\n' "$PROMPT"
bash pty:true background:true workdir:$SCRATCH command:"codex exec - < \"$PROMPT\""
list: running/recent sessions.poll: status.log: output.submit: send input + Enter.write: raw stdin.paste: paste text.kill: terminate.sessionId.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Run Codex CLI, Claude Code, OpenCode, or Pi Coding Agent via background process for programmatic control.
Run Codex CLI, Claude Code, OpenCode, or Pi Coding Agent via background process for programmatic control.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Run Codex CLI, Claude Code, OpenCode, or Pi Coding Agent via background process for programmatic control.
Run Codex CLI, Claude Code, OpenCode, or Pi Coding Agent via background process for programmatic control.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.