<!-- source: https://deepwiki.com/openclaw/openclaw/2.9-client-sdk -->

# Client SDK

- docs/cli/agent.md
- docs/tools/agent-send.md
- packages/gateway-client/src/client.ts
- packages/gateway-client/src/client.watchdog.test.ts
- packages/sdk/src/client.ts
- packages/sdk/src/index.test.ts
- packages/sdk/src/normalize.ts
- src/agents/agent-run-terminal-outcome.test.ts
- src/agents/agent-run-terminal-outcome.ts
- src/agents/command/types.ts
- src/agents/run-wait.test.ts
- src/agents/run-wait.ts
- src/cli/gateway-dispatch-dotenv.ts
- src/cli/program/command-registry-core.ts
- src/cli/program/command-registry.test.ts
- src/cli/program/register.agent-turn.ts
- src/cli/program/register.agent.test.ts
- src/cli/program/register.agent.ts
- src/commands/agent-via-gateway.test.ts
- src/commands/agent-via-gateway.ts
- src/config/config.talk-validation.test.ts
- src/config/gateway-dispatch-config.test.ts
- src/config/gateway-dispatch-config.ts
- src/gateway/call.test.ts
- src/gateway/call.ts
- src/gateway/chat-abort.test.ts
- src/gateway/chat-abort.ts
- src/gateway/client.test.ts
- src/gateway/client.ts
- src/gateway/client.watchdog.test.ts
- src/gateway/connection-details.ts
- src/gateway/server-chat-state.ts
- src/gateway/server-maintenance.test.ts
- src/gateway/server-maintenance.ts
- src/gateway/server-methods/agent-job.ts
- src/gateway/server-methods/agent-wait-dedupe.test.ts
- src/gateway/server-methods/agent-wait-dedupe.ts
- src/gateway/server-methods/agent.test.ts
- src/gateway/server-methods/agent.ts
- src/gateway/server-methods/chat.abort-authorization.test.ts
- src/gateway/server-methods/chat.abort-persistence.test.ts
- src/gateway/server-methods/chat.abort.test-helpers.ts
- src/gateway/server-methods/server-methods.test.ts
- src/gateway/server-methods/session-active-runs.ts
- src/gateway/server.node-version-mismatch.test.ts
- src/gateway/session-lifecycle-state.test.ts
- src/gateway/session-lifecycle-state.ts
- src/infra/agent-events.test.ts
- src/infra/agent-events.ts
- src/infra/dotenv-global.ts
- src/infra/dotenv.ts
- src/node-host/runner.credentials.test.ts
- src/node-host/runner.ts
- test/vitest/vitest.gateway-client.config.ts

The OpenClaw Client SDK (`@openclaw/sdk`) is a TypeScript/JavaScript package located in `packages/sdk` that provides a high-level, programmatic interface for interacting with the OpenClaw Gateway. It wraps the [Gateway WebSocket protocol](/openclaw/openclaw/2.1-websocket-protocol-and-rpc) (v4) into a structured class-based API, handling handshakes, authentication, request-response multiplexing, and event distribution.

## Core Architecture

The SDK is designed around the `OpenClaw` class, which serves as the primary entry point. It organizes Gateway functionality into logical namespaces (e.g., `Agents`, `Sessions`, `Runs`, `Tasks`) and manages the underlying WebSocket lifecycle through the `GatewayClient`.

### SDK Entity Mapping

The following diagram illustrates how the SDK bridges high-level TypeScript calls to the low-level WebSocket frames defined in the protocol.

Title: SDK Internal Mapping to Gateway

```

```

