Agent Inspector

Agent Inspector is an agent observability and knowledge-capture platform for AI coding tools. It keeps the local proxy, log capture, MCP, and Chrome companion foundation, and evolves it toward agent interaction analysis, knowledge extraction, and memory-ready workflows for systems such as OpenClaw.

The npm package and CLI remain agent-inspector; the platform name is Agent Inspector.

What It Does

• Runs a local transparent proxy for Anthropic and OpenAI-compatible APIs, including OpenAI Chat Completions and Responses paths.
• Captures model requests, responses, tool definitions, token usage, and errors.
• Provides a web UI for browsing sessions and logs in real time.
• Exposes sessions, logs, runs, and evidence packs through MCP Tools, Resources, and Prompts.
• Includes a Chrome companion extension for quick capture status and log navigation.
• Generates reviewable knowledge candidates from agent sessions.
• Bridges approved knowledge to OpenClaw while keeping OpenClaw hidden behind the Inspector surface.

Quick Start

Install the published CLI:

npm install -g @tonyclaw/agent-inspector
agent-inspector

Optional MCP-first companion package:

npm install -g @tonyclaw/agent-inspector-mcp
agent-inspector-mcp doctor

Agent Inspector requires Node.js 22 or newer. Node.js 24 LTS is recommended for production use.

By default, Agent Inspector binds to 127.0.0.1 and local tools need no Inspector credential. With --host 0.0.0.0, non-loopback coding tools must authenticate /proxy with a dedicated AGENT_INSPECTOR_PROXY_TOKEN, supplied as Proxy-Authorization: Bearer <token> or X-Agent-Inspector-Proxy-Token: <token>. Provider Authorization remains separate and is never accepted as the Inspector proxy credential. The UI, REST API, and MCP control plane remain local-only unless AGENT_INSPECTOR_CONTROL_TOKEN is configured for authenticated remote API/MCP clients. AGENT_INSPECTOR_ALLOW_UNAUTHENTICATED_REMOTE_PROXY=1 and AGENT_INSPECTOR_ALLOW_REMOTE_CONTROL=1 are temporary compatibility overrides intended only for a trusted firewall or loopback-only port mapping.

The packaged CLI keeps the protected identity ingress enabled even on loopback because it also owns Host validation, CSRF enforcement, credential scoping, and first-hop byte budgets. Disabling it with --no-identity-proxy requires the explicit diagnostic-only AGENT_INSPECTOR_ALLOW_UNPROTECTED_INGRESS=1 override.

When exposing Inspector through a named reverse proxy, add its public hostname to the comma-separated AGENT_INSPECTOR_TRUSTED_HOSTS allowlist. Browser mutations require same-origin CSRF proof; the built-in UI supplies it automatically. The public ingress streams request bodies with backpressure and defaults to a 64 MiB hard limit and a 120 second body deadline; override these with positive integer byte/millisecond values in AGENT_INSPECTOR_MAX_REQUEST_BYTES and AGENT_INSPECTOR_REQUEST_TIMEOUT_MS when a trusted workload requires different bounds.

@tonyclaw/agent-inspector runs the local UI, proxy, REST API, storage, and built-in /api/mcp endpoint. @tonyclaw/agent-inspector-mcp is the enhancement package for stdio-first MCP clients and setup automation; it bridges to the local Inspector endpoint without moving your captured evidence out of the machine.

On Windows, the npm install step creates a local agent-inspector.exe runtime from the user's installed Node.js runtime. The long-running server process therefore appears in Task Manager as Agent Inspector with the project icon. The executable also carries standard FileVersion and ProductVersion metadata for the installed package version. If npm lifecycle scripts are disabled, Agent Inspector falls back to node.exe and keeps working normally. Set AGENT_INSPECTOR_SKIP_WINDOWS_RUNTIME=1 to skip the Windows runtime metadata step explicitly.

For Linux containers, the Windows runtime setup is a no-op. To keep images lean, install with optional dependencies omitted:

npm install -g --omit=optional @tonyclaw/agent-inspector

