Skip to content

Zmmfly/openclaw-code-agent

BranchesTags
 
 

Repository files navigation

OpenClaw Code Agent

npm version npm downloads License: MIT

An OpenClaw plugin that lets AI agents orchestrate coding agent sessions as managed background processes. Launch, monitor, and interact with multiple concurrent coding sessions directly from Telegram, Discord, or any OpenClaw-supported messaging platform — without leaving your chat interface.

Why?

This plugin started as a response to a real gap in OpenClaw's built-in ACP support. At the time, ACP was effectively a raw relay into ACP backends: useful for handing off a prompt, but without the orchestration layer needed for coding-agent work in chat. There was no plan review flow, no plugin-managed pause/resume model, no fork flow, no cost or session stats, and no async notification path back to the originating chat when a session needed input or finished.

ACP has improved since then. OpenClaw core ACP now supports multi-turn sessions, resuming prior work, and a broader set of ACP runtimes and harnesses. That closes part of the original gap.

What still remains is the orchestration layer this plugin was built to provide: propose/revise/approve plan review before execution, forkable coding sessions, dedicated session catalog + operator-facing stats, cost accounting, and an explicit async notification pipeline that wakes the origin chat only when the job needs attention or completes.

For the current version-pinned breakdown, see docs/ACP-COMPARISON.md.

Demo

Ask mode demo showing plan review and approval before execution

Plan review and approval in ask mode: the agent pauses for your decision before executing.

Autonomous mode (delegate)

Delegate mode demo showing autonomous execution with selective escalation

In delegate mode, the orchestrator auto-approves low-risk plans and only escalates when needed.

Supported Agents

Agent Status Notes
Claude Code ✅ Supported Full support via @anthropic-ai/claude-agent-sdk
Codex ✅ Supported Full support via @openai/codex-sdk thread API
Other agents 🚧 Planned Plugin architecture supports adding new harnesses

vs. built-in ACP? See docs/ACP-COMPARISON.md for the current version-pinned breakdown.

Features

  • Multi-session management — Run multiple concurrent coding agent sessions, each with a unique ID and human-readable name
  • Plan → Execute workflow — Claude Code sessions expose plan mode; Codex uses a soft first-turn planning prompt while staying externally in implement mode
  • Real Codex approval policy support — Codex sessions default to the real Codex SDK/CLI approvalPolicy: "on-request" and can be pinned back to "never" via harnesses.codex.approvalPolicy
  • Thread-based routing — Notifications go to the Telegram thread/topic where the session was launched
  • Pause + auto-resume — Non-question turn completion pauses sessions (done) and next agent_respond auto-resumes with context intact
  • Turn-end wake signaling — Every turn end emits a deterministic wake signal with output preview and waiting hint
  • Smart waiting detection — Heuristic waiting detector reduces false-positive wake escalations
  • Multi-turn conversations — Send follow-up messages, interrupt, or iterate with a running agent
  • Session resume & fork — Resume any completed session or fork it into a new conversation branch
  • Merged session listing — agent_sessions shows active + persisted sessions in one view (deduped by internal session ID)
  • Pending MessageStream safety — queued follow-ups are preserved across turn completion so messages are not dropped
  • Codex SDK streaming harness — uses @openai/codex-sdk thread streaming with soft first-turn planning, waiting detection, and activity heartbeats
  • Multi-agent support — Route notifications to the correct agent/chat via workspace-based channel mapping
  • Auto-respond rules — Orchestrator auto-handles permission requests and confirmations; forwards real decisions to you
  • Anti-cascade protection — Orchestrator never launches new sessions from wake events
  • Automatic cleanup — Completed sessions are garbage-collected after a configurable TTL (sessionGcAgeMinutes, default 24h); IDs persist for resume
  • Harness-agnostic architecture — Pluggable AgentHarness interface allows adding new coding agent backends

Quick Start

1. Install the plugin

openclaw plugins install openclaw-code-agent
openclaw plugins enable openclaw-code-agent
openclaw gateway restart

2. Configure notifications

Add to ~/.openclaw/openclaw.json under plugins.entries["openclaw-code-agent"]:

