# llm-inspector

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

![LLM Inspector](docs/封面v1.15.0.png)

`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](docs/Proxy.png)

## 快速开始

### npm 安装

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

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

```bash
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

```bash
cd docker
docker compose up -d
```

### 源码运行

需要安装 [Bun](https://bun.sh/)。

```bash
bun install
bun run dev
```

## 配置 Provider

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

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

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

Provider 配置支持：

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

## 接入 AI 编码工具

### Claude Code

macOS / Linux：

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

Windows PowerShell：

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

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

```powershell
$env:ANTHROPIC_AUTH_TOKEN = ""
```

### OpenCode

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

### MiMo Code / OpenAI 兼容客户端

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

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

```text
http://localhost:25947/proxy
```

## 直接发送请求

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

### Anthropic 格式

```bash
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 格式

```bash
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：

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

Claude Code `.mcp.json` 示例：

```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 文档](docs/MCP-Server.md)。

> 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 |

## 开发与验证

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

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

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

## 更多文档

- [功能介绍](docs/Features.md)
- [安装指南](docs/Installation.md)
- [使用说明](docs/Usage.md)
- [架构说明](docs/Architecture.md)
- [开发指南](docs/Development.md)
- [MCP Server](docs/MCP-Server.md)

## License

MIT
