src/openclaw/

June 15, 2026 · View on GitHub

Generated: 2026-05-15

OVERVIEW

This module provides a bidirectional integration system: outbound session event notifications (Discord/Telegram/HTTP webhook/shell command) AND inbound reply handling (daemon polls chat apps, injects replies back into tmux session). Harness-neutral gateway, daemon, session registry, and tmux injection primitives are extracted to packages/openclaw-core/; this directory keeps OpenCode startup/event wiring stable.

BIDIRECTIONAL FLOW

Outbound (OpenCode → External)

OpenCode session event → dispatchOpenClawEvent()
  → runtime-dispatch.ts: map event to OpenClaw event
  → dispatcher.ts: execute gateway (HTTP POST or shell command)
  → session-registry.ts: record message ID ↔ sessionID ↔ tmux pane

Inbound (External → OpenCode)

Discord/Telegram API → reply-listener daemon (separate Bun process)
  → reply-listener-{discord,telegram}.ts: poll every 3s
  → session-registry.ts: look up target tmux session from message ID
  → reply-listener-injection.ts: send-keys into tmux pane (rate limited)

KEY FILES

File	Purpose
`index.ts`	`wakeOpenClaw()`, `initializeOpenClaw()` — main entry
`types.ts`	`OpenClawConfig`, `OpenClawPayload`, `WakeResult` types
`config.ts`	Gateway resolution + URL validation (HTTPS required, localhost exception)
`dispatcher.ts`	HTTP POST + shell command execution with variable interpolation
`runtime-dispatch.ts`	Maps OpenCode events → OpenClaw events, orchestrates dispatch
`session-registry.ts`	JSONL registry correlating message IDs ↔ sessions ↔ panes (file-locked)
`reply-listener.ts`	Daemon lifecycle: start/stop, poll loop, state persistence
`reply-listener-discord.ts`	Discord API polling
`reply-listener-telegram.ts`	Telegram API polling
`reply-listener-injection.ts`	Inject received reply into tmux pane (rate limiting + user filtering)
`reply-listener-state.ts`	Daemon state: PID, config signature, poll tracking
`daemon.ts`	Daemon entry point (runs as detached Bun process)
`tmux.ts`	`capturePane()`, `sendToPane()` utilities

GATEWAY TYPES

Type	Config	Execution
HTTP webhook	`url` field	POST with JSON payload
Shell command	`command` field	Execute with env vars (OPENCLAW_*)

PAYLOAD VARIABLES (interpolation)

{sessionId}, {projectPath}, {tmuxSession}, {timestamp}, {eventType} (session.created/deleted/idle), {messageContent}, {promptSummary}

INTEGRATION POINTS

src/index.ts — calls initializeOpenClaw(pluginConfig.openclaw) at plugin startup (if enabled)
src/plugin/event.ts — calls dispatchOpenClawEvent() for session.created/deleted/idle
src/config/schema/openclaw.ts — Zod config schema

DAEMON LIFECYCLE

initializeOpenClaw(config)
  → wakeOpenClaw() if reply_listener.enabled
  → spawn daemon.ts as detached process
  → daemon writes PID to .opencode/openclaw.state.json
  → daemon polls Discord/Telegram every 3s
  → on reply: lookup in session-registry → inject into tmux via send-keys

SECURITY

URL validation: HTTPS required except localhost (config.ts)
Authorized users: Inbound replies filtered by allowed user ID list
Token redaction: Secrets masked in logs and error messages
Rate limiting: Reply injection throttled per pane