coze_lab

Configure local AI agents (Claude Code, Codex, OpenClaw) to report traces to CozeLoop.

Usage

# First-time setup — triggers browser OAuth authorization
npx coze_lab --agent=<type>

# Per-agent setup. Cloud/local is inferred from coze-bridge config or CLOUD_ENV=1.
npx coze_lab --agent-id=<agentId>

# Auth-only commands (no agent configuration)
npx coze_lab --login      # Device Code login only
npx coze_lab --status     # Show current authorization status
npx coze_lab --refresh    # Force-refresh the access token
npx coze_lab --logout     # Clear cached credentials

Parameters

| Parameter | Required | Values / Effect | |-----------|----------|-----------------| | --agent | ✓ (for setup) | claude-code, codex, openclaw | | --agent-id | — | Resolve ~/.coze/agents/<agentId>/config.json and write per-agent config. Cloud mode is inferred from deployType=cloud, CLOUD_ENV=1, or bridge cloud-only fields | | --cloud | — | Backward-compatible override for old manual callers. New callers should rely on --agent-id auto-detection | | --codex-home | — | Override Codex config home for non-cloud/custom runs | | --login | — | Run the Device Code login flow only | | --status | — | Print local token status (valid / expiring / expired) | | --refresh | — | Force-refresh the access token via refresh_token | | --logout | — | Clears cached credentials |

Note — traces are collected into a shared CozeLoop workspace. All traces from this tool are uploaded to a single fixed workspace (COZELOOP_WORKSPACE_ID) maintained by the CozeLoop team — they are not sent to each user's personal workspace. The OAuth authorization only proves your identity for trace ingestion; it does not select a workspace.

What it does

1. Authorization — Checks ~/.cozeloop/credentials.json for a cached OAuth token.
   • Token valid → skip authorization, proceed.
   • Token expiring (< 10 min) → silently refresh via refresh_token.
   • No token / refresh failed → launches Device Code OAuth flow: opens browser, displays verification URL, polls until user approves.
2. Agent detection — Verifies the specified agent binary is installed locally.
3. Environment checks — Python ≥ 3.8 + cozeloop SDK (Claude Code & Codex only; SDK auto-installed via pip if missing), agent version whitelist check.
4. Hook configuration — Writes hook scripts and config files for the selected agent.

Per-agent hook files

| Agent | Hook script | Config file | Credentials | |-------|------------|-------------|-------------| | claude-code | ~/.claude/hooks/cozeloop_hook.py | ~/.claude/settings.json | .claude/settings.local.json (project-scoped) | | codex | ~/.codex/hooks/cozeloop_hook.py | ~/.codex/hooks.json | ~/.codex/hooks/cozeloop.env | | openclaw | — (Node.js plugin) | ~/.openclaw/openclaw.json | inline in config |

For cloud Codex with --agent-id=<agentId>, Codex hooks are written to ~/.coze/agents/<agentId>/codex-home by default. The directory is created if it does not already exist, so callers do not need to pass --codex-home for the standard coze-bridge layout.

Codex hook diagnostics are appended to hooks/cozeloop.log under the same Codex home. For cloud Codex, check ~/.coze/agents/<agentId>/codex-home/hooks/cozeloop.log. If that file is not created after a new Codex turn, Codex did not load or execute the hook.

Token lifecycle

OAuth tokens are stored in ~/.cozeloop/credentials.json (mode 600).

In cloud mode, trace verification and hook uploads prefer COZELOOP_API_TOKEN and fall back to COZE_API_TOKEN. The selfcheck result is authoritative: if the token does not have trace ingest permission, onboard still writes the hook configuration but reports verify=fail with token_source. For Python SDK uploads, OTEL_ENDPOINT is not used as the SDK base URL; set COZELOOP_API_BASE_URL only when the SDK ingest endpoint should be overridden.

At hook execution time (Claude Code / Codex), the Python hook script automatically:

1. Reads ~/.cozeloop/credentials.json
2. If the token expires in < 10 minutes, calls the Coze refresh API
3. Updates credentials.json with the new token
4. Passes the fresh token to the CozeLoop SDK before uploading traces

This means traces continue to upload without interruption even across token expiry, as long as the refresh token is still valid.

For OpenClaw, the token is read from openclaw.json at startup. Re-run npx coze_lab --agent=openclaw to refresh it if OpenClaw reports auth errors.

Supported versions

| Agent | Supported versions | |-------|--------------------| | claude-code | 1.2.x, 1.3.x, 1.4.x, 2.0.x, 2.1.x | | codex | 0.134.x, 1.0.x, 1.1.x | | openclaw | 2026.3.x, 2026.4.x, 2026.5.x |

Versions outside this list will show a yellow warning but onboarding will continue.