{
  "plugins": {
    "entries": {
      "openclaw-code-agent": {
        "enabled": true,
        "config": {
          "fallbackChannel": "telegram|my-bot|123456789",
          "maxSessions": 20,
          "harnesses": {
            "codex": {
              "defaultModel": "gpt-5.4",
              "allowedModels": ["gpt-5.4"],
              "reasoningEffort": "medium",
              "approvalPolicy": "on-request"
            },
            "claude-code": {
              "defaultModel": "sonnet",
              "allowedModels": ["sonnet", "opus"]
            }
          }
        }
      }
    }
  }
}

Replace my-bot with your Telegram bot account name and 123456789 with your Telegram chat ID.

2a. Codex auth safety

If you run Codex sessions, strongly recommend forcing ChatGPT login in your Codex config:

forced_login_method = "chatgpt"

Put that in ~/.codex/config.toml. This keeps Codex on the ChatGPT auth path and avoids account/login mismatches that can surface as unsupported-model or auth failures.

3. Typical workflow

  1. Ask your agent: "Fix the bug in auth.ts"
  2. A coding agent session launches and explores the task. Claude Code exposes plan mode; Codex can do a plan-first turn without surfacing plan mode in session status
  3. The agent's questions and plan appear in the same Telegram thread where you launched
  4. When a session is awaiting plan approval, approve it with agent_respond(..., approve=true) and the session switches to implement mode
  5. The agent implements with full permissions, then you get a brief completion summary

Tools

Tool Description Key Parameters
agent_launch Start a new coding agent session in background prompt, name, workdir, model, resume_session_id, fork_session, permission_mode, harness
agent_respond Send a follow-up message to a running session session, message, interrupt, approve, userInitiated
agent_kill Terminate or complete a running session session, reason
agent_output Read buffered output from a session session, lines, full
agent_sessions List recent sessions (5 by default, full for 24h view) status, full
agent_stats Show usage metrics (counts, durations, costs) (none)

Core orchestration workflows use agent_launch, agent_respond, agent_output, agent_sessions, and agent_kill.

All tools are also available as chat commands (/agent, /agent_respond, /agent_kill, /agent_sessions, /agent_resume, /agent_stats, /agent_output).

Usage Examples

# Launch a session (starts in plan mode by default)
/agent Fix the authentication bug in src/auth.ts
/agent --name fix-auth Fix the authentication bug

# Monitor
/agent_sessions
/agent_sessions --full

# Interact with a running session
/agent_respond fix-auth Also add unit tests
/agent_respond --interrupt fix-auth Stop that and do this instead

# Approve a pending plan (tool call)
agent_respond(session='fix-auth', message='Approved. Go ahead.', approve=true)

# Lifecycle management
/agent_kill fix-auth
/agent_resume fix-auth Add error handling
/agent_resume --fork fix-auth Try a different approach
/agent_stats

Notifications

The plugin sends targeted notifications to the originating Telegram thread:

Emoji Event Description
🚀 Launched Session started with prompt summary
🔔 Agent asks Session is waiting for user input
📋 Plan ready Plan approval requested — reply "go" to approve
🔄 Turn done Turn completed, session paused (auto-resumable)
✅ Completed Completion summary with cost and duration
❌ Failed Error notification with hint
⛔ Killed Session terminated with kill reason
💤 Idle-killed Auto-resumes on next respond

Plan → Execute Mode Switch

  • Claude Code starts in plan mode by default. Approve a pending plan with agent_respond(..., approve=true) and the session switches to bypassPermissions.
  • Codex does not surface plan or awaiting-plan-approval in session state. When launched with permissionMode: "plan", its first turn is prompted to return a plan and ask whether to proceed, while the exposed session phase remains implementation-oriented.
  • For Codex, plugin permissionMode is a plugin-orchestrated planning/approval workflow. It is not the same thing as the Codex SDK/CLI approvalPolicy.
  • The real Codex SDK/CLI approval behavior is controlled by harnesses.codex.approvalPolicy. Supported values are "on-request" (default) and "never".

On approval, the plugin prepends a system instruction telling the agent to exit plan mode and implement with full permissions.

Auto-Respond Rules

The orchestrator agent follows strict auto-respond rules to minimize noise:

Auto-respond (immediate):

  • Permission requests (file read/write/bash) → "Yes, proceed."
  • Explicit "should I continue?" confirmations → "Yes, continue."

