OpenClaw agent tracing with Future AGI

About

Use this guide for local CLI agent turns or CLI turns dispatched through a Gateway on macOS. Channel, TUI, Control UI, and cron execution are outside the scope of this guide.

OpenClaw ships an official OpenTelemetry exporter, the diagnostics-otel plugin. It exports OTLP/HTTP traces to any endpoint with any headers, so it can send straight to Future AGI. This page is configuration only: no Future AGI plugin, no collector.

Each agent run becomes one trace. A turn that succeeds on the first model request is one run:

openclaw.harness.run              one agent run: outcome, provider, model, agent
└── openclaw.run                  run lifecycle
    ├── openclaw.context.assembled    prompt and history sizes, token budget (no text)
    ├── openclaw.model.call           one model request: model, tokens, cache tokens, time to first byte
    ├── openclaw.tool.execution       tool name, call id, source, error category
    ├── openclaw.tool.execution
    └── openclaw.model.call

A retried model request can produce more than one trace for a user turn. See Failures and retries.

This recipe uses OpenClaw 2026.10.5, with the plugin at the same version as OpenClaw. See the OpenTelemetry plugin documentation.

1. Install the plugin

Install the plugin at the same version as OpenClaw:

openclaw --version    # for example: OpenClaw 2026.10.5 (1b58cb9)
openclaw plugins install clawhub:@openclaw/diagnostics-otel@2026.10.5

Version rule

OpenClaw publishes diagnostics-otel with each release, under the same version number, and each plugin release needs OpenClaw (its plugin API) at least that version.

• Pin the plugin to the version openclaw --version prints. On a newer OpenClaw, put that version after the @ instead of 2026.10.5.
• Do not install it without a version. That takes ClawHub’s latest release, which fails on an older OpenClaw with requires plugin API >=<plugin version>, but this OpenClaw runtime exposes <your version>.
• After you upgrade OpenClaw, run openclaw plugins update diagnostics-otel and restart the Gateway. openclaw plugins inspect diagnostics-otel shows the installed version.

openclaw plugins install enables the plugin. If you use a plugins.allow list, it adds diagnostics-otel to it. Do not create an allow list just for this: it disables every other plugin.

2. Point it at Future AGI

Download the example patch and apply it. It sets the diagnostics.otel block and one environment variable:

curl -fsSLO https://raw.githubusercontent.com/future-agi/docs/main/examples/coding-agents/openclaw/futureagi.patch.json5
openclaw config patch --file futureagi.patch.json5

{
  env: {
    vars: {
      OTEL_NODE_RESOURCE_DETECTORS: "env",
    },
  },
  diagnostics: {
    enabled: true,
    otel: {
      enabled: true,
      tracesEndpoint: "https://api.futureagi.com/tracer/v1/traces",
      protocol: "http/protobuf",
      headers: {
        "X-Api-Key": "${FI_API_KEY}",
        "X-Secret-Key": "${FI_SECRET_KEY}",
      },
      serviceName: "openclaw",
      traces: true,
      metrics: false,
      logs: false,
      captureContent: false,
    },
  },
}

• tracesEndpoint is an exact URL: OpenClaw does not append a path to it. For a self-hosted Future AGI, replace the host and keep /tracer/v1/traces.
• metrics and logs are off because Future AGI ingests traces only.
• OTEL_NODE_RESOURCE_DETECTORS=env is required for the privacy default. Without it, OpenClaw’s OpenTelemetry SDK also exports the host name, host id, OS user name, the executable and script paths, and the full command line, which for openclaw agent --local -m "..." contains the prompt. The patch sets it in OpenClaw’s config env block, which reaches the Gateway and the CLI. That block does not override: if the variable is already set in the process environment or a .env file, that value wins, so keep it env there too.
• Side effect: the env block sets the variable in OpenClaw’s own process environment, so the commands the agent runs with the exec tool inherit it. In OpenClaw 2026.10.3 and 2026.10.5, no setting applies it to the exporter alone. A Node program the agent starts that takes its OpenTelemetry resource detectors from the environment (the default for @opentelemetry/sdk-node) then runs only the env detector and exports no host or process attributes. To give such a program its detectors back, set OTEL_NODE_RESOURCE_DETECTORS=all (or the list it needs) where that program is launched. To remove the side effect instead, run openclaw config unset env.vars.OTEL_NODE_RESOURCE_DETECTORS; OpenClaw’s own spans then carry the host name, user name and command line again.

