coze_lab

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

Usage

# Per-agent setup. Local/cloud is inferred from ~/.coze/agents/<agentId>/config.json.
npx coze_lab --agent-id=<agentId>

# Cloud compatibility mode when the caller already knows the framework.
npx coze_lab --cloud --agent=<claude-code|codex|openclaw>

# Send a one-off trace selfcheck. Uses --agent-id patToken locally, or env token in cloud.
npx coze_lab --verify --agent-id=<agentId> --pair-code=<pairCode>

Parameters

| Parameter | Required | Values / Effect | |-----------|----------|-----------------| | --agent-id | Local setup | Resolve ~/.coze/agents/<agentId>/config.json, infer framework/workspace, and read patToken for local trace upload | | --agent | Cloud compatibility only | claude-code, codex, openclaw when no agent config is available | | --cloud | Optional | Forces cloud mode; token must come from COZELOOP_API_TOKEN or COZE_API_TOKEN | | --codex-home | Optional | Override Codex config home for custom cloud runs | | --force | Optional | Force OpenClaw plugin rewrite/reinstall and gateway restart | | --verify | Optional | Send a test trace; local requires --agent-id with patToken, cloud requires env token | | --pair-code | Optional | Add a trace lookup code to selfcheck metadata |

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.

What It Does

1. Token resolution - Local mode reads patToken from ~/.coze/agents/<agentId>/config.json. Cloud mode reads COZELOOP_API_TOKEN or COZE_API_TOKEN from the environment.
2. Agent detection - Verifies the specified agent binary is installed locally.
3. Environment checks - Python >= 3.8 + cozeloop SDK for Claude Code and Codex; SDK is auto-installed via pip if missing. Agent version whitelist warnings are non-fatal.
4. Hook configuration - Writes hook scripts and config files for the selected agent.
5. Selfcheck - Sends a test trace with the resolved token.

There is no Device Code login, OAuth cache, or refresh-token fallback. Legacy --login, --status, --refresh, --logout, and local --agent=<type> commands fail with a migration message.

Per-Agent Hook Files

| Agent | Hook script | Config file | Token environment | |-------|-------------|-------------|-------------------| | claude-code | ~/.claude/hooks/cozeloop_hook.py | ~/.claude/settings.json or agent workspace .claude/settings.json | .claude/settings.local.json | | codex | <CODEX_HOME>/hooks/cozeloop_hook.py | <CODEX_HOME>/hooks.json | <CODEX_HOME>/hooks/cozeloop.env | | openclaw | Node.js plugin | ~/.openclaw/openclaw.json | inline authorization |

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

Local setup requires ~/.coze/agents/<agentId>/config.json to contain patToken. Onboarding writes that PAT into the selected agent's hook configuration and marks the source as agent_config.patToken.

Cloud setup and verification 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, cloud onboard still writes hook configuration but reports verify=fail with token_source.

At hook execution time, Claude Code, Codex, and OpenClaw use only the token written by onboarding or injected by cloud env. They do not read ~/.cozeloop/credentials.json and do not refresh tokens locally. If a token is revoked or rotated, rerun npx coze_lab --agent-id=<agentId>.

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.

Supported Versions

The current hook scheme requires these local capabilities:

• claude-code: settings.json command hooks for Stop and PostToolUse.
• codex: hooks.json command hooks for Stop and PostToolUse.
• openclaw: plugin lifecycle/tool hooks with conversation access enabled.

| Agent | Supported versions | |-------|--------------------| | claude-code | >= 1.0.0 | | codex | >= 0.134.0 | | openclaw | >= 2026.3.0 |

Versions outside this list show a warning but onboarding continues.