OpenClaw External Integration

Relevant source files

The following files were used as context for generating this wiki page:

• src/openclaw/AGENTS.md
• README.md
• CONTRIBUTING.md
• src/openclaw/index.ts
• src/openclaw/dispatcher.ts

OpenClaw is a bidirectional integration system designed to bridge the gap between OpenCode sessions and external communication platforms. It provides a mechanism for outbound notifications to services like Discord, Telegram, or custom HTTP webhooks, and inbound reply handling that allows external messages to be injected back into active development sessions.

The system is named "Claw" because it reaches out from the OpenCode environment to external platforms and pulls replies back in, ensuring seamless session continuity even when the developer is away from the terminal. Sources: src/openclaw/AGENTS.md:1-5

Architecture and Bidirectional Flow

The OpenClaw architecture consists of two primary data paths: an outbound notification pipeline and an inbound listener daemon.

Outbound Flow (OpenCode to External)

The outbound flow is triggered by session events within OpenCode. When a session is created, deleted, or becomes idle, the system dispatches an event through a runtime dispatcher. This event is then mapped to a specific OpenClaw payload and sent via a configured gateway.

Inbound Flow (External to OpenCode)

The inbound flow utilizes a separate daemon process that polls external APIs (Discord or Telegram). When a reply is detected, the system correlates the external message ID with the internal session ID using a registry and injects the text into the corresponding tmux pane.

Component Breakdown

The OpenClaw system is modularized into several key functional areas.

Core Lifecycle and Entry Points

The system is initialized during the plugin startup phase. The main entry point manages the lifecycle of the reply listener daemon.

File	Primary Purpose
index.ts	Main entry point containing wakeOpenClaw() and initializeOpenClaw().
daemon.ts	Daemon entry point running as a detached Bun process.
reply-listener.ts	Manages daemon lifecycle, including start/stop and poll loops.

Sources: src/openclaw/AGENTS.md:28-40, CONTRIBUTING.md:121

Dispatchers and Gateways

OpenClaw supports two primary methods for sending data outbound, referred to as "Gateways".

• HTTP Webhook: Sends a POST request with a JSON payload to a specified URL.
• Shell Command: Executes a local shell command, passing data through environment variables prefixed with OPENCLAW_.

The dispatcher.ts module handles the execution of these gateways and supports variable interpolation for payloads. Sources: src/openclaw/AGENTS.md:43-52

Payload Variable Interpolation

When dispatching events, OpenClaw supports several variables that can be interpolated into commands or webhook bodies:

• {sessionId}: The unique identifier for the OpenCode session.
• {projectPath}: The path to the active project.
• {tmuxSession}: The identifier for the tmux session.
• {eventType}: The type of event (e.g., session.created, session.idle).
• {messageContent}: The content of the notification.

Sources: src/openclaw/AGENTS.md:54-56

Security and Constraints

Due to the nature of external integration and remote command injection, OpenClaw implements several security measures:

• URL Validation: HTTPS is mandatory for all external webhooks, with an exception allowed for localhost during development.
• Authorized Users: Inbound replies are strictly filtered against an allowed list of external user IDs to prevent unauthorized session injection.
• Rate Limiting: Injection of keys into tmux panes is throttled to prevent buffer overflows or accidental command spamming.
• Token Redaction: The system automatically masks secrets and sensitive tokens in logs and error reports.

Sources: src/openclaw/AGENTS.md:67-73

Integration with OpenCode

OpenClaw is deeply integrated into the OpenCode lifecycle through specific hooks and configuration schemas:

1. Plugin Startup: src/index.ts calls initializeOpenClaw using the pluginConfig.openclaw settings.
2. Event Hooks: src/plugin/event.ts triggers the outbound dispatcher on specific session state changes.
3. Config Schema: The configuration is validated via Zod in src/config/schema/openclaw.ts.

Sources: src/openclaw/AGENTS.md:58-65, CONTRIBUTING.md:104

Summary

OpenClaw External Integration provides a robust framework for asynchronous interaction with OpenCode. By combining an outbound webhook/shell notification system with an inbound polling daemon, it enables developers to monitor and interact with their AI-driven coding sessions from anywhere. The use of a file-locked JSONL registry (session-registry.ts) and tmux-based injection (tmux.ts) ensures that external messages are routed accurately to the correct terminal environment while maintaining strict security and rate-limiting protocols. Sources: src/openclaw/AGENTS.md:1-73