Optional guided setup:

agent-inspector onboard

The onboarding command installs guided setup skills for local agents:

• Claude Code: ~/.claude/skills/agent-inspector-onboard/SKILL.md plus a slash command.
• Codex: ~/.codex/skills/agent-inspector-onboard/SKILL.md, focused on connecting http://localhost:9527/api/mcp through Codex mcp_servers.agent-inspector.
• OpenCode: run agent-inspector onboard --opencode-only to merge mcp.agent-inspector into ~/.config/opencode/opencode.json or opencode.jsonc, then verify with opencode mcp list.
• MiMo Code: run agent-inspector onboard --mimo-only to merge mcp.agent-inspector into ~/.config/mimocode/mimocode.jsonc or mimocode.json, then route MiMo through the proxy with OPENAI_BASE_URL=http://localhost:9527/proxy.

During npm global install, Agent Inspector also makes a best-effort onboarding skill install for detected local agents. If ~/.claude exists, it installs the Claude Code skill and slash command. If ~/.codex exists, it installs the Codex skill. Generated onboarding files are stamped with the current npm package version; a later package install refreshes older generated files automatically, while same-version, newer-version, or user-created files without Agent Inspector version metadata are left in place.

Set AGENT_INSPECTOR_SKIP_CLAUDE_SKILL=1 or AGENT_INSPECTOR_SKIP_CODEX_SKILL=1 to skip either postinstall step. Set AGENT_INSPECTOR_INSTALL_CLAUDE_SKILL=1 or AGENT_INSPECTOR_INSTALL_CODEX_SKILL=1 to attempt installation even before the corresponding agent home directory exists. To refresh generated onboarding files later, run agent-inspector onboard --force.

To check what is installed, run agent-inspector onboard --status. It reports each generated file, its stamped version, whether it is current/outdated/custom, and the suggested next command. For scripts and CI checks, use agent-inspector onboard --status --json.

OpenCode and MiMo Code config is explicit rather than installed during npm postinstall, because it edits a real tool config file instead of adding an Agent Inspector generated skill. Use agent-inspector onboard --status --opencode-only --json or agent-inspector onboard --status --mimo-only --json to inspect those MCP entries.

Before uninstalling the npm package, run agent-inspector onboard --uninstall to remove matching generated onboarding files. The uninstall command only removes Agent Inspector generated files whose metadata version matches the currently installed npm package. npm v7+ does not run package uninstall lifecycle scripts, so npm uninstall -g @tonyclaw/agent-inspector alone cannot reliably clean these files automatically.

For local development from source:

bun install
bun run dev

Run a local health check when you need to verify the proxy and installed configuration:

agent-inspector doctor

The default doctor check covers proxy health, provider configuration, and package metadata. Chrome companion source and zip artifacts are optional and only checked when you ask for them explicitly:

agent-inspector doctor --chrome-extension

Then point an AI coding tool at the proxy:

ANTHROPIC_BASE_URL=http://localhost:9527/proxy <tool>

The web UI runs at http://localhost:9527. The public proxy endpoint is also http://localhost:9527/proxy; internally Agent Inspector may run the app on a private helper port, but AI tools should use the public URL printed by the CLI.

The legacy http://localhost:9527 port is closed by default. If you need a temporary alias for older AI tool or MCP configs, start with agent-inspector --legacy-port.

v3.0 Port Migration

Agent Inspector v3.0 changes the default public port from 9527 to 9527. The packaged CLI now opens only 9527 by default. Existing AI coding tool and MCP configs that still point at 9527 should be moved to 9527, or you can temporarily start with agent-inspector --legacy-port.

Use these endpoints for new configs:

• Web UI: http://localhost:9527
• Proxy: http://localhost:9527/proxy
• OpenAI-compatible /v1 proxy: http://localhost:9527/proxy/v1
• MCP: http://localhost:9527/api/mcp

If you intentionally need the old compatibility port, start with agent-inspector --legacy-port.

For Codex-style OpenAI Responses clients, configure the proxy as an OpenAI-compatible /v1 base:

model_provider = "agent-inspector"

[model_providers."agent-inspector"]
base_url = "http://127.0.0.1:9527/proxy/v1"
wire_api = "responses"

Documentation Map

• Installation: install and runtime notes.
• Usage: daily capture, browsing, replay, and export workflows.
• MCP Server: MCP setup plus tools, resources, prompts, and evidence usage for coding agents.
• Troubleshooting: port, provider, MCP, Replay, Jenkins, and GitCode fixes.
• Jenkins + GitCode WebHook: team CI and tunnel setup.
• Local Release Helper: local maintainer release helper.

Capture Modes

Agent Inspector starts in simple capture mode by default:

agent-inspector
agent-inspector --mode simple

Simple mode keeps the proxy lightweight for everyday use. It records the data needed for the session timeline, request/response views, token usage, provider routing, errors, and knowledge workflows, but it does not retain raw request headers, upstream headers, or detailed streaming chunk artifacts.

Use full mode when you need API-format-level diagnostics:

agent-inspector --mode full

Full mode captures the additional raw details used by the Raw Headers, Headers, and Raw Response views. It is useful for provider debugging, header transformation checks, and SSE stream inspection, but it uses more CPU, memory, and disk.

The mode is decided at process start. To change modes, restart the server. You can also set AGENT_INSPECTOR_MODE=full or AGENT_INSPECTOR_CAPTURE_MODE=full; the CLI flag takes precedence over the environment.

Provider URLs And Responses

Provider URL fields are base URLs. The UI shows the immutable API suffix next to each input and a Final URL preview beneath it, using the same upstream URL builder that the proxy uses at runtime. This makes path mistakes visible before saving the Provider.

| Provider field | Enter this kind of base URL | Runtime suffix | | --- | --- | --- | | Anthropic Base URL | https://api.anthropic.com | /v1/messages | | OpenAI Chat Base URL | https://api.openai.com | /v1/chat/completions | | OpenAI Responses Base URL | https://api.openai.com | /v1/responses |

Existing configurations that already store a full endpoint stay compatible. For example, https://api.minimaxi.com/v1/responses remains exactly that for Responses requests; Agent Inspector does not append /v1/responses a second time. Bases that already end in /v1 also avoid /v1/v1 duplication.

MiniMax supports both OpenAI-compatible endpoints:

https://api.minimaxi.com/v1/chat/completions
https://api.minimaxi.com/v1/responses

In the Provider UI, enter https://api.minimaxi.com as the OpenAI Chat and OpenAI Responses base; the preview will show the final endpoint with the suffix appended. DeepSeek's official API supports OpenAI Chat Completions but does not currently expose OpenAI Responses, so leave the Responses URL empty for DeepSeek unless you are routing through a compatible gateway.

The proxy chooses protocol by request path, not by Provider name:

| Client-facing path | Parsed as | | --- | --- | | /proxy/v1/messages | Anthropic | | /proxy/v1/chat/completions | OpenAI Chat Completions | | /proxy/v1/responses | OpenAI Responses |

Provider Test runs configured endpoints independently: Anthropic, OpenAI Chat Completions, and OpenAI Responses each get separate non-streaming and streaming probes. Test evidence is written into a provider-specific Session so the UI can show which exact path, payload shape, status code, and upstream URL failed.

MCP Evidence Workflows

Agent Inspector exposes MCP at:

http://localhost:9527/api/mcp

Coding agents can connect to this MCP surface directly over Streamable HTTP, or through the companion stdio bridge:

agent-inspector-mcp stdio
agent-inspector-mcp config codex

The companion package is useful for MCP clients that expect a local command. Direct HTTP remains the shortest path for clients that support Streamable HTTP.

The MCP HTTP surface is also documented as OpenAPI YAML in docs/mcp-openapi.yaml.

Use only one transport for the same Inspector instance. If the MCP client supports Streamable HTTP, configure http://localhost:9527/api/mcp directly. If it only supports stdio, configure agent-inspector-mcp stdio; that command is only a bridge to /api/mcp, not a second Inspector server.