Forward to user (everything else):

  • Architecture/design decisions
  • Destructive operations
  • Scope changes
  • Credential/production questions
  • Any ambiguous or non-trivial question

When forwarding, the orchestrator quotes the agent's exact question without adding its own commentary.

Configuration

Set values in ~/.openclaw/openclaw.json under plugins.entries["openclaw-code-agent"].config:

Option Type Default Description
agentChannels object — Map workdir paths → notification channels (see docs/AGENT_CHANNELS.md)
fallbackChannel string — Default notification channel when no workspace match found
maxSessions number 20 Maximum concurrent sessions
maxAutoResponds number 10 Max consecutive auto-responds before requiring user input
permissionMode string "plan" Plugin orchestration mode: "default" / "plan" / "acceptEdits" / "bypassPermissions"
idleTimeoutMinutes number 15 Idle timeout before auto-kill
sessionGcAgeMinutes number 1440 TTL for completed/failed/killed runtime sessions before GC eviction
maxPersistedSessions number 10000 Max completed sessions kept for resume; the 24h GC TTL (sessionGcAgeMinutes) is the primary retention control
planApproval string "delegate" "approve" (orchestrator can auto-approve) / "ask" (always forward to user) / "delegate" (orchestrator decides)
defaultHarness string "claude-code" Default harness for new sessions ("claude-code" / "codex")
harnesses object built-in defaults Per-harness defaults and restrictions. Built-in defaults: claude-code.defaultModel = "sonnet", claude-code.allowedModels = ["sonnet","opus"], codex.defaultModel = "gpt-5.4", codex.allowedModels = ["gpt-5.4"], codex.reasoningEffort = "medium", codex.approvalPolicy = "on-request"
defaultWorkdir string — Default working directory for new sessions

Permission Mode Mapping By Harness

Permission modes are shared at the plugin API, but each harness maps them differently:

  • Claude Code harness
    • default, plan, acceptEdits, bypassPermissions are passed through the SDK
  • Codex harness
    • Always runs with SDK thread option sandboxMode: "danger-full-access"
    • Uses Codex SDK/CLI approvalPolicy: "on-request" by default, or "never" when harnesses.codex.approvalPolicy is set
    • Supports harnesses.codex.defaultModel, harnesses.codex.allowedModels, harnesses.codex.reasoningEffort, and harnesses.codex.approvalPolicy
    • In bypassPermissions, the harness adds filesystem root (/ on POSIX) to Codex additionalDirectories, plus optional extras from OPENCLAW_CODEX_BYPASS_ADDITIONAL_DIRS (comma-separated)
    • setPermissionMode() is applied by recreating the thread on the next turn via resumeThread (same thread ID)
    • plan / acceptEdits remain plugin behavioral orchestration constraints (planning/approval flow), not Codex sandbox or SDK approval settings

Runtime Environment Overrides

  • OPENCLAW_CODE_AGENT_SESSIONS_PATH — explicit persisted session index path
  • OPENCLAW_HOME — base dir for persisted session index when explicit path is unset ($OPENCLAW_HOME/code-agent-sessions.json)
  • OPENCLAW_CODEX_BYPASS_ADDITIONAL_DIRS — comma-separated extra directories for Codex bypass mode
  • OPENCLAW_CODEX_HEARTBEAT_MS — Codex activity heartbeat interval in milliseconds (default 10000)

Session Lifecycle + GC

  • Active sessions live in runtime memory (SessionManager.sessions)
  • Terminal sessions are persisted with metadata/output stubs for resume and listing
  • Runtime records are evicted after sessionGcAgeMinutes (default 1440 / 24h)
  • Eviction means removed from runtime cache, not deleted permanently; persisted session records remain resumable

Example

{
  "plugins": {
    "entries": {
      "openclaw-code-agent": {
        "enabled": true,
        "config": {
          "maxSessions": 3,
          "harnesses": {
            "codex": {
              "defaultModel": "gpt-5.4",
              "allowedModels": ["gpt-5.4"],
              "reasoningEffort": "high",
              "approvalPolicy": "on-request"
            },
            "claude-code": {
              "defaultModel": "sonnet",
              "allowedModels": ["sonnet", "opus"]
            }
          },
          "permissionMode": "plan",
          "fallbackChannel": "telegram|my-bot|123456789",
          "agentChannels": {
            "/home/user/project-alpha": "telegram|my-bot|123456789",
            "/home/user/project-beta": "telegram|ops-bot|987654321"
          }
        }
      }
    }
  }
}

