openclaw-dynamo-provider

An OpenClaw plugin that registers a dynamo provider backed by Dynamo's OpenAI-compatible endpoint, so OpenClaw can use Dynamo as a normal model:

openclaw --model dynamo/<model-id>

With one switch (DYN_AGENT_TRACE=1) it also tags every request for Dynamo's agent trace, gives each subagent its own isolated KV session, and relays tool events into the trace — all without patching OpenClaw core.

What it does

Model provider — registers dynamo, discovers models from /v1/models, and streams via OpenClaw's OpenAI-compatible path.
Agent context — injects nvext.agent_context (session/trajectory identity) so Dynamo can attribute each LLM request in its trace.
Subagent KV isolation — gives each OpenClaw subagent child its own Dynamo streaming session: opened on its first turn, pinned across turns, and freed deterministically when the agent ends.
Tool-event relay — pushes tool start/end events to Dynamo over ZMQ so one trace shows LLM spans and tool spans together.

Everything but the bare model provider is gated by the DYN_AGENT_TRACE master switch and is off by default.

Install

# From npm (when published)
# Add to openclaw config: "plugin": ["@nvidia/openclaw-dynamo-provider"]

# From a local checkout
cd openclaw-dynamo-provider && npm install && npm run build
# Then add to your openclaw.json:
# "plugin": ["./path/to/openclaw-dynamo-provider"]

Quick start

export DYNAMO_BASE_URL=http://127.0.0.1:8000/v1
export DYNAMO_API_KEY=dummy
export DYN_AGENT_TRACE=1

openclaw --model dynamo/<model-id> -p "Reply exactly ok."

Configuration

| Variable | Default | Purpose | | --- | --- | --- | | DYNAMO_BASE_URL | http://127.0.0.1:8000/v1 | Dynamo endpoint root (falls back to OPENAI_BASE_URL). | | DYNAMO_API_KEY | dynamo-local | Bearer token. | | DYN_AGENT_TRACE | off | Master switch for agent_context, session_control, and tool relay. | | DYN_AGENT_SESSION_TYPE_ID | openclaw_coding_agent | Session class in the trace. | | DYN_AGENT_SESSION_ID | OpenClaw session id | Top-level run id. | | DYN_AGENT_TRAJECTORY_ID | OpenClaw session id | Trajectory id. | | DYN_AGENT_PARENT_TRAJECTORY_ID | unset | Parent trajectory for linking. | | DYN_AGENT_SESSION_TIMEOUT | Dynamo default (300s) | Idle timeout for subagent sessions. | | DYN_AGENT_TOOL_EVENTS_ZMQ_ENDPOINT | unset | ZMQ PULL endpoint for tool relay. |

Subagent KV isolation

When DYN_AGENT_TRACE=1 and this process is a subagent child (detected via OPENCLAW_AGENT_ or PI_SUBAGENT_ env vars), the provider drives session lifecycle:

1. First turn — session_control: {action: "open"} — worker holds KV in a dedicated slot 2. Later turns — bare session_id — sticky routing, O(1) KV restore 3. agent_end — close request frees the KV deterministically

The lead agent is never pinned — only subagents get a session.

Requires Dynamo frontend in --router-mode kv and an SGLang worker with --enable-streaming-session.

Architecture: zero code invasiveness

This plugin uses OpenClaw's standard plugin SDK:

| Feature | OpenClaw API used | | --- | --- | | Model provider | api.registerProvider() | | Request body injection | wrapStreamFn hook | | Request headers | resolveTransportTurnState hook | | Session close on agent end | api.on("agent_end") | | Session close on shutdown | api.on("session_end") | | Tool event relay | api.on("tool_execution_start/end") |

No OpenClaw core changes required.

Development

npm install
npm run check   # tsc --noEmit
npm run test    # vitest
npm run build   # -> dist/

Scope

No OpenClaw core changes, no native Rust ABI. The nvext and agent_trace.v1 schemas are owned upstream by Dynamo.

dynamo

Summary

Install to Claude Code