@laceletho/openclaw-opencode-cli

Command line tool for OpenClaw to dispatch tasks to OpenCode and receive asynchronous callbacks.

Features

• 🔗 Remote/Local Dual Mode: Supports connecting to remote OpenCode servers or local installations
• ⚡ Non-blocking Execution: Tasks execute asynchronously with automatic callbacks to OpenClaw upon completion
• 🔄 Session Persistence: Multiple tasks reuse the same session for context continuity
• 📊 Task Management: View task status and history
• 🔒 Secure Authentication: Supports HTTP Basic Auth

Installation

npm install -g @laceletho/openclaw-opencode-cli

Quick Start

1. Configure Environment Variables (OpenClaw Side)

# Required for remote mode
export OPENCODE_URL=https://your-opencode-server.com
export OPENCODE_PASSWORD=your-password
export OPENCODE_USERNAME=opencode  # optional, default: opencode

# For callback integration with OpenClaw
export OPENCLAW_CALLBACK_URL=http://localhost:18789/hooks/agent
export OPENCLAW_API_KEY=your-openclaw-token
export OPENCLAW_AGENT_ID=main

2. Setup OpenCode Plugin (OpenCode Side)

For asynchronous callbacks to work, the OpenCode server needs the @laceletho/plugin-openclaw plugin installed and enabled.

See the plugin documentation for setup instructions.

3. Dispatch Tasks

Session Management:

By default, multiple task commands reuse the same OpenCode session:

# First task creates a new session
openclaw-opencode task "Create a new Express.js app"

# Subsequent tasks reuse the same session
openclaw-opencode task "Add authentication middleware"

# Create a new session when you want fresh context
openclaw-opencode task "Start a new Python project" --new-session

Blocking vs Non-blocking:

# Non-blocking mode (default) - Returns taskId, callbacks OpenClaw when done
# Requires callback options: --agent-id, --channel, --to
openclaw-opencode task "Write a Python function to calculate fibonacci" \
  --agent-id myagent \
  --channel telegram \
  --to @username

# Blocking mode - Waits in real-time, outputs result to terminal
# No callback options needed
openclaw-opencode task "Create a React component" --wait

Command Reference

task - Dispatch a Task

openclaw-opencode task <prompt> [options]

Options:

• -c, --callback-url <url> - OpenClaw callback URL (optional, uses env.OPENCLAW_CALLBACK_URL if not set)
• -a, --agent-id <id> - Target agent ID for callback routing (required for async mode)
• --channel <channel> - Message delivery channel for callback, e.g., telegram, slack (required for async mode)
• --to <recipient> - Target recipient for callback message, e.g., @username, #channel (required for async mode)
• -d, --directory <dir> - Working directory
• -w, --wait - Wait for task completion in blocking mode (callback options not required when using this)
• -t, --timeout <minutes> - Timeout in minutes (default: 30)
• -n, --new-session - Create a new session

Note: The --agent-id, --channel, and --to options are only required for async mode (default). They configure where task completion callbacks are sent. Use --wait for blocking mode where these options are not needed.

session - Manage Active Session

# View current session
openclaw-opencode session

# Clear session (next task creates new session)
openclaw-opencode session --clear

status - Check Task Status

openclaw-opencode status <taskId>

list - List All Tasks

openclaw-opencode list
openclaw-opencode list --clear  # Clear completed tasks

Architecture

This CLI runs in the OpenClaw environment and communicates with OpenCode:

┌─────────────────┐      1. Create session      ┌─────────────────┐
│   openclaw-     │  ─────────────────────────→ │   OpenCode      │
│   opencode-cli  │                             │   HTTP API      │
│   (port 4096)   │      2. Send prompt         │   (port 4096)   │
│                 │  ─────────────────────────→ │                 │
│                 │                             │                 │
│                 │      3. Register callback   │   ┌───────────┐ │
│                 │  ─────────────────────────→ │   │ opencode- │ │
│                 │     POST /register          │   │ plugin-   │ │
│                 │                             │   │ openclaw  │ │
│                 │                             │   │ (port 9090)│ │
│                 │                             │   └───────────┘ │
└─────────────────┘                             └─────────────────┘
         ↑                                               │
         │                                               │
         └───────────────────────────────────────────────┘
              4. Plugin sends callback on completion

Flow:

1. CLI creates OpenCode session via HTTP API
2. CLI sends prompt to session
3. CLI registers callback with plugin (POST /register)
4. Plugin monitors session and sends callback to OpenClaw when done

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | OPENCODE_URL | Yes (remote) | - | OpenCode server URL | | OPENCODE_PASSWORD | Yes (remote) | - | HTTP Basic Auth password | | OPENCODE_USERNAME | No | opencode | HTTP Basic Auth username | | OPENCLAW_CALLBACK_URL | No | - | OpenClaw callback URL | | OPENCLAW_API_KEY | No | - | OpenClaw authentication token | | OPENCLAW_AGENT_ID | No | main | Target Agent ID | | LOG_LEVEL | No | info | Log verbosity: debug, info, warn, error |

Session Persistence

Sessions are persisted locally:

• macOS/Linux: ~/.@laceletho-openclaw-opencode-cli/session.json
• Windows: %USERPROFILE%\.@laceletho-openclaw-opencode-cli\session.json

First task creates a session and saves it. Subsequent tasks reuse the saved session. Use --new-session to create a new one.

Logging

The CLI outputs structured logs to stdout/stderr for debugging and monitoring:

Log Levels

Set LOG_LEVEL environment variable to control verbosity:

# Debug mode - detailed logs for troubleshooting
export LOG_LEVEL=debug
openclaw-opencode task "Create a React app"

# Info mode (default) - key events only
export LOG_LEVEL=info
openclaw-opencode task "Create a React app"

# Error mode - errors only
export LOG_LEVEL=error

Log Format

2025-03-13T10:30:45.123Z [openclaw-opencode] [INFO] Task dispatched {"taskId":"sess_abc123","isNewSession":true}
2025-03-13T10:30:45.234Z [openclaw-opencode] [INFO] Session created {"sessionId":"sess_abc123","duration":89}
2025-03-13T10:30:45.456Z [openclaw-opencode] [INFO] Callback registered {"sessionId":"sess_abc123","callbackUrl":"http://localhost:18789/hooks/agent"}

Railway Dashboard

Logs are automatically captured by Railway. View them in your project's Observability tab.

Development

# Install dependencies
npm install

# Development mode
npm run dev

# Build
npm run build

# Type check
npm run typecheck

License

MIT