OpenClaw Code Agent

openclaw-code-agent is the OpenClaw plugin for running Claude Code and Codex as managed background coding sessions from chat. Launch work from Telegram, Discord, or any OpenClaw-supported channel, review the plan before execution, keep the job isolated in its own git worktree, and merge or open a PR without leaving the thread.

• Plan -> Review -> Execute. plan is the default launch mode, and plan approval defaults to delegate so the orchestrator reviews the full plan before approving or escalating to the user.
• Delegated worktree isolation. New sessions default to delegate; opt into ask, off, manual, auto-merge, or auto-pr when you want a different branch follow-through policy.
• State-driven decision UX. ask sends explicit action buttons for Merge locally, Create PR, Decide later, and Dismiss. The same action-token model now backs both Telegram and Discord interactive callbacks.
• Lifecycle-first cleanup. Worktrees are treated as temporary task sandboxes. The plugin distinguishes merged from released so different-SHA branches whose content already landed on the base branch can still be cleaned safely.
• Full session lifecycle. Suspend, resume, fork, interrupt, and recover sessions across restarts with persisted metadata and output.
• Explicit goal-task loops. Opt into verifier-driven repair loops or Ralph-style completion loops when you need iterative autonomous execution toward a specific goal.
• Real operator visibility. agent_sessions, agent_output, and agent_stats show status, buffered output, duration, and USD cost.
• Two harnesses, one control plane. Claude Code and Codex share the same tools, routing, notification pipeline, and worktree strategy model while each backend uses its own native execution substrate.
• One continuation primitive. agent_respond is the only way to continue, approve, revise, or redirect an existing session. Forks still go through agent_launch(..., resume_session_id=..., fork_session=true).

Need the ACPX vs Codex vs code-agent breakdown? See docs/ACP-COMPARISON.md.

Boundaries

openclaw-code-agent is separate from both OpenClaw's bundled acpx runtime plugin and OpenClaw's bundled codex plugin.

• ACPX is OpenClaw's ACP runtime backend for ACP session interoperability.
• OpenClaw's bundled codex plugin is the core native Codex provider/harness pair for embedded agent turns.
• openclaw-code-agent is the chat orchestration layer that adds plan approval, wake routing, session lifecycle, and worktree/merge/PR policy above its own native Claude Code and Codex harnesses.

The shared substrate is often the local codex command and Codex App Server, but the responsibilities are different. This plugin is not an ACP server and it does not depend on OpenClaw's bundled Codex provider to expose its own codex harness.

New In 4.1.2

4.1.2 is a plan-approval reliability patch for the OpenClaw 2026.5.4 release line. It keeps the >=2026.4.21 compatibility floor and the 4.1.1 build/test target, while tightening the user-facing approval path that gates implementation.

• Telegram plan approval buttons restored. Plan prompts in Telegram use the shared direct-message presentation path and carry the canonical Approve, Revise, and Reject actions.
• Plain-text fallback is explicit. While a plan is awaiting review, replying Approve, Revise, or Reject triggers the same approval, revision, or rejection path as the buttons.
• Stale prompts are suppressed. Rejected or killed plan sessions no longer resurface an obsolete Plan v2 prompt as if it were still actionable.
• Verified release evidence. A plan-gated rust-hello-world run, rust-hello-world-minor-change-2 (FzPCkqjh), completed as approved_then_implemented after explicit approval; a later run (VmUBWOH2) delivered a clean plan prompt without the old stale Plan v2-after-reject behavior.

The 4.1.1 OpenClaw 2026.5.4 compatibility work remains current: managed TaskFlow mirroring is opportunistic, deterministic runtime state is exposed in wakes, direct notification failures are surfaced, and local build/test metadata still targets stable OpenClaw 2026.5.4.

From Prompt To Merged Branch

1. Launch a coding session from chat with /agent ... or agent_launch(...).
2. Review the plan in the same thread before anything touches the repo.
3. Let the agent finish in an isolated worktree, then merge or publish the result from chat.

Explicit Goal Tasks

Goal tasks are an explicit opt-in path for iterative autonomous work. They do not replace the default agent_launch flow.

Use the dedicated goal entrypoints:

• /goal ...
• goal_launch(...)

The plugin does not automatically switch into goal mode just because a freeform prompt contains the words goal task.

Use them when you want the plugin to keep looping toward one concrete outcome:

• Verifier mode reruns one or more shell checks after each coding turn and keeps iterating until they pass or the iteration budget is exhausted.
• Ralph mode keeps resuming the same task until the agent emits an exact completion promise, with optional verifiers run after completion is claimed.

Examples:

/goal --workdir /repo --verify "npm test" --verify "npm run lint" Fix the failing auth flow
/goal --workdir /repo --mode ralph --completion-promise DONE Ship the draft blog post workflow end to end
goal_launch(goal="Fix the failing auth flow", verifier_commands=["npm test", "npm run lint"], workdir="/repo")
goal_launch(goal="Ship the draft blog post workflow end to end", goal_mode="ralph", completion_promise="DONE", workdir="/repo")

