Skip to content

configuration.md

Latest commit

 

History

History
276 lines (219 loc) · 4.96 KB

configuration.md

File metadata and controls

276 lines (219 loc) · 4.96 KB

Configuration

Configure OpenClaw's built-in OpenTelemetry diagnostics via ~/.openclaw/openclaw.json.

Full Configuration Example

{
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "http://localhost:4318",
      "protocol": "http/protobuf",
      "headers": {
        "Authorization": "Api-Token dt0c01.xxx"
      },
      "serviceName": "openclaw-gateway",
      "traces": true,
      "metrics": true,
      "logs": true,
      "sampleRate": 1.0,
      "flushIntervalMs": 5000
    }
  }
}

Configuration Reference

diagnostics

Top-level diagnostics configuration.

Option Type Default Description
enabled boolean false Enable the diagnostics system

diagnostics.otel

OpenTelemetry export configuration.

Option Type Default Description
enabled boolean false Enable OTel export
endpoint string — OTLP endpoint URL (required)
protocol string "http/protobuf" Protocol: "http/protobuf" or "grpc"
headers object {} Custom HTTP headers (e.g., auth tokens)
serviceName string "openclaw" OTel service name attribute
traces boolean true Enable trace export
metrics boolean true Enable metrics export
logs boolean false Enable log forwarding
sampleRate number 1.0 Trace sampling rate (0.0–1.0)
flushIntervalMs number — Export flush interval in milliseconds

Endpoint Configuration

HTTP Protocol (Default)

For OTLP/HTTP endpoints (port 4318):

{
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "http://localhost:4318",
      "protocol": "http/protobuf"
    }
  }
}

The endpoint auto-appends /v1/traces, /v1/metrics, /v1/logs as needed.

gRPC Protocol

For OTLP/gRPC endpoints (port 4317):

{
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "http://localhost:4317",
      "protocol": "grpc"
    }
  }
}

Note: gRPC support is experimental.

Authentication

Bearer Token

{
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "https://api.example.com/otlp",
      "headers": {
        "Authorization": "Bearer your-token-here"
      }
    }
  }
}

Dynatrace API Token

{
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "https://{env-id}.live.dynatrace.com/api/v2/otlp",
      "headers": {
        "Authorization": "Api-Token dt0c01.xxx..."
      }
    }
  }
}

Basic Auth (Grafana Cloud)

{
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "https://otlp-gateway-prod-us-central-0.grafana.net/otlp",
      "headers": {
        "Authorization": "Basic base64(instanceId:apiKey)"
      }
    }
  }
}

Sampling

Control trace sampling rate to reduce volume:

{
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "http://localhost:4318",
      "sampleRate": 0.1
    }
  }
}
  • 1.0 — Sample all traces (default)
  • 0.5 — Sample 50% of traces
  • 0.1 — Sample 10% of traces
  • 0.0 — Disable trace sampling

Selective Export

Enable only specific signals:

Traces Only

{
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "http://localhost:4318",
      "traces": true,
      "metrics": false,
      "logs": false
    }
  }
}

Metrics Only

{
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "http://localhost:4318",
      "traces": false,
      "metrics": true,
      "logs": false
    }
  }
}

Logs Only

{
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "http://localhost:4318",
      "traces": false,
      "metrics": false,
      "logs": true
    }
  }
}

Environment Variables

OpenClaw also respects standard OTel environment variables as fallbacks:

Variable Description
OTEL_EXPORTER_OTLP_ENDPOINT Default OTLP endpoint
OTEL_EXPORTER_OTLP_PROTOCOL Default protocol
OTEL_SERVICE_NAME Default service name

Config file values take precedence over environment variables.

Applying Changes

After modifying configuration:

openclaw gateway restart

Or trigger a hot reload (if supported):

kill -SIGUSR1 $(pgrep -f openclaw-gateway)

Troubleshooting

Configuration Not Applied?

Check the current config:

cat ~/.openclaw/openclaw.json | jq '.diagnostics'

Invalid Config Errors?

Validate JSON syntax:

cat ~/.openclaw/openclaw.json | jq .

Endpoint Unreachable?

Test connectivity:

curl -v http://localhost:4318/v1/traces