feat(openclaw): add @ag-ui/openclaw AG-UI client integration

docs/integrations.mdx

@@ -23,6 +23,7 @@ that demonstrate the protocol's capabilities and versatility.
 - **[CrewAI](https://crewai.com)** - Streamline workflows across industries with
   powerful AI agents.
 - **[AG2](https://ag2.ai)** - The Open-Source AgentOS
+- **[OpenClaw](https://github.com/openclaw/openclaw)** - Open-source, self-hostable agent runtime
 
 ## Infrastructure / Deployment
 

integrations/openclaw/typescript/.gitignore

@@ -0,0 +1,141 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+web_modules/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional stylelint cache
+.stylelintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variable files
+.env
+.env.*
+!.env.example
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache
+
+# Next.js build output
+.next
+out
+
+# Nuxt.js build / generate output
+.nuxt
+dist
+.output
+
+# Gatsby files
+.cache/
+# Comment in the public line in if your project uses Gatsby and not Next.js
+# https://nextjs.org/blog/next-9-1#public-directory-support
+# public
+
+# vuepress build output
+.vuepress/dist
+
+# vuepress v2.x temp and cache directory
+.temp
+.cache
+
+# Sveltekit cache directory
+.svelte-kit/
+
+# vitepress build output
+**/.vitepress/dist
+
+# vitepress cache directory
+**/.vitepress/cache
+
+# Docusaurus cache and generated files
+.docusaurus
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# Firebase cache directory
+.firebase/
+
+# TernJS port file
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+.vscode-test
+
+# yarn v3
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+
+# Vite files
+vite.config.js.timestamp-*
+vite.config.ts.timestamp-*
+.vite/

integrations/openclaw/typescript/.npmignore

@@ -0,0 +1,12 @@
+.nx
+.DS_Store
+.git
+.gitignore
+.idea
+.vscode
+.env
+__tests__
+src
+tsdown.config.ts
+tsconfig.json
+vitest.config.ts

integrations/openclaw/typescript/README.md

@@ -0,0 +1,68 @@
+# OpenClaw
+
+Implementation of the AG-UI protocol for [OpenClaw](https://github.com/openclaw/openclaw).
+
+`OpenClawAgent` connects an AG-UI / CopilotKit frontend to an OpenClaw gateway
+that speaks the AG-UI protocol over HTTP/SSE through the
+[`clawg-ui`](https://www.npmjs.com/package/@contextableai/clawg-ui) channel
+plugin. The plugin self-registers an AG-UI endpoint on the gateway (the
+operator-auth route `/v1/clawg-ui/operator`), so the client talks to it exactly
+like any other self-hosted AG-UI HTTP backend — no framework-specific transport
+is required.
+
+`OpenClawAgent` is a thin extension of the standard
+[`HttpAgent`](https://www.npmjs.com/package/@ag-ui/client). OpenClaw emits the
+current AG-UI protocol (streaming text, reasoning, tool calls), so no protocol
+version capping is applied.
+
+## Features
+
+- **Operator-token auth built in** — pass the gateway token as `gatewayToken` and
+  it is attached as `Authorization: Bearer <token>` on every request; no manual
+  header assembly.
+- **Standard AG-UI transport** — a thin `HttpAgent` subclass, so it works with any
+  AG-UI / CopilotKit frontend over HTTP/SSE with no framework-specific glue.
+- **No protocol capping** — OpenClaw emits the current AG-UI protocol (streaming
+  text, reasoning, tool calls), so no version ceiling is applied.
+
+## Installation
+
+```shell
+npm install @ag-ui/openclaw
+# or
+pnpm add @ag-ui/openclaw
+# or
+yarn add @ag-ui/openclaw
+```
+
+`@ag-ui/core`, `@ag-ui/client`, and `rxjs` are peer dependencies.
+
+## Usage
+
+```ts
+import { OpenClawAgent } from "@ag-ui/openclaw";
+
+const agent = new OpenClawAgent({
+  // The clawg-ui operator route exposed by the OpenClaw gateway.
+  url: "http://localhost:8000/v1/clawg-ui/operator",
+  // The gateway operator token — sent as `Authorization: Bearer <token>`.
+  gatewayToken: process.env.OPENCLAW_GATEWAY_TOKEN,
+  // Seed the conversation; the agent replies to these on the first run.
+  initialMessages: [{ id: "1", role: "user", content: "Hello from AG-UI!" }],
+});
+
+const result = await agent.runAgent();
+```
+
+`OpenClawAgent` accepts the same configuration as `HttpAgent` (`url`, `headers`,
+`fetch`, `agentId`, `threadId`, `initialMessages`, `initialState`, `debug`), plus
+`gatewayToken` — a convenience that becomes the `Authorization: Bearer` header
+(authoritative over any `Authorization` passed in `headers`).
+
+## Prerequisites
+
+An OpenClaw gateway running with the `clawg-ui` plugin installed and a gateway
+token configured. See the [OpenClaw](https://github.com/openclaw/openclaw)
+documentation for setting up and running a gateway, and the
+[`clawg-ui`](https://www.npmjs.com/package/@contextableai/clawg-ui) plugin for
+installing and exposing the AG-UI endpoint.

integrations/openclaw/typescript/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@ag-ui/openclaw",
+  "version": "0.0.1",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ag-ui-protocol/ag-ui.git"
+  },
+  "author": "AG-UI Team",
+  "license": "Apache-2.0",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "dist/**",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "clean": "git clean -fdX --exclude=\"!.env\"",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "test:exports": "publint --strict && attw --pack",
+    "link:global": "pnpm link --global",
+    "unlink:global": "pnpm unlink --global"
+  },
+  "peerDependencies": {
+    "@ag-ui/core": ">=0.0.37",
+    "@ag-ui/client": ">=0.0.37",
+    "rxjs": "7.8.1"
+  },
+  "devDependencies": {
+    "@ag-ui/core": "workspace:*",
+    "@ag-ui/client": "workspace:*",
+    "@arethetypeswrong/cli": "^0.17.4",
+    "@types/node": "^20.11.19",
+    "@vitest/coverage-istanbul": "^4.0.18",
+    "publint": "^0.3.12",
+    "tsdown": "^0.20.1",
+    "typescript": "^5.3.3",
+    "vitest": "^4.0.18"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  }
+}

integrations/openclaw/typescript/src/index.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from "vitest";
+import { OpenClawAgent } from "./index";
+import { HttpAgent } from "@ag-ui/client";
+
+const URL = "http://localhost:8000/v1/clawg-ui/operator";
+
+describe("OpenClawAgent", () => {
+  it("is a subclass of HttpAgent", () => {
+    expect(OpenClawAgent.prototype).toBeInstanceOf(HttpAgent);
+  });
+
+  it("constructs with just a url", () => {
+    const agent = new OpenClawAgent({ url: URL });
+    expect(agent).toBeInstanceOf(OpenClawAgent);
+    expect(agent).toBeInstanceOf(HttpAgent);
+  });
+
+  it("maps gatewayToken to an Authorization: Bearer header", () => {
+    const agent = new OpenClawAgent({ url: URL, gatewayToken: "secret-token" });
+    expect(agent.headers.Authorization).toBe("Bearer secret-token");
+  });
+
+  it("sends no Authorization header when gatewayToken is omitted", () => {
+    const agent = new OpenClawAgent({ url: URL });
+    expect(agent.headers.Authorization).toBeUndefined();
+  });
+
+  it("gatewayToken wins over Authorization in headers, other headers preserved", () => {
+    const agent = new OpenClawAgent({
+      url: URL,
+      gatewayToken: "token-wins",
+      headers: { Authorization: "Bearer old", "X-Custom": "keep" },
+    });
+    expect(agent.headers.Authorization).toBe("Bearer token-wins");
+    expect(agent.headers["X-Custom"]).toBe("keep");
+  });
+});

integrations/openclaw/typescript/src/index.ts

@@ -0,0 +1,45 @@
+/**
+ * OpenClaw integration for the AG-UI protocol.
+ *
+ * Connects an AG-UI / CopilotKit frontend to an OpenClaw gateway that speaks the
+ * AG-UI protocol over HTTP/SSE via the `clawg-ui` channel plugin (e.g. the
+ * operator route `/v1/clawg-ui/operator`). OpenClaw speaks the current AG-UI
+ * protocol, so the standard `HttpAgent` transport handles the request/response
+ * as-is — no version capping required.
+ *
+ * @see https://github.com/openclaw/openclaw
+ */
+
+import { HttpAgent, type HttpAgentConfig } from "@ag-ui/client";
+
+/**
+ * Config for {@link OpenClawAgent}. Extends the base `HttpAgent` config with a
+ * first-class `gatewayToken` — the OpenClaw gateway operator token — so callers
+ * pass the secret directly instead of hand-assembling an `Authorization` header.
+ */
+export interface OpenClawAgentConfig extends HttpAgentConfig {
+  /**
+   * OpenClaw gateway operator token. When set, the agent sends
+   * `Authorization: Bearer <gatewayToken>` on every request to the clawg-ui
+   * operator route. Omit (or leave empty) to send no auth header.
+   */
+  gatewayToken?: string;
+}
+
+/**
+ * `HttpAgent` for an OpenClaw gateway's `clawg-ui` operator route. Its one
+ * addition over `HttpAgent` is the `gatewayToken` convenience: pass the operator
+ * token and it becomes the `Authorization: Bearer` header (authoritative over any
+ * `Authorization` supplied in `headers`).
+ */
+export class OpenClawAgent extends HttpAgent {
+  constructor({ gatewayToken, headers, ...rest }: OpenClawAgentConfig) {
+    super({
+      ...rest,
+      headers: {
+        ...headers,
+        ...(gatewayToken ? { Authorization: `Bearer ${gatewayToken}` } : {}),
+      },
+    });
+  }
+}

integrations/openclaw/typescript/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "es2017",
+    "module": "esnext",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "moduleResolution": "node",
+    "skipLibCheck": true,
+    "strict": true,
+    "jsx": "react-jsx",
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "types": ["vitest/globals"],
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    },
+    "stripInternal": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}