Once launched, use goal_status / /goal_status to inspect progress and goal_stop / /goal_stop to terminate the loop. Goal-task state is persisted so recoverable loops can resume after a gateway restart.

Plan First

The differentiator is the plan-review loop. Claude Code and Codex both feed the same review UX now: the plugin receives a structured plan artifact, keeps execution blocked until approval, and resumes the same session with agent_respond(..., approve=true). If the user asks for revisions, the revised submission becomes the new actionable review version for that same session, and approve=true resolves against that latest version instead of any stale earlier change-request state.

Demo note: the GIFs below were recorded on an older build. They still show the overall flow correctly, but they do not include the newer explicit action buttons and some other current thread controls.

ask mode keeps the human in the loop: the plan lands back in the originating thread, and execution only starts after approval. The current UI now uses explicit buttons for approval and follow-through, even though the GIF predates that update.

Finish Cleanly

When the task is done, the plugin can leave the branch for review, merge it automatically, or help create a PR. In ask, the user gets the same explicit decision buttons in the originating thread. In delegate, the orchestrator receives the diff context, may merge if safe, and always escalates PR decisions to the user. Planning artifacts belong in /tmp/ — the agent will not commit analysis notes to the branch.

The main checkout stays clean. The branch lifecycle happens in the worktree, and the chat thread stays current on what was shipped. The current UI includes newer buttons and lifecycle affordances that are not visible in this older recording.

Worktree Lifecycle

Worktree-backed sessions move through product-facing lifecycle states:

• active: sandbox still in use
• pending decision: waiting for merge / PR / dismiss follow-through
• pr_open: PR exists and the sandbox is being preserved
• merged: branch landed by normal git ancestry
• released: content is already on the base branch even though branch SHAs differ after rebase, squash, or cherry-pick
• dismissed: user intentionally discarded the sandbox
• no_change: session finished without a committed delta

For cleanup, use agent_worktree_cleanup(mode="preview_safe") to preview what Clean all safe would remove, mode="clean_safe" to perform that cleanup, and mode="preview_all" to review both safe sandboxes and the reasons other worktrees were retained.

Supported Harnesses

Launches and notifications work from Telegram, Discord, or any OpenClaw-supported channel. Telegram and Discord now share the same action-token callback flow for plan approvals, question options, resume/restart, and worktree decisions.

Quick Start

Install and enable the plugin:

openclaw plugins install openclaw-code-agent
openclaw plugins enable openclaw-code-agent
openclaw gateway restart
openclaw plugins inspect openclaw-code-agent --runtime --json

Restart or reload the gateway only as part of your normal install/upgrade flow; it is not needed for editing docs or preparing a release branch.

This release targets the OpenClaw v2026.4.21 external plugin contract and is verified against the stable v2026.5.4 build/test target. package.json carries the plugin API compatibility and build metadata used by modern OpenClaw / ClawHub installs, and openclaw.plugin.json advertises the plugin-owned startup, command activation surface, tool contracts, and onboarding metadata OpenClaw uses during plugin-config setup. Keep those metadata surfaces in sync when bumping the plugin release baseline.

After install or update, inspect the runtime plugin view after the gateway restart. The runtime inspection should show the chat commands, service, and agent_* / goal_* tools without diagnostics. If tools.effective or tools.invoke cannot see agent_launch or agent_sessions, the installed plugin is stale or the gateway has not restarted onto the updated manifest and bundle.

The current manifest descriptors stay intentionally narrow: activation advertises startup loading plus only the chat commands this plugin owns, and setup stays minimal with requiresRuntime: false. First-run onboarding is driven by the manifest config schema and uiHints, not by provider/backend setup descriptors.

First-Run Onboarding

In OpenClaw's Manual setup flow, the plugin should only ask for three first-run decisions:

• defaultWorkdir: the git repo path you expect to launch from most often
• defaultHarness: whether your default harness is claude-code or codex
• fallbackChannel: an optional but recommended fully routable notification target for async updates

Everything else stays advanced/manual. In particular, agentChannels, per-harness model policy, permission defaults, and worktree policy are intentionally deferred until after the first successful launch, even though plan approval and worktree follow-through now default to delegated behavior. If your first launch must run outside a git repo, expand Advanced during setup or edit config afterwards and set defaultWorktreeStrategy to off.

Add a minimal config block under plugins.entries["openclaw-code-agent"] in ~/.openclaw/openclaw.json:

{
  "plugins": {
    "entries": {
      "openclaw-code-agent": {
        "enabled": true,
        "config": {
          "defaultWorkdir": "/home/user/project",
          "defaultHarness": "claude-code",
          "fallbackChannel": "telegram|my-bot|123456789",
          "harnesses": {
            "claude-code": {
              "defaultModel": "anthropic/claude-sonnet-4-7",
              "allowedModels": ["sonnet", "opus"]
            },
            "codex": {
              "defaultModel": "gpt-5.5",
              "allowedModels": ["gpt-5.5", "gpt-5.5-pro"],
              "reasoningEffort": "medium"
            }
          }
        }
      }
    }
  }
}

