Gateway Service
Relevant source files
The following files were used as context for generating this wiki page:
The Gateway Service is the central communication hub of the Clawdbot ecosystem. It operates as a multiplexed server handling both WebSocket and HTTP traffic, facilitating coordination between agents, messaging channels (like Telegram, Discord, and Slack), and the user-facing Control UI. The service can run in two primary modes: local, where the gateway is managed on the host machine, or remote, where the CLI connects to an existing external gateway instance.
The service is responsible for critical infrastructure tasks including session management, AI model completions, tool execution routing, and system updates. It serves as the primary RPC target for CLI commands and is often managed as a background daemon using platform-specific service managers like launchd on macOS, systemd on Linux, or schtasks on Windows.
Sources: src/config/types.gateway.ts, src/commands/status.command.ts:60-100, src/cli/daemon-cli/status.print.ts:50-70
Architecture and Core Components
The Gateway architecture is designed to be highly portable and manageable across different operating systems. It utilizes a multiplexed port (defaulting to 18789) to serve both the WebSocket-based RPC API and the HTTP-based Control UI and completion endpoints.
Service Modes and Deployment
The Gateway can be deployed as a managed service on multiple platforms. The system identifies and manages these via the resolveGatewayService() helper, which abstracts the underlying platform's service manager.
| Platform | Service Manager | Label/Name Resolution |
|---|---|---|
| macOS | launchd | resolveGatewayLaunchAgentLabel |
| Linux | systemd | resolveGatewaySystemdServiceName |
| Windows | schtasks | resolveGatewayWindowsTaskName |
Sources: src/commands/doctor-gateway-services.ts:13-17, src/cli/daemon-cli/shared.ts:135-150
Connection Flow
The Gateway supports secure and authenticated connections. Authentication can be handled via shared tokens or passwords. For remote connections, the system supports both direct WebSocket (direct) and SSH-tunneled (ssh) transports.
Core Functionality
1. RPC and API Methods
The Gateway exposes several internal methods that can be invoked via WebSocket RPC. Key methods include:
health: Returns aHealthSummaryincluding channel status and latency.config.apply: Validates and writes a new configuration to disk, often triggering a service restart.usage.cost: Aggregates token usage and cost data from session logs.system-presence: Manages agent and node availability.
Sources: src/cli/gateway-cli/register.ts:150-200, src/gateway/server.config-apply.e2e.test.ts:40-55
2. Service Management (Daemon Operations)
The CLI provides a suite of commands to manage the Gateway as a background daemon. This includes installing the service with specific runtimes (Node or Bun) and handling graceful restarts.
3. HTTP Endpoints
Beyond WebSocket communication, the Gateway can be configured to serve OpenAI-compatible endpoints:
POST /v1/chat/completions: Proxies chat completion requests to the configured providers.POST /v1/responses: Implements the OpenResponses API for file and image inputs.
Sources: src/config/types.gateway.ts:108-125
Configuration and Discovery
Gateway Configuration Options
The GatewayConfig structure defines how the server binds to network interfaces and manages security.
| Option | Type | Description |
|---|---|---|
port | number | The port the Gateway listens on (Default: 18789). |
bind | GatewayBindMode | Binding policy: auto, lan, loopback, custom, or tailnet. |
mode | "local" | "remote" | Determines if the local machine should start the gateway. |
auth.mode | "token" | "password" | The authentication scheme for incoming connections. |
tls.enabled | boolean | Enables HTTPS/WSS for the Gateway server. |
Sources: src/config/types.gateway.ts:180-230
Discovery Mechanism
The Gateway supports local and wide-area discovery via Bonjour (multicast DNS) and Unicast DNS. This allows clients to find available gateways on the local network or via specific domains like discovery.clawd.bot.
Sources: src/cli/gateway-cli/register.ts:250-280, src/cli/gateway-cli/discover.ts
Diagnostic and Repair Tools
The Gateway Service includes extensive self-diagnostic capabilities via the doctor command. This system performs:
- Service Audit: Detects if the gateway entrypoint matches the current install and if the configuration is out of date.
- Runtime Migration: Offers to migrate the service between runtimes (e.g., from Bun to Node 22+).
- Conflict Detection: Identifies "extra" gateway-like services running on the same host and provides cleanup hints.
- Health Probes: Verifies reachability and RPC responsiveness.
Sources: src/commands/doctor-gateway-services.ts:70-130, src/commands/doctor.ts:100-150
Conclusion
The Gateway Service is the backbone of Clawdbot, providing a unified interface for agents and external messaging platforms. Its modular design allows it to adapt to various deployment environments while maintaining strict security through token-based authentication and sandboxed runtime support. By centralizing configuration, usage tracking, and model access, it ensures a consistent state across all connected Clawdbot components.