Skip to content

OpenClaw Integration

If your application relies on OpenClaw (>=2026.3.2) to orchestrate agents, you can bypass manual SDK instrumentation entirely.

The @atheon-inc/openclaw-plugin runs inside your OpenClaw Gateway process and automatically captures your entire execution trace, including:

  • LLM request and response traces with token usage.
  • Sub-agent lifecycles seamlessly nested under their parent trace.
  • Tool call traces with latency, inputs, and errors.

All internal OpenClaw metadata is sanitized and stripped before leaving your gateway, ensuring absolute data privacy.

1. Install the Plugin

Install the plugin directly into your OpenClaw Gateway. If your gateway is running on a remote host, execute this on that machine.

openclaw plugins install @atheon-inc/openclaw-plugin

If the gateway is already running, you must restart it after installation.

2. Configuration

You must provide your Atheon project API key for the plugin to start. You can do this via an environment variable or directly in your OpenClaw configuration file.

Option A: Environment Variable 

export ATHEON_API_KEY=arc_...

Option B: OpenClaw Config (Recommended) Define the plugin configuration in your gateway's JSON config:

{
  "plugins": {
    "entries": {
      "atheon-openclaw": {
        "enabled": true,
        "config": {
          "apiKey": "arc_..."
        }
      }
    },
    "allow": ["atheon-openclaw"]
  }
}

Note: Adding "atheon-openclaw" to the plugins.allow list prevents OpenClaw from throwing warnings about untrusted community plugins.

3. Verify the Integration

Check that the gateway has recognized your effective settings:

openclaw plugins status atheon-openclaw

Run a test message through your gateway:

openclaw gateway run
openclaw message send "hello from openclaw"

Check your Atheon Gateway Dashboard — you will see the interaction populated automatically.

How It Works

The plugin hooks into the native OpenClaw Plugin SDK lifecycle events and maps them directly to Atheon Codex entities.

Trace Structure

Each session produces one root interaction. Sub-agents produce child interactions nested underneath it. Tool calls are recorded as spans on whichever interaction made the call.

Session
└── Root interaction  (llm_input → llm_output)
    ├── Tool span     (before_tool_call → after_tool_call)
    ├── Tool span
    └── Child interaction  (subagent_spawning → subagent_ended)
        ├── Tool span
        └── Tool span

Abandoned Interactions

If a session ends while tool calls or sub-agents are still in flight, the plugin records them as abandoned with an error message and closes the tree cleanly. A background reaper runs every 5 minutes to force-close any interactions that have been idle for more than 1 hour, preventing memory leaks from disconnected clients.