Legacy MCP configs that still use http://localhost:9527/api/mcp require starting the CLI with agent-inspector --legacy-port; new configs should use http://localhost:9527/api/mcp.

Coding agents can use the MCP surface in three ways:

• Tools: perform actions such as listing logs, reading bounded log details, testing providers, creating evaluation runs/groups, attaching sessions, and exporting evidence packs.
• Resources: read stable evidence URIs, MCP self-description, session timelines, and evidence file paths without invoking a tool call.
• Prompts: start common analysis/reporting tasks from reusable templates.

The evaluation-oriented run flow is:

1. Call inspector_create_run before a task starts to declare a stable runId, optional sessionId, and optional groupId.
2. Optionally call inspector_set_current_context so the active run/session/model/provider is discoverable through inspector://context/current.
3. Call inspector_update_run as the task moves through running, failed, completed, or cancelled; metadata keys are merged so CI can add build numbers, branch names, or case ids.
4. Let the coding agent run through the proxy as usual.
5. If something fails, call inspector_get_recent_failures or read inspector://failures/recent, then use inspector_search_logs to locate suspicious log ids.
6. Use inspector_get_session_timeline for a quick chronological view before opening large logs.
7. Call inspector_get_run to inspect the declared run.
8. Call inspector_export_evidence to write JSON, Markdown, and HTML artifacts under:

<dataDir>/evidence/<runId>/evidence.json
<dataDir>/evidence/<runId>/evidence.md
<dataDir>/evidence/<runId>/evidence.html

Use inspector_get_evidence_files to return those paths and inspector_export_evidence_bundle to create evidence.zip.

For benchmark or CI systems that spawn multiple coding-agent processes, use a group as the outer evaluation artifact:

1. Call inspector_create_group once for the evaluation batch.
2. Call inspector_set_current_context with the group/project/task.
3. For each OpenCode/Codex/MiMo worker, call inspector_create_run with the group's groupId.
4. Start each OpenCode/Codex/MiMo process through the proxy with its own model/provider.
5. As each process discovers or reports its session id, call inspector_update_run with the real sessionId; runs that have a groupId are auto-attached to the group.
6. Optionally call inspector_add_group_session to override or enrich the group member with groupId, sessionId, and optional runId, provider, model, agent, label, and metadata.
7. Call inspector_update_group to mark the whole batch running, failed, completed, or cancelled.
8. Call inspector_export_group_evidence to write an aggregate provider/model matrix under:

<dataDir>/evidence/groups/<groupId>/evidence.json
<dataDir>/evidence/groups/<groupId>/evidence.md
<dataDir>/evidence/groups/<groupId>/evidence.html

Use inspector_get_group_evidence_files to return those paths and inspector_export_group_evidence_bundle to create group-evidence.zip.

Useful MCP resource URIs:

| Resource | Purpose | | --- | --- | | inspector://mcp/health | Read MCP version, transport, mode, and catalog counts. | | inspector://mcp/capabilities | Read tools split into read vs write/action, resources, prompts, and write mode. | | inspector://mcp/config | Read Streamable HTTP, stdio bridge, OpenCode, MiMo Code, and network config snippets. | | inspector://context/current | Read the active eval/coding context. | | inspector://sessions | List known session ids. | | inspector://sessions/{sessionId} | Read a compact session summary with Inspector links, counts, models, providers, token totals, and recent logs. | | inspector://sessions/{sessionId}/timeline | Read a chronological request timeline for a session. | | inspector://logs/{id} | Read bounded log details for one captured request. Large bodies are capped for agent safety. | | inspector://runs | List declared evaluation runs. | | inspector://failures/recent | Read recent failed/cancelled runs and non-success evidence classifications. | | inspector://runs/{runId} | Read one declared run and its evidence paths. | | inspector://evidence/{runId} | Read the exported Markdown evidence pack for a run. | | inspector://evidence/{runId}/files | Read local paths and byte status for run evidence files. | | inspector://groups | List declared evaluation groups. | | inspector://groups/{groupId} | Read one group, including attached session/run members and evidence paths. | | inspector://groups/{groupId}/sessions | Read only the attached group member list. | | inspector://groups/{groupId}/evidence | Read the exported Markdown evidence pack for a group. | | inspector://groups/{groupId}/evidence/files | Read local paths and byte status for group evidence files. |

