@tonyclaw/llm-inspector

v1.19.1

Published

35 minutes ago

LLM API proxy inspector — captures and displays requests/responses from AI coding tools in a web UI

0High
0Medium
0Low

tonyclaw

claude anthropic openai proxy api-inspector debugging llm ai-coding-tools

llm-inspector

透明捕获、解析、重放和治理 AI 编码工具的 LLM API 流量。

LLM Inspector

llm-inspector 是一个运行在本机的 LLM API 代理调试台，同时提供 Web UI + Proxy + MCP Server。把 Claude Code、OpenCode、Cursor、Cody、MiMo Code 或其他兼容客户端的 API Base URL 指向它，就可以在 Web UI 中实时观察请求、响应、SSE 流式事件、工具调用、Thinking/Reasoning、Token 用量、缓存 Token、请求来源和提供商路由结果；也可以让 Coding Agent 通过 MCP 主动读取日志、复盘会话和重放请求。

它的定位不是一个单纯的抓包工具，而是面向 AI 编码场景的“可观察代理层”：

调试 Agent：看清系统提示词、工具定义、消息、响应、错误和慢请求。
治理 Provider：按模型路由到不同 LLM 提供商，集中管理 API Key、模型、协议 URL 和连接测试。
复现问题：重放历史请求，对比代理处理前后的请求差异，排查客户端、代理和上游之间的问题。
辅助 Agent 自诊断：内置 MCP Server，让 Coding Agent 可以直接查询最近日志、会话、模型、Provider 和重放结果。

默认入口：

Web UI：http://localhost:25947
Proxy：http://localhost:25947/proxy
MCP Server：http://localhost:25947/api/mcp

核心能力

双协议代理：支持 Anthropic Messages API 与 OpenAI Chat Completions API。
路径识别协议：根据 endpoint 选择协议，而不是猜测 body。
- /proxy/v1/messages -> Anthropic
- /proxy/v1/chat/completions -> OpenAI
- /proxy/chat/completions -> OpenAI 兼容路径
多模型 Provider 路由：一个 Provider 可以配置多个模型，同时保存 Anthropic/OpenAI 两套 Base URL。
AI 编码工具适配：覆盖 Claude Code、OpenCode、Cursor、Cody、MiMo Code 等可配置 Base URL 的工具。
实时日志与 SSE 捕获：普通响应和流式响应都会被记录，SSE chunks 支持按需加载。
结构化查看器：按协议解析 Request、Response、Thinking/Reasoning、Answer、Tool Call、Token 和 Cache Token。
会话与 Turn 视图：按 session 分组，展示多轮对话边界、模型、协议、状态、耗时和 Token 汇总。
请求 Diff 与 Replay：比较 Raw/Processed Request，也可以比较同会话相邻请求，并用当前 Provider 配置重放。
Provider 迁移与导入：支持导入/导出 Provider，并可扫描外部工具配置辅助迁移。
运行时代理开关：通过 Settings 或 /api/config 调整代理行为，无需重启。
MCP 原生调试入口：提供 inspector_* 工具，让 Agent 直接读取日志、重放请求、测试 Provider 和管理 Provider。
本地数据持久化：Provider、运行时配置、日志与 SSE chunks 存在本机数据目录，适合离线排查。

Proxy Overview

快速开始

npm 安装

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

启动后会自动打开浏览器。常用参数：

llm-inspector --no-open
llm-inspector --port 3000
llm-inspector --config-dir ./local-config
llm-inspector --providers '[{"name":"OpenAI","apiKey":"sk-...","models":["gpt-4o-mini"],"openaiBaseUrl":"https://api.openai.com/v1","authHeader":"bearer","createdAt":"2026-01-01T00:00:00.000Z","updatedAt":"2026-01-01T00:00:00.000Z","id":"demo"}]'

Docker

cd docker
docker compose up -d

源码运行

需要安装 Bun。

bun install
bun run dev

配置 Provider

打开 Web UI，进入 Settings 添加 Provider：