Orchestration Skill

Example orchestration skill (click to expand)

The plugin is a transparent transport layer — business logic lives in OpenClaw skills:

---
name: Coding Agent Orchestrator
description: Orchestrates coding agent sessions with auto-response rules.
metadata: {"openclaw": {"requires": {"plugins": ["openclaw-code-agent"]}}}
---

# Coding Agent Orchestrator

## Anti-cascade rule
When woken by a waiting-for-input or completion event, ONLY use agent_respond
or agent_output for the referenced session. NEVER launch new sessions from wake events.

## Auto-response rules

When a coding agent session asks a question, analyze and decide:

### Auto-respond (use `agent_respond` immediately):
- Permission requests for file reads, writes, or bash commands -> "Yes, proceed."
- Confirmations like "Should I continue?" -> "Yes, continue."

### Forward to user (everything else):
- Architecture decisions, destructive operations, ambiguous requirements,
  scope changes, credential/production questions
- Quote the agent's exact question. No commentary.

## Workflow
1. User sends a coding task -> `agent_launch(prompt, ...)`
2. Session runs in background. Monitor via wake events.
3. On wake event -> `agent_output` to read the question, then auto-respond or forward.
4. On completion -> summarize briefly: files changed, cost, duration, issues.

A comprehensive orchestration skill is available at skills/code-agent-orchestration/SKILL.md.

Architecture

For a detailed look at how the plugin works internally, see the docs/ directory:

Document Description
docs/ARCHITECTURE.md System design, component breakdown, and data flow
docs/NOTIFICATIONS.md Notification architecture, delivery model, and wake mechanism
docs/AGENT_CHANNELS.md Multi-agent setup, notification routing, and workspace mapping
docs/TOOLS.md Detailed tool reference with parameters and examples
docs/DEVELOPMENT.md Development guide, project structure, and build instructions

Development

Build output is an ESM bundle at dist/index.js (package.json has "type": "module").

# Install dependencies
pnpm install

# Build (esbuild → dist/index.js)
pnpm run build

# Type-check
pnpm run typecheck

# Run tests
pnpm test

Project Structure

openclaw-code-agent/
├── index.ts                    # Plugin entry point
├── openclaw.plugin.json        # Plugin manifest & config schema
├── src/
│   ├── harness/                # Agent harness abstraction layer
│   │   ├── types.ts            # AgentHarness interface & message types
│   │   ├── claude-code.ts      # Claude Code harness (SDK wrapper)
│   │   ├── codex.ts            # Codex harness (@openai/codex-sdk thread stream wrapper)
│   │   └── index.ts            # Harness registry
│   ├── types.ts                # TypeScript interfaces
│   ├── config.ts               # Config singleton + channel resolution
│   ├── format.ts               # Formatting utilities
│   ├── singletons.ts           # Module-level singleton refs
│   ├── session.ts              # Session class (state machine, timers, harness)
│   ├── session-manager.ts      # Session pool management + lifecycle
│   ├── session-store.ts        # Persisted session/index storage abstraction
│   ├── session-metrics.ts      # Metrics recorder abstraction
│   ├── wake-dispatcher.ts      # Wake delivery + retry abstraction
│   ├── notifications.ts        # Notification service
│   ├── actions/respond.ts      # Shared respond logic (tool + command)
│   ├── application/            # Shared app-layer logic used by tools + commands
│   ├── tools/                  # Tool implementations (6 tools)
│   └── commands/               # Chat command implementations (7 commands)
├── tests/                      # Unit tests (node:test + tsx)
├── skills/                     # Orchestration skill definitions
└── docs/                       # Architecture & reference docs

Troubleshooting

  • Plugin installed but the gateway does not see it yet: run openclaw gateway restart.
  • Notifications are not arriving: verify fallbackChannel uses the exact format "telegram|bot-name|chat-id" in ~/.openclaw/openclaw.json.

Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes with tests
  4. Submit a pull request

License

MIT — see LICENSE for details.

Originally based on alizarion/openclaw-claude-code-plugin. Renamed to openclaw-code-agent to be harness-agnostic.

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages

  • TypeScript 100.0%