Built-in prompt templates help turn captured evidence into user-facing output:

• inspector_analyze_session_failure: explain why a session failed and cite log evidence.
• inspector_triage_recent_failures: prioritize recent failed runs and suggest next actions.
• inspector_generate_jenkins_report: produce a Jenkins-ready Markdown report for a run.
• inspector_generate_group_report: produce a provider/model evaluation report for a group.
• inspector_extract_repro_steps: extract concise reproduction steps from a session.

TonyClaw Lab Ecosystem

TonyClaw Lab turns Inspector into a local control panel for the TonyClaw npm ecosystem. The UI shows installed and latest package status for @tonyclaw/agent-inspector, @tonyclaw/agent-inspector-mcp, and @tonyclaw/eval-harness; it can launch install, upgrade, help, preset discovery, and safe smoke-test recipes without leaving Inspector.

The Lab also exposes copy-ready recipes that connect Inspector evidence, MCP checks, and evaluation runners:

npx @tonyclaw/eval-harness check-inspector-mcp
npx @tonyclaw/eval-harness inspector-smoke --title "TonyClaw Lab smoke" --latest-log-limit 5
npx @tonyclaw/eval-harness runner-presets --format json
npx @tonyclaw/eval-harness run-once --smoke --project-source <project> --work-source <work> --count 1 --parallel 1

Use these recipes as stable starting points for CI smoke tests, local provider checks, and multi-run evaluation batches. Inspector remains the evidence surface; eval-harness drives repeatable workloads; the MCP package bridges coding agents that prefer stdio.

Recipes without placeholders can be run directly from TonyClaw Lab. Template recipes remain copy-ready so users can fill project and work directories explicitly before running them.

Jenkins And GitCode

Team CI, GitCode WebHook setup, Cloudflare Tunnel notes, local push fallback, and the verified PR workflow live in Jenkins + GitCode WebHook. Keep real Jenkins notify tokens, GitCode access tokens, and tunnel URLs out of the repository.

Project Direction

Agent Inspector should stay close to the proven inspector codebase while growing into an agent knowledge layer. The memory flow has four layers:

1. Raw Trace: capture requests, responses, streaming chunks, tools, errors, and token usage.
2. Episode: summarize a session into goal, steps, outcome, failures, and artifacts.
3. Memory Candidate: create reviewable, redacted knowledge candidates with evidence ids.
4. OpenClaw Memory: write approved candidates into OpenClaw's durable recall system.

Agent Inspector owns the first three layers. OpenClaw owns indexing, retrieval, consolidation, and long-term recall.

OpenClaw Memory Bridge

Agent Inspector treats OpenClaw as a hidden memory backend. The preferred integration uses OpenClaw's file-backed memory layout:

OPENCLAW_WORKSPACE_DIR=C:\Users\<you>\.openclaw\workspace
OPENCLAW_GATEWAY_URL=http://127.0.0.1:18789
OPENCLAW_GATEWAY_TOKEN=<gateway-token>
OPENCLAW_SESSION_KEY=main

When a candidate is promoted, Agent Inspector writes sanitized Markdown under:

memory/agent-inspector/YYYY-MM-DD/<candidate>.md

OpenClaw remains responsible for indexing and recall. Run openclaw memory index --force when you need immediate reindexing, or rely on the running OpenClaw memory runtime to sync according to its own policy.

Search stays behind the Inspector facade. Agents call Inspector MCP/API tools, and Inspector invokes OpenClaw Gateway memory_search when OPENCLAW_GATEWAY_URL is configured.

For older deployments, OPENCLAW_MEMORY_URL / OPENCLAW_API_URL remain supported as a legacy HTTP backend.