填写 Provider 名称和 API Key。
添加一个或多个模型名称。代理优先用请求体中的 model 匹配 Provider。
按 Provider 能力填写协议 URL：
- Anthropic Base URL：例如 https://api.anthropic.com
- OpenAI Base URL：例如 https://api.openai.com/v1
选择认证方式：Bearer 或 x-api-key。
使用 Provider Test 验证非流式和流式请求。

同一个 Provider 可以同时配置 Anthropic 和 OpenAI URL。代理会根据客户端请求路径选择协议和上游地址；模型匹配用于决定走哪个 Provider。

Provider 配置支持：

多模型合并：同一 API Key 和 URL 组合会合并模型列表。
导入/导出：可备份和迁移配置，导出时可选择是否包含 API Key。
外部扫描：从支持的外部工具配置中扫描可迁移的 Provider。
来源标记：区分个人或公司 Provider，便于列表管理。

接入 AI 编码工具

Claude Code

macOS / Linux：

ANTHROPIC_BASE_URL=http://localhost:25947/proxy claude

Windows PowerShell：

$env:ANTHROPIC_BASE_URL = "http://localhost:25947/proxy"
claude

如果 API Key 已保存在 llm-inspector 的 Provider 配置中，客户端令牌可以留空：

$env:ANTHROPIC_AUTH_TOKEN = ""

OpenCode

LLM_BASE_URL=http://localhost:25947/proxy opencode

MiMo Code / OpenAI 兼容客户端

OPENAI_BASE_URL=http://localhost:25947/proxy mimo

对于 Cursor、Cody 等工具，请在其设置中将 Anthropic 或 OpenAI Base URL 改为：

http://localhost:25947/proxy

直接发送请求

请先在 Settings 中配置与 model 匹配的 Provider。

Anthropic 格式

curl http://localhost:25947/proxy/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: resolved-by-llm-inspector" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 128,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

OpenAI 格式

curl http://localhost:25947/proxy/v1/chat/completions \
  -H "content-type: application/json" \
  -H "authorization: Bearer resolved-by-llm-inspector" \
  -d '{
    "model": "gpt-4o-mini",
    "max_tokens": 128,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

使用查看器

Simple / Full

Simple：聚焦请求、解析后的响应、工具调用、Thinking/Reasoning 和 Token。
Full：额外显示 Raw Headers、Headers、Raw Request、Raw Response 和 SSE chunks。

Thinking / Reasoning / Answer

查看器按协议分别解析响应：

Anthropic：解析 content[].type === "thinking"、text、tool_use 等内容块。
OpenAI：解析 reasoning_content、thinking、think、message.content 和函数/工具调用。

如果响应因为 max_tokens 提前结束且只返回 Thinking，界面只展示真实存在的内容，不会生成不存在的 Answer。

会话、Turn 与来源

日志会记录：

sessionId、模型、Provider、API format、状态码和耗时。
输入/输出 Token、cache creation/read Token。
客户端端口、PID、工作目录和项目目录。
流式响应的 SSE chunk 索引、类型和数据。

这些信息用于定位“哪一个工具、哪个项目、哪一轮对话、哪个 Provider”产生了问题。

Diff、Replay 与 Export

Diff with Raw：比较代理处理前后的 Request 或 Headers。
Diff with Previous：比较同一会话、同一协议中的相邻请求。
Replay：使用当前 Provider 配置重新发送历史请求。
Export：将捕获日志导出为 ZIP，供离线分析或问题复盘。

MCP Server

MCP 是 llm-inspector 的一等能力。它让 Agent 不只是在 UI 外部“被观察”，还可以主动查询自己刚刚产生的请求链路，完成自诊断和复盘。

典型场景：

最近请求自查：Agent 可以读取最近几条日志，确认模型、Provider、状态码、Token、SSE chunks 和错误信息。
会话复盘：按 sessionId 找到一次编码任务的请求序列，定位是哪一轮、哪个工具调用或哪个上游响应异常。
Provider 调试：列出 Provider、查看配置、触发连接测试，并把测试结果写回日志视图。
请求重放：对历史请求执行 replay，验证问题是否来自客户端、代理配置或上游 Provider。
上下文压缩排查：读取 last user message preview、response preview、cache token 等摘要，辅助判断 Agent 行为变化。

