OpenClaw

Set TCC environment variables

Our SDKs default to using the TCC_API_KEY environment variable.

.env

TCC_API_KEY="your-api-key"

Instrument OpenClaw

Plugin install
Manual registration

The fastest way to get started. Install the plugin and configure it in your openclaw.json.

Step 1: Install the plugin

openclaw plugins install @contextcompany/openclaw

Step 2: Configure the plugin

Add the plugin to your openclaw.json:

openclaw.json

{
  "plugins": {
    "allow": ["openclaw"],
    "entries": {
      "openclaw": {
        "enabled": true,
        "hooks": {
          "allowConversationAccess": true
        },
        "config": {
          "apiKey": "${TCC_API_KEY}"
        }
      }
    }
  }
}

allowConversationAccess lets the plugin observe the prompts and responses needed to build complete traces. OpenClaw requires this explicit permission for non-bundled plugins.

Step 3: Restart the gateway

openclaw gateway restart

That’s it! The plugin hooks into the agent runtime and starts sending traces to The Context Company. All LLM calls, tool executions, and agent lifecycle events are automatically captured.

Use manual registration when you need per-run metadata, custom run IDs, or feedback wiring via onRunStart / onRunEnd callbacks.

Step 1: Install the package

npm i @contextcompany/openclaw

Step 2: Register in a custom extension

Create an extension that calls register() with the OpenClaw plugin API:

extensions/tcc-observability/index.ts

import { register } from "@contextcompany/openclaw";

export default async function (api) {
  register(api);
}

You can also pass explicit configuration:

extensions/tcc-observability/index.ts

import { register } from "@contextcompany/openclaw";

export default async function (api) {
  register(api, {
    apiKey: "tcc_...",
    debug: true,
  });
}

Step 3: Restart the gateway

openclaw gateway restart

Adding custom metadata

Custom metadata allows you to add additional properties to your agent runs. This is particularly useful for tying agent runs to your own specific business logic, letting you filter and analyze agent runs by user, organization, feature, or some other dimension.

Plugin config
Manual registration

Set static metadata in your openclaw.json to attach the same metadata to every run:

openclaw.json

{
  "plugins": {
    "entries": {
      "openclaw": {
        "enabled": true,
        "config": {
          "apiKey": "${TCC_API_KEY}",
          "metadata": {
            "environment": "production",
            "service": "support-bot"
          }
        }
      }
    }
  }
}

Derive metadata from the run context by passing a function to the metadata config:

extensions/tcc-observability/index.ts

import { register } from "@contextcompany/openclaw";

export default async function (api) {
  register(api, {
    metadata: (ctx) => ({
      agent: ctx.agentId ?? "unknown",
      trigger: ctx.trigger ?? "user",
      channel: ctx.channelId ?? "none",
    }),
  });
}

For per-run metadata that depends on the prompt or needs to be set imperatively, use the onRunStart callback:

extensions/tcc-observability/index.ts

import { register } from "@contextcompany/openclaw";

export default async function (api) {
  register(api, {
    onRunStart: ({ ctx, prompt, setMetadata }) => {
      setMetadata({
        agent: ctx.agentId ?? "unknown",
        trigger: ctx.trigger ?? "user",
        promptPreview: prompt.slice(0, 120),
      });
    },
  });
}

Agent runs are automatically indexed by your custom metadata fields and can be filtered directly in the dashboard.

The tcc.* namespace is reserved. Only the reserved TCC metadata keys (tcc.runId, tcc.sessionId, tcc.conversational, tcc.agent, tcc.userId, tcc.userName, tcc.orgId, tcc.orgName) are recognized; any other tcc.* keys are ignored. None of them appear in your custom metadata.The plugin auto-mints a per-run tcc.runId and stamps it on every payload. Do not set tcc.runId in metadata. Use the runId config (consumed once) or override per run via the onRunStart callback.

Adding user feedback

User feedback allows you to collect score (thumbs up & thumbs down) and text feedback (up to 2000 characters) from end users on your agent runs. This is useful for tracking user satisfaction, identifying problematic responses, and filtering agent runs in the dashboard to focus on positive or negative feedback.

Step 1: Capture the run ID

The plugin auto-generates a unique run ID (UUID) for every agent turn. Use the onRunEnd callback to capture it:

extensions/tcc-observability/index.ts

import { register, submitFeedback } from "@contextcompany/openclaw";

const runIdByConversation = new Map<string, string>();

export default async function (api) {
  const handle = register(api, {
    onRunEnd: ({ runId, ctx }) => {
      // Stash the run ID by conversation for later feedback
      if (ctx.sessionKey) {
        runIdByConversation.set(ctx.sessionKey, runId);
      }
    },
  });
}

// Export for use in other extensions (e.g. reaction handlers)
export function getRunIdForConversation(sessionKey: string): string | undefined {
  return runIdByConversation.get(sessionKey);
}

You can also retrieve the run ID directly from the handle:

// Get the most recent run ID
const runId = handle.getRunId();

// Get the run ID for a specific session (concurrency-safe)
const runId = handle.getRunIdForSession(sessionKey);

Step 2: Submit feedback

