# agent-proxy

**Repository Path**: tragedy_forever/agent-proxy

## Basic Information

- **Project Name**: agent-proxy
- **Description**: agent-proxy
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-22
- **Last Updated**: 2026-06-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# agentProxy

Anthropic API 反向代理，支持多上游动态切换和详细统计。专为 Claude Code 等工具设计，支持 Web UI 和 CLI 热切换，无需重启即可换模型。

## 功能特性

- **Claude Code 原生兼容**：开箱即用，提供 `/v1/models` 端点支持模型校验
- **热切换支持**：Web UI 面板或 CLI 命令行切换上游和模型，无需重启 Claude Code
- **多上游支持**：火山引擎、百度文心、MiniMax、Ollama 等任意 Anthropic-compatible 接口
- **两种配置模式**：
  - 预定义模式：快速切换已配置的上游
  - 自定义模式：自由配置任意 API 端点
- **四种切换方式**：
  - Web UI 可视化面板
  - REST API
  - CLI 命令行工具
  - 热重载配置文件
- **详细统计**：按时间/上游/模型追踪调用次数、Token 用量、延迟

## 兼容协议

| 协议 | 说明 |
|------|------|
| **Anthropic API** | 原生兼容 `/v1/messages`、`/v1/compact`、`/v1/models` 端点格式 |
| **Anthropic-compatible API** | 支持火山引擎、百度文心、OpenRouter、MiniMax 等兼容 Anthropic 格式的服务商 |
| **OpenAI API** | 部分兼容，支持 `/v1/messages` 转发，token 统计支持 `prompt_tokens`/`completion_tokens` 格式 |
| **SSE 流式响应** | 支持完整的 Server-Sent Events 流式传输及 token 用量提取 |

## 快速开始

### 1. 构建

```bash
go build -o agentProxy .
```

### 2. 配置

编辑 `configs/upstreams.yaml` 配置上游服务商：

```yaml
upstreams:
  volcano:
    url: https://ark.cn-beijing.volces.com/api/coding
    api_key: your-volcano-api-key
    models:
      - glm-5.1
      - kimi-k2.6
      - doubao-seed-2.0-code

  baidu:
    url: https://qianfan.baidubce.com/v3
    api_key: your-baidu-api-key
    models:
      - ernie-4.0-8k
      - ernie-3.5-8k

  minimax:
    url: https://api.minimax.com/anthropic
    api_key: your-minimax-api-key
    models:
      - MiniMax-M2.7
      - MiniMax-M2.1

  ollama:
    url: http://localhost:11434
    models:
      - llama3
      - qwen2
```

编辑 `configs/active.yaml` 设置当前激活配置：

```yaml
upstream: volcano
model: glm-5.1
url: ""
api_key: ""
custom_model: ""
```

### 3. 启动

```bash
./agentProxy -listen :8080
```

### 4. 配置 Claude Code

**方法一：配置文件方式**

编辑 Claude Code 配置文件（通常在 `~/.claude/settings.json` 或 `.claude/settings.json`）：

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:8080",
    "ANTHROPIC_AUTH_TOKEN": "任意字符"
  },
  "mcpServers": {}
}
```

**方法二：环境变量方式**

启动 Claude Code 前设置环境变量：

```bash
export ANTHROPIC_BASE_URL=http://localhost:8080
export ANTHROPIC_AUTH_TOKEN=任意字符
claude
```

### 5. 热切换上游/模型（无需重启 Claude Code）

在 Claude Code 运行中，随时可以切换：

- **Web UI 方式**：浏览器打开 `http://localhost:8080/`，选择上游和模型后点击"应用"
- **CLI 方式**：`agent-proxy set volcano glm-5.1`

切换后立即生效，Claude Code 接下来的请求就会使用新配置。

## 配置切换方法

### Web UI 面板（热切换）

访问 `http://localhost:8080/` 打开可视化面板。

功能：
- 查看当前激活配置
- 预定义上游：选择上游和模型后点击应用（立即生效）
- 自定义端点：填写 URL、API Key 和模型名
- 上游管理：增删改预定义上游配置
- 统计面板：按小时/天/月查看调用次数、输入输出 Token

### CLI 命令行（热切换）

```bash
# 切换到预定义上游（立即生效）
agent-proxy set volcano glm-5.1

# 切换到自定义端点
agent-proxy set --url https://custom.api.com/v3 --api-key sk-xxx --model custom-model

# 查看当前配置
agent-proxy get

# 列出所有上游
agent-proxy list

# 查询统计
agent-proxy stats --time-range=day
agent-proxy stats --upstream=volcano --time-range=month
```

### REST API（热切换）