Sources: [packages/sdk/src/client.ts1-200](https://github.com/openclaw/openclaw/blob/fbdf5937/packages/sdk/src/client.ts#L1-L200) [src/gateway/server-methods/agent.ts155-159](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-methods/agent.ts#L155-L159) [src/gateway/server-methods/chat.ts30-37](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-methods/chat.ts#L30-L37)

## Key Classes and Implementation

### The OpenClaw Class

The `OpenClaw` class is the central coordinator. It initializes the transport and provides access to the functional namespaces. It handles the initial `connect` handshake required by the protocol.

- Handshake : On startup, it sends a ConnectParams structure containing client identification, protocol versions, required scopes , and auth credentials.
- Authentication : Supports multiple modes: token-based ( auth.token ), password-based, and device-based identity signatures.
- Protocol Versioning : The SDK negotiates protocol version 4, ensuring compatibility with the Gateway's current feature set. src/gateway/client.ts 141-142

### GatewayClientTransport

The `GatewayClient` manages the `WebSocket` connection. It is responsible for:

1. Framing : Wrapping method calls into RequestFrame objects with unique id strings generated via randomUUID . src/gateway/server-methods/agent.ts 1-15
2. Multiplexing : Tracking pending requests and resolving the correct promise when a ResponseFrame arrives.
3. Connection Options : Configurable parameters include url , requestTimeoutMs , and deviceToken . It manages device identity and signing via signDevicePayload . src/gateway/client.ts 111-150 src/gateway/client.ts 213-219

### EventHub

The `EventHub` processes incoming `EventFrame` messages. It allows clients to stream real-time updates.
Key event types include:

- Transcript Updates : Real-time streaming of agent reasoning and tool outputs.
- Lifecycle Events : phase: "start" , phase: "end" , and phase: "error" notifications for agent runs. src/gateway/server-methods/server-methods.test.ts 93-107
- Task Completion : AGENT_INTERNAL_EVENT_TYPE_TASK_COMPLETION events for backgrounded operations. src/gateway/server-methods/agent.ts 37-38

## Functional Namespaces

The SDK exposes Gateway methods through typed namespaces, mirroring the `GatewayRequestHandlers` defined in the server. [src/gateway/server-methods/agent.ts155-159](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-methods/agent.ts#L155-L159)

Sources: [src/gateway/server-methods/agent.ts20-23](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-methods/agent.ts#L20-L23) [src/gateway/server-methods/exec-approval.ts38-39](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-methods/exec-approval.ts#L38-L39)

## Request-Response Flow

Every request initiated by the SDK follows a lifecycle involving unique IDs and typed frames. For example, `agent.wait` uses the `waitForTerminalGatewayDedupe` mechanism to synchronize terminal run states. [src/gateway/server-methods/agent-wait-dedupe.ts152-153](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-methods/agent-wait-dedupe.ts#L152-L153)

Title: Agent Wait Sequence Flow

```

```

Sources: [src/agents/run-wait.ts208-222](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/run-wait.ts#L208-L222) [src/gateway/server-methods/agent.ts146-153](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-methods/agent.ts#L146-L153)

## Error Handling

The SDK surfaces Gateway errors using standard `ErrorCodes` defined in the protocol package. [src/gateway/server-methods/agent.ts17-23](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-methods/agent.ts#L17-L23)

- Validation Errors : The SDK/Gateway validates parameters (e.g., validateAgentParams , validateAgentWaitParams ) before execution. src/gateway/server-methods/agent.ts 20-23
- Recoverable Errors : The SDK identifies recoverable connection issues (e.g., ECONNRESET , socket hang up , gateway closed (1006) ) to trigger automatic reconnection or retry logic in the execution pipeline. src/agents/run-wait.ts 120-130
- Timeouts : Requests that exceed requestTimeoutMs or agent runs that hit hard limits return a timeout status. The SDK uses normalizeAgentRunTimeoutPhase to attribute the timeout to either the provider or the local runtime. src/agents/run-wait.ts 100-101 src/gateway/server-methods/agent.ts 41-43

Sources: [src/gateway/server-methods/agent.ts17-23](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-methods/agent.ts#L17-L23) [src/agents/run-wait.ts120-130](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/run-wait.ts#L120-L130) [src/agents/run-timeout-attribution.ts41-43](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/run-timeout-attribution.ts#L41-L43)