Commands run by the agent’s exec tool can inherit the Future AGI keys from OpenClaw’s environment. Use this setup only when those commands and their environment are trusted. Then put the keys and the project name in ~/.openclaw/.env (OpenClaw’s global env file, read by the Gateway and the CLI):

FI_API_KEY=your-futureagi-api-key
FI_SECRET_KEY=your-futureagi-secret-key
OTEL_RESOURCE_ATTRIBUTES=project_name=openclaw

OTEL_RESOURCE_ATTRIBUTES sets the Future AGI project.

Check the config and restart the Gateway:

openclaw config validate
openclaw gateway restart

3. Run a turn

Send one message that uses a tool:

openclaw agent -m "List the files in this folder and read README.md"

Open Observe in Future AGI and select the project (openclaw above). The run appears as a trace named openclaw.harness.run; open it for the model calls and tool executions. The Gateway batches spans, so allow a few seconds.

What is captured

OpenClaw span	Future AGI span kind	Fields
openclaw.harness.run		Trace root. openclaw.outcome, provider, model, agent, items started/completed; openclaw.error on failure
openclaw.run		outcome, provider, model, trigger; openclaw.errorCategory and openclaw.error on failure
openclaw.context.assembled		message count, history and prompt sizes in characters, system prompt size, token budget
openclaw.model.call	LLM	gen_ai.request.model, gen_ai.system (the provider id), gen_ai.usage.input_tokens / output_tokens, cache read and write tokens, reasoning tokens, request and response bytes, time to first byte, prompt component sizes (no text); status ERROR with the error category when the request fails
openclaw.tool.execution	TOOL	gen_ai.tool.name, gen_ai.tool.call.id, tool source and owner, status ERROR with openclaw.errorCategory when the tool fails (including a tool that returns an error, such as a missing file), openclaw.outcome=blocked when policy denies it
openclaw.exec		One per command the agent runs with the exec tool, under openclaw.harness.run: exec target, mode, outcome, exit code, command length (no command text).

OpenClaw also exports, as separate traces:

• openclaw.model.usage: run-level accounting for a Gateway run (total tokens, provider, model, channel). Its token counts repeat the openclaw.model.call spans. Future AGI stores it as an LLM span too, so project-level token and LLM-call totals count each Gateway run twice. For per-call numbers, filter by span name openclaw.model.call.
• openclaw.gateway.rpc.*: Gateway request handling phases.
• openclaw.message.processed and openclaw.message.delivery for channel messages, openclaw.webhook.* for webhooks.
• openclaw.diagnostic.phase: timings of OpenClaw’s internal startup phases, one short trace each.

The full span catalog is in OpenClaw’s spans and events page.

Failures and retries

• A failed model request is marked ERROR on its openclaw.model.call span. The run’s openclaw.harness.run and openclaw.run can still say openclaw.outcome=completed with no error status.
• A retried turn can appear as several traces. Do not infer success from a root span alone; inspect its model-call and tool spans.
• To find failed turns, filter for openclaw.model.call or openclaw.tool.execution spans with status ERROR, not by the status of the root.

What is not available

• Session grouping. OpenClaw never exports session ids or session keys, so runs are not grouped into Future AGI sessions.
• One trace per user turn when a model request is retried. Each attempt is a separate trace (see above).
• openclaw agent exec runs. They run embedded in the CLI and do not start the exporter. Gateway runs and openclaw agent --local do export.
• Cost. openclaw.model.call carries tokens, not cost; OpenClaw’s cost estimate is exported as a metric, which Future AGI does not ingest.
• The system prompt, even with content capture on.
• Tool calls of external harnesses (Codex, Claude CLI) carry no content, even with content capture on.