You can leave the advanced settings at their defaults for the first run. The plugin defaults to:

• permissionMode: "plan"
• planApproval: "delegate"
• defaultWorktreeStrategy: "delegate"

Because delegated worktree follow-through is now the default, the first-run defaultWorkdir should normally point at a git repository. Non-git workdirs are still supported by setting defaultWorktreeStrategy: "off" globally or by launching with worktree_strategy: "off".

If you run Codex sessions, keep Codex on the ChatGPT auth path:

forced_login_method = "chatgpt"

Put that in ~/.codex/config.toml.

Codex approval behavior is fixed to the supported execution path, and OpenClaw handles review gates through permissionMode plus planApproval.

Harness Availability Guidance

OpenClaw's generic plugin onboarding can prompt for defaultHarness, but it does not yet have a plugin-specific readiness panel. Use these checks when choosing the default:

• codex: choose this only when the codex command (or your OPENCLAW_CODEX_APP_SERVER_COMMAND override) is available and local Codex auth under ~/.codex is already working
• claude-code: choose this when the bundled Claude SDK/CLI is installed and you expect Claude Code to be the main path on this machine

Codex readiness is the easier one to verify locally because the plugin depends on a resolvable command plus local auth files. Claude Code installation is verifiable, but authenticated usability may still require Claude-side login/account setup the first time you launch a session.

This is this plugin's own harness selection, not OpenClaw ACPX runtime selection and not the bundled core codex provider toggle. The real prerequisites are the local backend commands and local auth state.

Launch a first session:

/agent --name fix-auth Fix the auth middleware bug
/agent_sessions
/agent_respond fix-auth Add unit tests too
agent_launch(prompt="<new task>", resume_session_id="fix-auth", fork_session=true)

For multi-workspace or multi-bot setups, configure agentChannels. The full routing rules, config matrix, and notification behavior live in docs/REFERENCE.md.

Prefer fully routable channel strings such as telegram|123456789 or telegram|my-bot|123456789. A bare provider like telegram is only a weak fallback; the plugin now repairs topic routing from originSessionKey when possible, but explicit channels are still the safer default.

Upgrade Notes

For OpenClaw 2026.5.4 readiness:

• Build and SDK metadata now target OpenClaw 2026.5.4; the peer floor remains >=2026.4.21 for existing compatible installs.
• If your OpenClaw config uses an exclusive plugins.allow list, include openclaw-code-agent or the plugin's agent_* / goal_* tools will not load even if tools.allow names them.
• Harness model policy should live under harnesses.codex.* and harnesses["claude-code"].*. Legacy defaultModel, model, reasoningEffort, and global allowedModels are compatibility-only. Configured reasoningEffort supports low, medium, high, xhigh, and max.
• Codex and Claude Code restrictions are harness-scoped. Codex defaults to gpt-5.5 with gpt-5.5 / gpt-5.5-pro allowed; Claude Code defaults to anthropic/claude-sonnet-4-7 with sonnet / opus matching.
• tools.deny does not disable OpenClaw's apply_patch tool by itself. Use OpenClaw's tools.exec.applyPatch.* settings when you need patch-tool policy.

For 4.1.0:

• Managed TaskFlow integration is opportunistic. It uses OpenClaw's current managed-flow runtime when available and degrades to the existing session-only behavior when that surface is absent.
• Direct notification failures are now surfaced more explicitly. Treat a missing button delivery as a delivery/routing problem, not as evidence that the underlying plan or worktree state changed.
• Runtime and approval state fields in wakes are authoritative. Prefer them over transcript fragments when deciding whether execution was approved, bypassed, completed, or still waiting.

For 3.2.0:

If you are upgrading from 3.1.0, the important behavioral changes are:

• defaultWorktreeStrategy now defaults to delegate, so new sessions use worktree isolation and orchestrator-led follow-through unless you configure or launch with a different strategy.
• auto-merge now attempts one autonomous conflict resolution before escalating.
• Completion wakes and no-change outcomes are deterministic and carry explicit approval/execution state instead of relying on transcript inference.
• Worktree cleanup is lifecycle-first and can now classify already-landed branches as released, which makes preview_safe and clean_safe more trustworthy after rebase, squash, or cherry-pick flows.
• Release validation now checks package/plugin version parity in addition to the normal pnpm verify gate.

Backend Capabilities

• Claude Code stays on plugin-managed worktrees.
• Codex now runs through App Server structured events and may execute inside a native backend-managed worktree.
• Merge, PR, reminder, and decision policy remain plugin-owned above both backends.
• Operators should continue sessions by plugin session ID or name. Backend conversation IDs are accepted only for recovery and diagnostics.

Tool Surface

The chat command surface mirrors the common workflows: /agent, /agent_sessions, /agent_output, /agent_respond, /agent_kill, /agent_stats, /goal, /goal_status, and /goal_stop.

Docs

License

MIT. See LICENSE.