When the user provides feedback, submit it using the submitFeedback function. Both score and text are optional individually, but each request must include at least one of them: score is the thumbs rating. Use only "thumbs_up" or "thumbs_down". text is written feedback from your user, up to 2000 characters.

import { submitFeedback } from "@contextcompany/openclaw";

// Submit score and/or text feedback:
await submitFeedback({
  runId: runId,          // The run ID from your agent execution
  score: "thumbs_up",   // Optional thumbs rating: "thumbs_up" or "thumbs_down"
  text: "Great response!", // Optional written user feedback, up to 2000 characters
});

Agent runs with feedback can be filtered in the dashboard using the feedback filter.

Tracking agent sessions

Agent sessions represent multiple agent runs that are grouped together. The most common use case is tracking entire conversations between a human user and an AI agent in chatbot interfaces. By default, the plugin automatically uses OpenClaw’s ctx.sessionKey as the session ID, which is already scoped per conversation thread. This means sessions are tracked automatically for channel-based setups (e.g. Slack threads). To override this default, use manual registration and derive the session ID from the run context:

extensions/tcc-observability/index.ts

import { register } from "@contextcompany/openclaw";

export default async function (api) {
  register(api, {
    sessionId: (ctx) => ctx.channelId ?? ctx.sessionKey,
  });
}

You can also override the session ID per-run using the onRunStart callback:

extensions/tcc-observability/index.ts

import { register } from "@contextcompany/openclaw";

export default async function (api) {
  register(api, {
    onRunStart: ({ ctx, setSessionId }) => {
      setSessionId(ctx.channelId ?? "default-session");
    },
  });
}

The value of sessionId should be a unique identifier for the agent session. This can be any string, but it’s generally recommended to use a UUID. Agent sessions are automatically indexed and can be filtered directly in the dashboard.

Marking runs as conversational

A conversational run is an agent run that was initiated by a user. Marking a run as conversational tells The Context Company that this run involves direct user interaction. This is important because conversational runs are the only runs monitored for user insights, such as user confusion, frustration, or any other custom insights you want to track. Runs that are not marked as conversational (e.g. background jobs, cron tasks, or internal automations) are excluded from user insight analysis. Mark a run as conversational by setting tcc.conversational to "true" in metadata:

Plugin config
Manual registration

openclaw.json

{
  "plugins": {
    "entries": {
      "openclaw": {
        "enabled": true,
        "config": {
          "apiKey": "${TCC_API_KEY}",
          "metadata": {
            "tcc.conversational": "true"
          }
        }
      }
    }
  }
}

extensions/tcc-observability/index.ts

import { register } from "@contextcompany/openclaw";

export default async function (api) {
  register(api, {
    metadata: {
      "tcc.conversational": "true",
    },
  });
}

Or set it per-run using the onRunStart callback:

extensions/tcc-observability/index.ts

import { register } from "@contextcompany/openclaw";

export default async function (api) {
  register(api, {
    onRunStart: ({ ctx, setMetadata }) => {
      // Only mark user-initiated runs as conversational
      if (ctx.trigger === "user") {
        setMetadata({ "tcc.conversational": "true" });
      }
    },
  });
}

Identifying the agent

If your product ships more than one named agent, set the reserved tcc.agent metadata key to scope the run to a specific agent. The dashboard’s top-level agent selector, per-agent patterns and recaps, and the agent filter on the REST API and MCP tools all read from this key.

Plugin config
Per-run via onRunStart

openclaw.json

{
  "plugins": {
    "entries": {
      "openclaw": {
        "enabled": true,
        "config": {
          "apiKey": "${TCC_API_KEY}",
          "metadata": {
            "tcc.agent": "support-agent"
          }
        }
      }
    }
  }
}

extensions/tcc-observability/index.ts

import { register } from "@contextcompany/openclaw";

export default async function (api) {
  register(api, {
    onRunStart: ({ ctx, setMetadata }) => {
      setMetadata({
        "tcc.agent": ctx.agentName,
      });
    },
  });
}

Agent names that collide with reserved dashboard routes (for example runs, sessions, patterns, recaps, overview, search, failures, feedback, tools, topics, views, settings, mcp-and-api) are dropped.

Identifying users and organizations

Attach the end user and their organization to a run as first-class identity using the reserved tcc.userId, tcc.userName, tcc.orgId, and tcc.orgName metadata keys. This is not the same as adding a userId field to custom metadata — these keys promote user and org identity to dedicated dashboard filters and unlock native user/org search, per-user views, and per-org analytics. See User and organization identity for the full concept. Set these whenever you have a stable identifier for the end user or their organization in your product.

Plugin config
Per-run via onRunStart

openclaw.json

{
  "plugins": {
    "entries": {
      "openclaw": {
        "enabled": true,
        "config": {
          "apiKey": "${TCC_API_KEY}",
          "metadata": {
            "tcc.userId": "user-123",
            "tcc.userName": "Jane Doe",
            "tcc.orgId": "org-456",
            "tcc.orgName": "Acme Inc."
          }
        }
      }
    }
  }
}

extensions/tcc-observability/index.ts

import { register } from "@contextcompany/openclaw";

