# llm-inspector

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

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

`llm-inspector` 是一个运行在本机的 HTTP 代理和 Web 调试器。将 Claude Code、OpenCode、Cursor、Cody 或其他兼容客户端的 API Base URL 指向它，即可实时查看请求、响应、工具调用、Thinking、SSE chunks 和 Token 用量。

默认地址：

- Web UI：`http://localhost:25947`
- 代理入口：`http://localhost:25947/proxy`
- MCP Server：`http://localhost:25947/api/mcp`

## 功能

- 同时支持 Anthropic Messages API 和 OpenAI Chat Completions API
- 分开解析两种协议的请求、响应、Thinking、Answer 和 Tool Call
- 按请求路径识别协议：
  - `/proxy/v1/messages` -> Anthropic
  - `/proxy/v1/chat/completions` -> OpenAI
- 实时捕获普通响应和 SSE 流式响应
- 查看原始/处理后的 Headers 和 Request Diff
- 比较同一会话、同一协议的相邻请求
- 请求 Replay、日志 ZIP 导出和按会话/模型筛选
- 会话分组、Turn 边界、缓存 Token 趋势和 Token 汇总
- 提供商管理、双协议 URL、连接测试、导入与导出
- 记录客户端 PID、工作目录和项目目录，便于定位请求来源
- 内置 MCP Server，让 Coding Agent 直接查询日志和管理提供商

![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
```

### Docker

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

### 源码运行

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

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

## 配置提供商

打开 Web UI，进入 **Settings** 添加提供商：

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

同一个提供商可以同时配置 Anthropic 和 OpenAI URL。代理会根据客户端请求路径选择协议与上游地址，而不是根据请求 body 猜测格式。

## 接入 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 的提供商配置中，客户端令牌可以留空：

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

### OpenCode 和其他客户端

不同客户端使用的环境变量名称不同。将其 Anthropic 或 OpenAI Base URL 设置为：

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

例如：

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

对于 Cursor、Cody 等工具，请在其设置中修改 API Base URL。

## 直接发送请求

请先在 Settings 中配置与 `model` 匹配的提供商。

### 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**：聚焦 Request 和解析后的 Response。
- **Full**：额外显示 Raw Headers、Headers、Raw Request、Raw Response 和 SSE chunks。

### Thinking 与 Answer

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

- Anthropic：`content[].type === "thinking"` 与 `content[].type === "text"`
- OpenAI：`reasoning_content`、`thinking`、`think` 与 `message.content`

Thinking 和最终 Answer 会分区显示。如果响应因 `max_tokens` 提前结束且只返回 Thinking，界面只展示真实存在的 Thinking，不会生成不存在的 Answer。

### Diff 与 Replay

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

## MCP Server

内置 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` |
| 提供商查询 | `inspector_list_providers`, `inspector_get_provider` |
| 操作 | `inspector_replay_log`, `inspector_test_provider` |
| 提供商写入 | `inspector_add_provider`, `inspector_update_provider` |

完整说明见 [MCP Server 文档](docs/MCP-Server.md)。

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

## 数据目录与环境变量

默认数据目录：

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

常用环境变量：

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `PORT` | `25947` | Web UI 和代理端口 |
| `LLM_INSPECTOR_DATA_DIR` | 系统默认目录 | providers、runtime config 等数据目录 |
| `LOG_DIR` | `<dataDir>/logs` | 捕获日志和运行日志目录 |
| `LOG_RETENTION_DAYS` | `7` | 日志保留天数 |
| `CHUNKS_DIR` | `<dataDir>/chunks` | SSE chunks 存储目录 |

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

## HTTP API

| Endpoint | Method | 说明 |
| --- | --- | --- |
| `/api/health` | GET | 健康检查 |
| `/api/logs` | GET / DELETE | 查询或清空日志 |
| `/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 | 查询或添加提供商 |
| `/api/providers/:id` | GET / PUT / DELETE | 管理单个提供商 |
| `/api/providers/:id/test` | POST | 测试提供商连接 |
| `/api/mcp` | POST | MCP HTTP Streamable endpoint |

## 开发与验证

```bash
bun test
npm run typecheck
npm run lint
npm run format:check
npm 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
