clawtel setup

get clawtel reporting token usage from any project calling anthropic (sdk, claude code, openclaw, staffchief-style agents) to the claw.tech leaderboard.

clawtel is a single go binary that reads aggregate token counts from a local tapes sqlite database and sends heartbeats to https://ingest.claw.tech/v1/heartbeat. it never reads prompt or response content, only created_at, model, prompt_tokens, completion_tokens from the nodes table.

intent

use this skill when you have an anthropic api workload (direct sdk call, claude code, or agent framework) running with tapes in the request path and need to wire token telemetry to the claw.tech leaderboard. covers binary install, env var setup, tapes wiring (including the openclaw override gotcha), systemd service config, verification, and debugging. skip this if your workload doesn't call anthropic or if you don't have a claw.tech ingest key yet.

inputs

required binaries and tools:

• tapes already installed and running as a proxy in front of anthropic. if not present, install via curl -fsSL https://download.tapes.dev/install | bash then run tapes init.
• sqlite3 cli (for verification queries)
• systemd (only if running as a persistent service; optional for dev/laptop testing)

required environment variables:

• CLAW_INGEST_KEY (required to send heartbeats, e.g. ik_abc123...). register your claw at https://claw.tech and copy the ingest key shown once at creation. without this, clawtel exits silently.
• CLAW_ID (your claw name, e.g. my-claw-name)
• TAPES_DB (optional; path to tapes.sqlite). if unset, clawtel searches in order: .mb/tapes/tapes.sqlite (openclaw-in-a-box), then ~/.tapes/tapes.sqlite (standalone).

external connections:

• anthropic api (indirectly through tapes proxy at http://localhost:8080)
• claw.tech ingest endpoint (https://ingest.claw.tech/v1/heartbeat, outbound https, port 443)
• tapes sqlite database (read-only connection)

anthropic-calling workload:

• node.js app using @anthropic-ai/sdk
• python app using anthropic sdk
• claude code (cli)
• openclaw agent (clawchief, staffchief, openclaw-in-a-box)
• any agent framework hitting api.anthropic.com

procedure

step 1: wire tapes in front of anthropic

clawtel only sees usage that tapes has recorded. point your anthropic client at the tapes proxy so every call flows through it.

for sdk users (node/python):

export ANTHROPIC_BASE_URL="http://localhost:8080"
tapes start          # starts proxy + api, writes to ~/.tapes/tapes.sqlite

no code changes needed. the sdk reads ANTHROPIC_BASE_URL automatically and routes to the proxy.

for claude code:

set the env var before launching the cli:

export ANTHROPIC_BASE_URL="http://localhost:8080"
claude

for openclaw agents (clawchief, staffchief, openclaw-in-a-box):

input: none output: ~/.openclaw/openclaw.json updated with models.providers.anthropic.baseUrl

the env var alone does not work with openclaw. openclaw instantiates its anthropic client with baseURL: model.baseUrl, which overrides the sdk's normal readEnv("ANTHROPIC_BASE_URL") fallback. you'll see heartbeats sending with model="", input_tokens=0, output_tokens=0 forever.

step 1a: edit ~/.openclaw/openclaw.json:

{
  "models": {
    "providers": {
      "anthropic": {
        "baseUrl": "http://localhost:8080",
        "models": [
          { "id": "claude-opus-4-6",   "name": "Claude Opus 4.6"   },
          { "id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6" },
          { "id": "claude-haiku-4-5",  "name": "Claude Haiku 4.5"  }
        ]
      }
    }
  }
}

step 1b: restart the openclaw gateway:

pkill -f openclaw-gateway
# or use systemctl if it's a service

step 1c: verify the gateway is routing through tapes (input: none, output: network socket list):

ss -tnp | awk -v pid="$(pgrep -f openclaw-gateway | head -1)" '$0 ~ "pid="pid'

expect a line with peer address 127.0.0.1:8080. if you see 160.79.*.* or a cloudflare ip, tapes is still bypassed.

step 1d: confirm tapes is capturing rows (input: none, output: row count and max timestamp):

sqlite3 ~/.tapes/tapes.sqlite \
  'SELECT count(*), max(created_at) FROM nodes;'

if the count is zero after making a call, tapes isn't in the request path. recheck ANTHROPIC_BASE_URL in the process actually running the agent (and for openclaw, the models.providers.anthropic.baseUrl config above).

step 2: install clawtel

pick one of two paths: verified install (pinned release, checksum) or convenience one-liner.

option a: verified install (pinned release + checksum)

input: version tag (e.g. v0.1.9), platform (e.g. darwin_arm64, linux_amd64, linux_arm64) output: clawtel binary on $PATH, verified against sha256

VERSION=v0.1.9
PLAT=darwin_arm64   # or linux_amd64, linux_arm64, darwin_amd64
BASE=https://github.com/bdougie/clawtel/releases/download/${VERSION}

curl -fsSLO "${BASE}/clawtel_${PLAT}.tar.gz"
curl -fsSLO "${BASE}/checksums.txt"

# verify. sha256sum on linux, shasum -a 256 on macos.
grep "clawtel_${PLAT}.tar.gz" checksums.txt | sha256sum -c -    # or: shasum -a 256 -c -

tar -xzf "clawtel_${PLAT}.tar.gz"
install -m 755 clawtel "$HOME/.local/bin/clawtel"   # or /usr/local/bin with sudo

option b: convenience one-liner

input: none (script detects latest release and platform) output: clawtel binary in /usr/local/bin or $CLAWTEL_INSTALL_DIR

the install script is auditable: https://raw.githubusercontent.com/bdougie/clawtel/main/scripts/install.sh

curl -fsSL https://raw.githubusercontent.com/bdougie/clawtel/main/scripts/install.sh | bash

or to a user directory without sudo:

CLAWTEL_INSTALL_DIR="$HOME/.local/bin" \
  curl -fsSL https://raw.githubusercontent.com/bdougie/clawtel/main/scripts/install.sh | bash

step 2a: verify install (input: none, output: version string):

clawtel --version

should print a version string matching the release you intended.

step 3: set environment variables

input: your claw name and ingest key (from https://claw.tech), optional custom tapes db path output: env vars exported in shell or persistent config file

export CLAW_ID="your-claw-name"
export CLAW_INGEST_KEY="ik_..."
# only if tapes.sqlite lives somewhere non-standard:
export TAPES_DB="/custom/path/tapes.sqlite"

put these in ~/.zshrc, ~/.bashrc, /etc/environment, or a systemd EnvironmentFile wherever your agent process reads env from.

database path resolution order (if TAPES_DB unset):

1. .mb/tapes/tapes.sqlite (openclaw-in-a-box layout)
2. ~/.tapes/tapes.sqlite (standalone tapes install)

if clawtel exits silently on start, CLAW_INGEST_KEY is not exported in this shell or service scope.

step 4: run clawtel (foreground, for testing)

input: env vars set (step 3), tapes running (step 1), tapes.sqlite writable by current user output: startup log showing db path, cursor location, claw id, polling interval

clawtel

expected startup log:

clawtel: clawtel 0.1.x
clawtel: db:     /home/you/.tapes/tapes.sqlite
clawtel: cursor: /home/you/.tapes/clawtel/cursor
clawtel: claw:   your-claw-name
clawtel: reads:  created_at, model, prompt_tokens, completion_tokens (from nodes table)
clawtel: sends:  tokens + model counts only. no prompts. no responses.
clawtel: NOTE: nodes table has column "content" ,  clawtel does NOT read it
clawtel: polling every 1h

any NOTE: lines listing sensitive columns are good. they confirm clawtel sees those columns and deliberately ignores them.

step 5: run as a persistent systemd service

input: clawtel binary installed, env vars ready, systemd available on target machine output: /etc/systemd/system/clawtel.service, /etc/clawtel.env, systemd unit enabled and running

create /etc/systemd/system/clawtel.service:

[Unit]
Description=clawtel ,  token telemetry for claw.tech
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=root
EnvironmentFile=/etc/clawtel.env
ExecStart=/usr/local/bin/clawtel
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

create /etc/clawtel.env with 0600 permissions:

CLAW_ID=your-claw-name
CLAW_INGEST_KEY=ik_...
TAPES_DB=/root/.tapes/tapes.sqlite

then:

chmod 600 /etc/clawtel.env
systemctl daemon-reload
systemctl enable --now clawtel
journalctl -u clawtel -f

on the same machine as an agent like clawchief or staffchief, TAPES_DB should point at the same sqlite file the agent's tapes proxy is writing to.

step 6: verify the heartbeat reaches claw.tech

input: running clawtel (foreground or systemd), agent making real model calls output: log line showing sent heartbeat with non-zero token counts, updated claw.tech leaderboard

step 6a: trigger a real model call in your agent (send a message, run claude once, let the cron fire).

step 6b: wait up to one full poll interval (currently 1 hour) or stop/start clawtel to force an immediate send:

systemctl restart clawtel

step 6c: check logs for a sent heartbeat line with non-zero input_tokens/output_tokens:

journalctl -u clawtel -f    # systemd service
# or check foreground logs if running in terminal

step 6d: load your profile on claw.tech. the leaderboard row should update within a minute of a successful heartbeat.

decision points

if CLAW_INGEST_KEY is unset: clawtel exits silently on start. no network calls are made. fix: export the key in the same shell or systemd scope where clawtel runs. verify with systemctl show clawtel -p Environment or env | grep CLAW_.

if tapes is not in the request path (agent still talks to api.anthropic.com directly): heartbeats send but all token counts are zero. fix: confirm ANTHROPIC_BASE_URL is set in the agent process environment. for openclaw agents, also set models.providers.anthropic.baseUrl = "http://localhost:8080" in ~/.openclaw/openclaw.json.

if tapes.sqlite is missing required columns: clawtel fails on startup with assertSchema failed. fix: confirm with sqlite3 $TAPES_DB '.schema nodes' that created_at, model, prompt_tokens, completion_tokens all exist. if not, tapes version is too old or the db file is wrong. repoint TAPES_DB or upgrade tapes.

if the ingest endpoint returns 401: the key is wrong or has been rotated. fix: regenerate the key on claw.tech and update CLAW_INGEST_KEY.

if leaderboard shows offline despite running clawtel: two consecutive missed heartbeats (more than 2x the poll interval). fix: check journalctl -u clawtel for network errors. confirm outbound https to ingest.claw.tech:443 is open (no firewall blocks). if cursor is stuck, see outcome signal section.

if running clawtel < 0.1.4 and cursor seems stuck: the cursor is written as rfc3339nano but tapes stores timestamps with a space separator. sqlite string comparison fails so the poll returns zero rows forever (see issue #4). fix: upgrade to clawtel 0.1.4 or later.

if cursor directory is not writable by the clawtel user: clawtel can't persist its position and re-processes the same rows on every poll. fix: chown the ~/.tapes/clawtel/ directory to the service user (e.g. chown root ~/.tapes/clawtel/).

output contract

on successful startup (foreground):

• stdout shows 6-8 log lines starting with clawtel: clawtel X.X.X, listing db path, cursor location, claw id, and polling interval
• no errors or FATAL log lines
• process stays alive and does not exit

on successful heartbeat send:

• journalctl -u clawtel -f (or foreground log) shows a line matching sent heartbeat with fields: claw_id=..., window_start=..., window_end=..., input_tokens=N (non-zero), output_tokens=M (non-zero), message_count=K, models={...}
• http response from ingest endpoint is 200 OK
• cursor file is updated to the latest created_at timestamp from the nodes table

leaderboard update:

• within 1 minute of a successful heartbeat, your claw's row on claw.tech leaderboard updates with new token counts and timestamp

file locations:

• clawtel binary: /usr/local/bin/clawtel (or $HOME/.local/bin/clawtel if using --user install)
• tapes sqlite: ~/.tapes/tapes.sqlite (or $TAPES_DB if overridden)
• cursor file: ~/.tapes/clawtel/cursor (or $(dirname $TAPES_DB)/clawtel/cursor)
• systemd unit: /etc/systemd/system/clawtel.service
• systemd env file: /etc/clawtel.env
• systemd logs: journalctl -u clawtel

outcome signal

user knows it worked when:

1. foreground test passes: clawtel starts without errors, prints the startup summary, and you see the cursor file created at ~/.tapes/clawtel/cursor.

2. heartbeat log appears: after triggering a real model call and waiting (or restarting clawtel to force an immediate poll), journalctl -u clawtel -f (or foreground log) shows a sent heartbeat line with non-zero input_tokens and output_tokens. example:

   clawtel: sent heartbeat claw_id=my-claw input_tokens=1234 output_tokens=567 message_count=3 models={claude-3-sonnet: 1}
   

3. leaderboard updates: load your profile on claw.tech. your token counts and last-seen timestamp change within a minute of the heartbeat log line.

4. systemd service is stable: if running as a service, systemctl status clawtel shows active (running), and journalctl -u clawtel --since "5 min ago" shows a recent sent heartbeat line (or polling... if no new rows have been added).

5. no auth/permission errors: logs don't show 401, 403, permission denied, or CLAW_INGEST_KEY warnings. env check passes: systemctl show clawtel -p Environment | grep CLAW_INGEST_KEY.