openclaw-go

March 25, 2026 · View on GitHub

The Go client library for OpenClaw — the open gateway for AI agents. Maintained by A3T.

go get github.com/a3tai/openclaw-go

Provides typed clients for the Gateway WebSocket protocol, OpenAI-compatible HTTP APIs, local network discovery, and the Agent Client Protocol (ACP).

Install

go get github.com/a3tai/openclaw-go

Requires Go 1.25+. The only external dependency is gorilla/websocket.

Packages

Package	Import	Description
`protocol`	`github.com/a3tai/openclaw-go/protocol`	Wire types, constants, and serialization for the Gateway WebSocket protocol (v3)
`gateway`	`github.com/a3tai/openclaw-go/gateway`	WebSocket client with full handshake, 96+ typed RPC methods, event/invoke callbacks
`chatcompletions`	`github.com/a3tai/openclaw-go/chatcompletions`	OpenAI-compatible Chat Completions HTTP client (streaming + non-streaming)
`openresponses`	`github.com/a3tai/openclaw-go/openresponses`	OpenAI Responses API HTTP client with typed SSE events and tool calling
`toolsinvoke`	`github.com/a3tai/openclaw-go/toolsinvoke`	Tools Invoke HTTP client (`POST /tools/invoke`)
`discovery`	`github.com/a3tai/openclaw-go/discovery`	mDNS/DNS-SD local network gateway discovery
`acp`	`github.com/a3tai/openclaw-go/acp`	Agent Client Protocol (JSON-RPC 2.0 over NDJSON) server for IDE integration

Quick Start

Gateway WebSocket Client

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/a3tai/openclaw-go/gateway"
	"github.com/a3tai/openclaw-go/protocol"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()

	client := gateway.NewClient(
		gateway.WithToken("my-token"),
		gateway.WithOnEvent(func(ev protocol.Event) {
			fmt.Printf("event: %s\n", ev.EventName)
		}),
	)
	defer client.Close()

	if err := client.Connect(ctx, "ws://localhost:18789/ws"); err != nil {
		log.Fatal(err)
	}

	result, err := client.ChatSend(ctx, protocol.ChatSendParams{
		SessionKey: "main",
		Message:    "Hello from Go!",
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("chat response: %+v\n", result)
}

Chat Completions (OpenAI-compatible)

client := &chatcompletions.Client{
	BaseURL: "http://localhost:18789",
	Token:   "my-token",
}

resp, _ := client.Create(ctx, chatcompletions.Request{
	Model:    "openclaw:main",
	Messages: []chatcompletions.Message{
		{Role: "user", Content: "Hello!"},
	},
})
fmt.Println(resp.Choices[0].Message.Content)

// Streaming
stream, _ := client.CreateStream(ctx, chatcompletions.Request{
	Model:    "openclaw:main",
	Messages: []chatcompletions.Message{
		{Role: "user", Content: "Tell me about Go"},
	},
})
defer stream.Close()

for {
	chunk, err := stream.Recv()
	if err == io.EOF { break }
	fmt.Print(chunk.Choices[0].Delta.Content)
}

Tools Invoke

client := &toolsinvoke.Client{
	BaseURL: "http://localhost:18789",
	Token:   "my-token",
}

resp, _ := client.Invoke(ctx, toolsinvoke.Request{
	Tool:   "sessions_list",
	Action: "json",
})
fmt.Printf("result: %s\n", resp.Result)

Network Discovery

browser := discovery.NewBrowser()
beacons, _ := browser.Browse(ctx)
for _, b := range beacons {
	fmt.Printf("%s -> %s\n", b.DisplayName, b.WebSocketURL())
}

Examples

Runnable examples are in examples/. Start the mock server first:

go run ./examples/server

Then run any example:

go run ./examples/chat
go run ./examples/client
go run ./examples/openresponses
go run ./examples/agents
go run ./examples/sessions
go run ./examples/approvals
go run ./examples/pairing
go run ./examples/config
go run ./examples/cron
go run ./examples/node
go run ./examples/discovery
go run ./examples/acp

Example	What it demonstrates
`server`	Mock gateway for local development
`client`	All three APIs: WebSocket, Chat Completions, Tools Invoke
`chat`	Interactive chat with streaming events
`openresponses`	OpenAI Responses API with tool definitions
`agents`	Agent CRUD: list, create, update, files, delete
`sessions`	Session management: list, preview, patch, usage, reset
`approvals`	Exec approval flow: listen, approve/reject, admin config
`pairing`	Node and device pairing workflows
`config`	Gateway configuration: get, schema, patch, apply
`cron`	Cron jobs: list, add, run, history, remove
`node`	Connect as a node: declare capabilities, handle invocations
`discovery`	Scan the LAN for gateways via mDNS
`acp`	ACP agent server over stdio

Testing

go test ./... -race
go vet ./...

All library packages target 100% statement coverage (except discovery/ at 98.2% due to platform exec wrappers).

Documentation

See the docs/ directory for per-package API guides:

About

This project is independently maintained by Rude Company LLC (d/b/a a3t.ai) and is not officially affiliated with the OpenClaw project.

Many thanks to Peter Steinberger for creating OpenClaw and giving it to the world. His vision for an open, local-first AI gateway has made projects like this possible. With all love and respect.

Author: Steve Rude steve@a3t.ai

License

MIT -- see LICENSE for details.