export default async function (api) {
  register(api, {
    onRunStart: ({ ctx, setMetadata }) => {
      // Look up the user/org for this run from your context
      setMetadata({
        "tcc.userId": ctx.userId,
        "tcc.userName": ctx.userName,
        "tcc.orgId": ctx.orgId,
        "tcc.orgName": ctx.orgName,
      });
    },
  });
}

tcc.userName and tcc.orgName require the corresponding ID (tcc.userId / tcc.orgId) to also be set. Names without IDs are dropped.

Lifecycle callbacks

The onRunStart and onRunEnd callbacks give you fine-grained control over each agent run. These are only available with manual registration.

`onRunStart`

Called at the start of each agent run, before any LLM calls. Use it to set per-run metadata, override the run ID, or customize the session ID.

extensions/tcc-observability/index.ts

import { register } from "@contextcompany/openclaw";

export default async function (api) {
  register(api, {
    onRunStart: ({ runId, ctx, prompt, setRunId, setSessionId, setMetadata }) => {
      // runId: the auto-generated UUID for this run
      // ctx: { agentId, sessionKey, channelId, trigger, ... }
      // prompt: the user's input text

      // Override the run ID if needed
      setRunId("my-custom-uuid");

      // Override the session ID
      setSessionId("my-session-id");

      // Attach per-run metadata
      setMetadata({
        agent: ctx.agentId ?? "unknown",
        trigger: ctx.trigger ?? "user",
      });
    },
  });
}

`onRunEnd`

Called when an agent run completes. Use it to capture the run ID for feedback, log results, or trigger downstream actions.

extensions/tcc-observability/index.ts

import { register } from "@contextcompany/openclaw";

export default async function (api) {
  register(api, {
    onRunEnd: ({ runId, ctx, success, sessionId, metadata }) => {
      // runId: the final run ID
      // ctx: { agentId, sessionKey, channelId, trigger, ... }
      // success: whether the run completed without errors
      // sessionId: the session ID used for this run
      // metadata: the full merged metadata for this run

      console.log(`Run ${runId} completed (success: ${success})`);
    },
  });
}

Configuration

Option	Environment variable	Default	Description
`apiKey`	`TCC_API_KEY`	—	Your Context Company API key
`debug`	`TCC_DEBUG`	`false`	Enable debug logging
`sessionId`	—	`ctx.sessionKey`	Session ID for grouping runs
`metadata`	—	`{}`	Key-value metadata attached to every run
`runId`	—	Auto-generated UUID	Explicit run ID (first run only)
`onRunStart`	—	—	Callback at run start (manual registration only)
`onRunEnd`	—	—	Callback at run end (manual registration only)

Events are batched and sent when the agent run completes. Sessions that never complete are automatically flushed after 30 minutes.

Debug mode

You can enable debug mode to log hook events and transport details to the console.

Plugin config
Manual registration
Environment variable

openclaw.json

{
  "plugins": {
    "entries": {
      "openclaw": {
        "enabled": true,
        "config": {
          "apiKey": "${TCC_API_KEY}",
          "debug": true
        }
      }
    }
  }
}

extensions/tcc-observability/index.ts

import { register } from "@contextcompany/openclaw";

export default async function (api) {
  register(api, {
    debug: true,
  });
}

.env

TCC_DEBUG=true

Examples

See our examples repository for more detailed usage examples.

Getting started

Supported frameworks

Custom Instrumentation

Monitoring

Integrations

Security

Set TCC environment variables

Instrument OpenClaw

Step 1: Install the plugin

Step 2: Configure the plugin

Step 3: Restart the gateway

Step 1: Install the package

Step 2: Register in a custom extension

Step 3: Restart the gateway

Adding custom metadata

Adding user feedback

Step 1: Capture the run ID

Step 2: Submit feedback

Tracking agent sessions

Marking runs as conversational

Identifying the agent

Identifying users and organizations

Lifecycle callbacks

`onRunStart`

`onRunEnd`

Configuration

Debug mode

Examples

​Set TCC environment variables

​Instrument OpenClaw

​Step 1: Install the plugin

​Step 2: Configure the plugin

​Step 3: Restart the gateway

​Step 1: Install the package

​Step 2: Register in a custom extension

​Step 3: Restart the gateway

​Adding custom metadata

​Adding user feedback

​Step 1: Capture the run ID

​Step 2: Submit feedback

​Tracking agent sessions

​Marking runs as conversational

​Identifying the agent

​Identifying users and organizations

​Lifecycle callbacks

​onRunStart

​onRunEnd

​Configuration

​Debug mode

​Examples

Set TCC environment variables

Instrument OpenClaw

Step 1: Install the plugin

Step 2: Configure the plugin

Step 3: Restart the gateway

Step 1: Install the package

Step 2: Register in a custom extension

Step 3: Restart the gateway

Adding custom metadata

Adding user feedback

Step 1: Capture the run ID

Step 2: Submit feedback

Tracking agent sessions

Marking runs as conversational

Identifying the agent

Identifying users and organizations

Lifecycle callbacks

`onRunStart`

`onRunEnd`

Configuration

Debug mode

Examples