内置 MCP Server 使用 HTTP Streamable transport：

POST http://localhost:25947/api/mcp

Claude Code .mcp.json 示例：

{
  "mcpServers": {
    "llm-inspector": {
      "type": "http",
      "url": "http://localhost:25947/api/mcp"
    }
  }
}

提供 11 个 inspector_* 工具：

| 类型 | 工具 | | --- | --- | | 日志查询 | inspector_list_logs, inspector_get_log, inspector_get_log_chunks | | 索引查询 | inspector_list_sessions, inspector_list_models | | Provider 查询 | inspector_list_providers, inspector_get_provider | | 操作 | inspector_replay_log, inspector_test_provider | | Provider 写入 | inspector_add_provider, inspector_update_provider |

完整说明见 MCP Server 文档。

MCP 接口仅应在可信本机环境使用。Provider 查询工具会返回明文 API Key，请勿将服务暴露到不可信网络。

数据目录与环境变量

默认数据目录：

Windows：%USERPROFILE%\.llm-inspector
macOS / Linux：$HOME/.llm-inspector

常用环境变量：

| 变量 | 默认值 | 说明 | | --- | --- | --- | | PORT | 25947 | Web UI、代理和 MCP 端口 | | LLM_INSPECTOR_DATA_DIR | 系统默认目录 | providers、runtime config、logs、chunks 等数据目录 | | LLM_INSPECTOR_CONFIG_PATH | <dataDir>/providers.json | Provider 配置文件路径 | | LLM_INSPECTOR_PROVIDERS_JSON | 无 | 启动时注入 Provider JSON | | LLM_INSPECTOR_STRIP_CLAUDE_CODE_BILLING_HEADER | 0 | 初始是否移除 Claude Code billing header 文本块 | | LOG_DIR | <dataDir>/logs | 捕获日志和运行日志目录 | | LOG_RETENTION_DAYS | 7 | 日志保留天数 | | CHUNKS_DIR | <dataDir>/chunks | SSE chunks 存储目录 | | PROXY_IDENTITY | inspector9527@Tony | 转发请求使用的代理身份标识 |

Provider API Key 以明文 JSON 保存在本机数据目录中。请保护该目录，并避免在共享或不可信主机上运行服务。

HTTP API

| Endpoint | Method | 说明 | | --- | --- | --- | | /api/health | GET | 健康检查 | | /api/config | GET / PATCH | 查询或更新运行时代理配置 | | /api/config/paths | GET | 查看配置文件路径 | | /api/logs | GET / DELETE | 查询、分页筛选或清空日志；DELETE 可按 id 清理 | | /api/logs/:id | GET | 获取完整日志 | | /api/logs/:id/chunks | GET | 获取 SSE chunks | | /api/logs/:id/replay | POST | 重放请求 | | /api/logs/stream | GET | 实时日志更新 | | /api/sessions | GET | 会话列表 | | /api/models | GET | 模型列表 | | /api/providers | GET / POST | 查询或添加 Provider | | /api/providers/:id | GET / PUT / DELETE | 管理单个 Provider | | /api/providers/:id/test | POST | 测试 Provider 连接 | | /api/providers/:id/test/log | POST | 写入 Provider 测试日志 | | /api/providers/export | GET | 导出 Provider 配置 | | /api/providers/import | POST | 导入 Provider 配置 | | /api/providers/scan | GET | 扫描外部 Provider 配置 | | /api/mcp | POST | MCP HTTP Streamable endpoint |

开发与验证

bun test
bun run typecheck
bun run lint
bun run format:check
bun run build

涉及代理或 UI 的改动还应启动开发服务器，并使用真实 AI 编码工具通过代理完成端到端验证：

bun run dev
ANTHROPIC_BASE_URL=http://localhost:25947/proxy claude

License

MIT