The Gateway Protocol
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Gateway Protocol is the central communication layer of the Clawdbot ecosystem, enabling structured interaction between the Clawdbot Gateway daemon and various clients, including the macOS menubar app, mobile applications, and CLI tools. It defines a rigid schema for requests, responses, and events, ensuring type-safe message passing across different programming environments such as TypeScript and Swift.
The protocol facilitates essential operations such as tool invocation, status reporting, configuration management, and agent-specific interactions. By standardizing these communications, the protocol allows for a decoupled architecture where the core logic of the Gateway can be accessed by diverse front-ends and sub-agents.
Core Architecture and Framing
The protocol utilizes a "Gateway Frame" structure to wrap all communications. Every message sent over the protocol is categorized into one of three primary types: requests, responses, or events. This framing ensures that every transaction is identifiable and can be tracked via unique IDs when necessary.
Gateway Frame Types
| Frame Type | Description |
|---|---|
Request (req) | Initiated by a client to perform an action or fetch data. |
Response (res) | Sent by the Gateway in direct reply to a specific request. |
Event (event) | Asynchronous notifications sent by the Gateway to subscribed clients. |
Sources: scripts/protocol-gen-swift.ts:133-140, src/gateway/protocol/schema.ts
Message Flow Diagram
The following diagram illustrates the lifecycle of a typical request-response cycle and the asynchronous nature of events within the protocol.
Protocol Schema and Data Models
The protocol is strictly defined using a JSON Schema-based approach in TypeScript, which is then used to generate native models for other platforms, such as Swift for the macOS application.
Error Handling
The protocol defines a standardized set of ErrorCodes to ensure that clients can programmatically handle failures. Common errors include authentication failures, tool execution errors, and invalid request formats.
Sources: scripts/protocol-gen-swift.ts:39-44, src/gateway/protocol/schema.ts
Payload Structures
The protocol defines several key payload objects used within frames:
- RequestFrame: Contains the
id,method, andparams. - ResponseFrame: Contains the
id, optionalresultdata, and optionalerrordetails. - EventFrame: Contains the
typeand associatedpayload.
Sources: scripts/protocol-gen-swift.ts:108-131
Runtime and Environment Interaction
The Gateway Protocol is closely tied to the environment in which the daemon runs. The protocol allows clients to query and verify the gateway's state, including its version, reachability, and configuration.
Connectivity and Bind Modes
The Gateway supports several binding modes to control accessibility, which are communicated and configured via the protocol environment.
| Bind Mode | Description |
|---|---|
loopback | Accessible only on the local machine (default). |
tailnet | Accessible over a Tailscale network. |
lan | Accessible over the local area network. |
auto | Automatically selects the best available binding. |
Sources: apps/macos/Sources/Clawdbot/GatewayEnvironment.swift:92-92, apps/macos/Sources/Clawdbot/GatewayEnvironment.swift:154-173
Versioning and Compatibility
To prevent protocol mismatches, the Gateway includes a GATEWAY_PROTOCOL_VERSION. Clients verify compatibility by checking the major version of the Gateway against their internal required version. A lightweight SemVer helper is used to compare major.minor.patch versions.
Sources: apps/macos/Sources/Clawdbot/GatewayEnvironment.swift:6-41, scripts/protocol-gen-swift.ts:37-37
Tooling and Agent Integration
The protocol serves as the bridge for "Tool Invocation." When an agent needs to perform an action (e.g., reading a file or searching the web), the request is routed through the protocol to the appropriate handler.
Core Protocol Tools
The system prompt defines a standard set of tools that are exposed or managed via protocol interactions:
- File Operations:
read,write,edit,ls,find. - Execution:
exec,process(managing background sessions). - Communication:
message(sending messages to channels like Telegram/Discord). - System:
gateway(restarting, applying config, or running updates). - Session Management:
sessions_spawn,sessions_list,session_status.
Sources: src/agents/system-prompt.ts:153-180, src/agents/system-prompt.ts:257-275
Status Reporting
The protocol enables deep probing of the system state, which is consumed by the status command. This includes:
- Gateway Reachability: Checking if the daemon is alive and its connection latency.
- Agent Activity: Reporting which agents are active and their last activity age.
- Security Audits: Relaying critical and warning findings from security scans.
Sources: src/commands/status.command.ts:47-90, src/commands/status.command.ts:143-165
Implementation Details
Swift Generation
The project uses a TypeScript script (scripts/protocol-gen-swift.ts) to automate the generation of Swift struct and enum definitions. This ensures the macOS app stays in sync with protocol changes. The script maps TypeScript types to Swift equivalents (e.g., string to String, array to [T]) and handles reserved keywords by prepending underscores.
Sources: scripts/protocol-gen-swift.ts:68-106
Gateway CLI and Dev Mode
For development, the protocol can be initialized in a "dev" mode, which sets up a local gateway with a specific identity (e.g., "C3-PO", a protocol droid) and a dev workspace. This mode bypasses standard onboarding to allow for rapid testing of protocol changes.
Sources: src/cli/gateway-cli/dev.ts:11-21, src/cli/gateway-cli/dev.ts:74-98
Conclusion
The Gateway Protocol provides the essential structural integrity required for Clawdbot's multi-platform and agent-based architecture. By utilizing a strictly defined schema and automated code generation, the project ensures that communication remains reliable and type-safe across diverse environments, from low-level CLI tools to high-level GUI applications.