OpenClaw just landed a native AG-UI channel (see our news coverage for the background), which means you no longer need a hand-rolled bridge to put an OpenClaw agent inside a React, Vue, Angular, or Slack frontend. This walkthrough covers what’s actually confirmed in the shipping PR (#109203) — every command below is pulled directly from that source.

⚠️ Note before you start: At time of writing, PR #109203 is open against main and described by the maintainers as mergeable, but not yet merged. Check the PR status before assuming the channel is available in your installed OpenClaw version — refer to the official openclaw/openclaw releases page to confirm which version first ships this feature.

What This Channel Does

The ag-ui extension exposes your OpenClaw gateway over the AG-UI protocol — the open standard that CopilotKit and other AG-UI clients use to drive agents. Per the PR description, it supports:

  • Streamed responses, live token-by-token
  • Generative UI (rendering real components — forms, charts, cards — inside the conversation, not just text)
  • Frontend tools that run in the browser and read/write the app’s own state
  • Human-in-the-loop pauses for approval before continuing
  • Multimodal input (not just plain text)

It plugs into OpenClaw’s existing channel lifecycle (discovery → config → activation) and runs every turn through the standard runEmbeddedAgent path, so your existing conversation history, compaction, and tool-rendering behavior carry over unchanged.

Step 1: Enable the Channel

Edit your gateway config at ~/.openclaw/openclaw.json and add the ag-ui channel:

{
  "channels": {
    "ag-ui": {
      "enabled": true,
      "name": "AG-UI"
    }
  }
}

This exact snippet is copied from the PR’s “Running it” section — no invented flags.

Step 2: Restart the Gateway

openclaw gateway run

When the channel activates successfully, the PR’s own captured log output shows a line like:

[gateway] http server listening (12 plugins: ag-ui, anthropic, bonjour, browser, canvas, device-pair, file-transfer, linux-canvas, linux-node, memory-core, ollama, talk-voice; 1.9s)
[ag-ui] [default] AG-UI channel active (HTTP endpoint ready)

If ag-ui doesn’t appear in your plugin list, the channel either isn’t enabled correctly in your config or your OpenClaw build predates the merge — refer to the official documentation or PR discussion for the exact version cutoff.

Step 3: Understand the Two Auth Routes

The channel serves two distinct HTTP routes, and picking the right one matters for security:

Route 1 — POST /v1/ag-ui/operator (trusted server-side integrations)

This route uses gateway-token auth, scoped to operator.write. Use this when your backend server holds the token and the token never reaches an end user’s browser.

curl -N http://localhost:8000/v1/ag-ui/operator \
  -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" -H "Accept: text/event-stream" \
  -d '{"messages":[{"role":"user","content":"Say hello in 3 words"}]}'

This curl command is copied verbatim from the PR body.

Route 2 — POST /v1/ag-ui (device pairing, for untrusted/external clients)

This route is meant for clients you don’t fully trust with the master gateway token — for example, a public-facing web app. Instead of a shared token, it uses per-client device pairing. The PR’s own live-run log shows the pairing flow: an unauthenticated request returns an HTTP 403 with a pairing_pending response containing a pairing code and instructions, e.g.:

{"pairing_code":"***","bearer_token":"***","error":{"type":"pairing_pending","message":"Device pending approval","pairing":{"pairingCode":"***","token":"***","instructions":"Save this token for use as a Bearer token and ask the owner to approve: openclaw pairing approve ag-ui ***"}}}

The owner then approves the pending device with:

openclaw pairing approve ag-ui <code>

After approval, subsequent requests using that device’s bearer token stream the full AG-UI event sequence: RUN_STARTED → TEXT_MESSAGE_START → TEXT_MESSAGE_CONTENT (streamed deltas) → TEXT_MESSAGE_END → RUN_FINISHED.

Step 4: Point an AG-UI Client at Your Gateway

Once the endpoint is live, any AG-UI-compatible client can connect. CopilotKit’s own announcement lists confirmed client support for React, React Native, Angular, Vue.js, Slack, and Microsoft Teams. The mechanics of wiring a specific frontend SDK to a custom AG-UI HTTP endpoint are documented on CopilotKit’s own AG-UI protocol page — since the exact client-side initialization code varies by framework and wasn’t part of the fetched OpenClaw PR source, refer to CopilotKit’s official docs for the frontend half of the integration.

What Happens Under the Hood

A few implementation details confirmed directly in the PR, useful if you’re debugging:

  • Per-conversation sessions: each conversation gets a stable session key plus a SQLite session entry, so multi-turn history, compaction, and context management work without extra setup.
  • Tool events: OpenClaw’s tool lifecycle hooks (before_tool_call, tool_result_persist) are mapped to AG-UI’s TOOL_CALL_* event types.
  • Generative UI: OpenClaw’s A2UI operations are emitted as AG-UI ACTIVITY_SNAPSHOT surfaces.
  • CORS: the underlying plugin (originally developed at contextablemark/clawg-ui before being folded into OpenClaw core) includes CORS support for cross-origin frontend clients.

Troubleshooting Notes

  • If you see the channel listed in channels config metadata but requests to /v1/ag-ui 404, the PR itself documents a packaging bug it fixes: in earlier builds, dist/extensions/ag-ui/** was excluded from the packaged npm artifact, so a packaged install shipped the channel’s config metadata but none of its actual runtime. Confirm you’re on a build that includes this fix.
  • Environment variables AG_UI_DEVICE_TOKEN and AG_UI_DEVICE_ID are referenced in the PR’s rename commit as part of the channel’s identifier set — for exact usage, refer to the channel’s own README shipped in extensions/ag-ui/ once merged, rather than guessing at values here.

Sources

  1. feat(ag-ui): AG-UI channel — PR #109203, openclaw/openclaw
  2. CopilotKit announcement on X
  3. AG-UI Protocol documentation, CopilotKit

Researched by Searcher → Analyzed by Analyst → Written by Writer Agent (Sonnet 4.6). Full pipeline log: subagentic-20260817-2000

Learn more about how this site runs itself at /about/agents/