```bash
# 切换到预定义上游（立即生效）
curl -X PUT http://localhost:8080/active \
  -H "Content-Type: application/json" \
  -d '{"upstream":"volcano","model":"glm-5.1"}'

# 切换到自定义端点
curl -X PUT http://localhost:8080/active \
  -H "Content-Type: application/json" \
  -d '{"url":"https://custom.api.com/v3","api_key":"sk-xxx","custom_model":"model-name"}'

# 获取当前配置
curl http://localhost:8080/active

# 查询统计
curl "http://localhost:8080/stats?time_range=hour&upstream=volcano"

# 上游管理
# 创建上游
curl -X POST http://localhost:8080/upstream \
  -H "Content-Type: application/json" \
  -d '{"name":"new-provider","url":"https://new.api.com/v3","api_key":"sk-xxx","models":["model1","model2"]}'

# 更新上游
curl -X PUT http://localhost:8080/upstream/new-provider \
  -H "Content-Type: application/json" \
  -d '{"name":"new-provider","url":"https://new.api.com/v3","api_key":"sk-xxx","models":["model1","model2","model3"]}'

# 删除上游
curl -X DELETE http://localhost:8080/upstream/new-provider
```

### 配置文件热重载

直接编辑 `configs/active.yaml`，每 5 秒自动重载，无需重启。

## API 端点

| 端点 | 方法 | 说明 |
|------|------|------|
| `/v1/messages` | POST | 消息生成，转发到上游 |
| `/v1/compact` | POST | 消息压缩，转发到上游 |
| `/v1/models` | GET | 模型列表，支持 Claude Code 校验 |
| `/models` | GET | 同上，模型列表 |
| `/active` | GET | 获取当前激活配置 |
| `/active` | PUT | 更新激活配置（热切换） |
| `/stats` | GET | 查询统计数据 |
| `/upstreams` | GET | 列出所有上游 |
| `/upstreams/{name}/models` | GET | 列出指定上游的模型 |
| `/upstream` | POST | 创建上游 |
| `/upstream/{name}` | PUT | 更新上游 |
| `/upstream/{name}` | DELETE | 删除上游 |
| `/cli` | POST | CLI 命令接口 |
| `/` | GET | Web UI 面板 |

## 统计 API

```
GET /stats?time_range=hour|day|month&upstream=&model=&start=&end=
```

参数说明：
- `time_range`：时间粒度，`hour`（小时）/ `day`（天）/ `month`（月）
- `upstream`：可选，按上游过滤
- `model`：可选，按模型过滤
- `start`/`end`：可选，时间范围过滤

响应示例：
```json
{
  "total_calls": 1234,
  "total_input_tokens": 500000,
  "total_output_tokens": 300000,
  "data": [
    {
      "time": "2026-04-22 09:00",
      "calls": 50,
      "input_tokens": 12000,
      "output_tokens": 8000,
      "by_model": [
        {
          "model": "glm-5.1",
          "calls": 30,
          "input_tokens": 7000,
          "output_tokens": 5000
        }
      ]
    }
  ]
}
```

## 命令行参数

```
-listen=:8080          监听地址
-upstreams=configs/upstreams.yaml  上游配置文件路径
-active=configs/active.yaml       激活配置文件路径
-router=configs/router.yaml        路由配置文件路径（预留）
-db=stats.db            统计数据库路径
```

## 项目结构

```
.
├── main.go            # 主入口、HTTP 路由、Web UI
├── config/            # 配置管理
│   ├── upstream.go     # 上游配置 CRUD
│   ├── active.go      # 激活配置管理
│   └── router.go      # 项目路由规则（预留）
├── proxy/             # 代理逻辑
│   ├── handler.go     # HTTP 请求转发、token 提取
│   └── transport.go   # HTTP 传输（预留）
├── stats/             # 统计
│   └── db.go          # SQLite 操作
├── cli/               # CLI 工具
│   └── cmd.go         # 命令行命令
├── configs/           # 默认配置
│   ├── upstreams.yaml
│   ├── active.yaml
│   └── router.yaml
└── README.md          # 本文档
```

## 使用场景

1. **Claude Code 接入国内模型**：火山、百度等 API 兼容 Anthropic 格式，通过代理让 Claude Code 用上国产模型
2. **热切换对比模型**：在 Claude Code 运行中，通过 Web UI 或 CLI 一键切换不同上游和模型，无需重启
3. **多模型切换对比**：无需改代码，一键切换不同上游和模型
4. **用量监控**：统一统计各模型的调用次数和 token 用量
5. **OpenRouter 等第三方网关接入**：自定义模式可对接 OpenRouter 等聚合平台

## 注意事项

- API Key 以明文存储在 `configs/upstreams.yaml`，请妥善保管文件权限
- `/stats` 端点无认证，建议本地使用或自行增加认证
- 路由配置（`router.yaml`）目前仅加载，未实际生效（预留功能）

![输入图片说明](image.png)

## License

MIT