Privacy

With captureContent: false (the default), spans carry identifiers, model and provider names, token counts, sizes, durations and outcomes. OpenClaw states they never include prompt text, response text, tool inputs, tool outputs, skill file paths or session keys. With OTEL_NODE_RESOURCE_DETECTORS=env (set by the patch), the host name, host id, OS user name, executable paths and command line are not exported either.

One exception: when a run fails, openclaw.run and openclaw.harness.run carry OpenClaw’s error message (openclaw.error and the span status message, up to 4 KB, with secrets redacted) even with content capture off. It can contain file paths, URLs or provider error text. openclaw.webhook.error spans also carry error text in openclaw.error and the status message, and failed channel openclaw.message.processed spans carry it in the status message; both are redacted but have no 4 KB cap. OpenClaw has no setting to turn this off.

Commands the agent runs with the exec tool inherit OpenClaw’s environment, including FI_API_KEY, FI_SECRET_KEY and OTEL_RESOURCE_ATTRIBUTES from ~/.openclaw/.env. OpenClaw removes only a fixed list of variables such as NODE_OPTIONS, and treats provider API keys in that file the same way.

To include content, set captureContent: true in diagnostics.otel. Model spans then carry bounded, redacted input and output messages (shown as the span’s input and output in Future AGI) and tool spans carry gen_ai.tool.call.arguments and gen_ai.tool.call.result (also as openclaw.content.tool_input / tool_output), which include file paths, command text and file contents. Tool definitions are included; the system prompt stays excluded.

Troubleshooting

No traces appear.

1. openclaw status --all or openclaw doctor shows the exporter’s state per signal, including export failures (without endpoints or headers).
2. diagnostics.otel.protocol must be http/protobuf; OpenClaw retired grpc.
3. ${FI_API_KEY} must resolve: OpenClaw warns about unresolved variables at start. Put the keys in ~/.openclaw/.env or the Gateway’s process environment; a .env in the working directory is a lower-trust source.
4. The Gateway exports from its own process: restart it after changing the config or .env.

plugins install fails with requires plugin API >=…, but this OpenClaw runtime exposes …. The plugin release is newer than your OpenClaw. Install the plugin at your OpenClaw version (see Version rule) or upgrade OpenClaw.

plugins install fails with Version not found on ClawHub. ClawHub has no diagnostics-otel release with exactly your OpenClaw version, for example on a source build. Install the newest plugin release that is not newer than your OpenClaw; ClawHub lists them.

Traces do not show up in the expected project. Future AGI files traces under the project_name resource attribute. Check that OTEL_RESOURCE_ATTRIBUTES=project_name=... reaches the exporting process: set it in ~/.openclaw/.env or the Gateway’s service environment, then restart the Gateway.

Traces show your host name, user name or command line. OTEL_NODE_RESOURCE_DETECTORS is set to something other than env in the exporting process’s environment or a .env file, which wins over the patch. Set it to env there and restart the Gateway.

A Node program the agent runs exports no host or process attributes. It inherited OTEL_NODE_RESOURCE_DETECTORS=env from OpenClaw’s config env block. See the side-effect note in step 2.

A failed turn shows as several successful traces. Each model retry is its own trace and the roots can say completed. Look for openclaw.model.call spans with status ERROR (see Failures and retries).

Many short openclaw.diagnostic.phase traces. These are startup phases; filter the trace list by name openclaw.harness.run to see agent runs only. Cron turns are rooted at openclaw.message.processed instead.

The run’s root spans are missing. openclaw.harness.run and openclaw.run end after the reply is delivered. If a Gateway or CLI process is killed right after a turn, they may not be flushed.