proxycast/docs/content/04.api-reference/5.amp-cli-api.md

---
title: Amp CLI API
description: Amp CLI 集成路由端点
navigation:
  icon: i-heroicons-command-line
---

# Amp CLI API

::alert{type="info"}
本页是开发者进阶文档。若你不涉及 Amp CLI 集成，可跳过。
::

ProxyCast 提供 Amp CLI 兼容的路由端点，支持将 Amp CLI 请求路由到本地 OAuth 凭证。

## 概述

Amp CLI 集成允许你：
- 使用本地 OAuth 凭证处理 Amp CLI 请求
- 将不可用的模型映射到可用的替代模型
- 代理 Amp 的认证和账户管理功能

## Provider 路由

### /api/provider/{provider}/v1/chat/completions

处理 Amp CLI 的 OpenAI 格式聊天请求。

```bash
POST /api/provider/{provider}/v1/chat/completions
Content-Type: application/json
Authorization: Bearer your-api-key
```

#### 支持的 Provider

| Provider | 说明 |
|----------|------|
| `anthropic` | Claude 模型 |
| `openai` | GPT 模型 |
| `google` | Gemini 模型 |

#### 请求示例

```bash
curl http://127.0.0.1:8999/api/provider/anthropic/v1/chat/completions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true
  }'
```

### /api/provider/{provider}/v1/messages

处理 Amp CLI 的 Anthropic Messages 格式请求。

```bash
POST /api/provider/{provider}/v1/messages
Content-Type: application/json
x-api-key: your-api-key
anthropic-version: 2023-06-01
```

#### 请求示例

```bash
curl http://127.0.0.1:8999/api/provider/anthropic/v1/messages \
  -H "x-api-key: your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

## 模型映射

当 Amp CLI 请求的模型不可用时，ProxyCast 可以自动映射到可用的替代模型。

### 配置

```yaml
ampcode:
  model_mappings:
    - from: "claude-opus-4.5"
      to: "claude-sonnet-4"
    - from: "gpt-5"
      to: "gemini-2.5-pro"
    - from: "claude-3-opus-20240229"
      to: "claude-3-5-sonnet-20241022"
```

### 映射行为

1. 收到请求时检查模型名称
2. 如果模型在映射列表中，替换为目标模型
3. 使用替换后的模型名称路由请求
4. 响应中保留原始请求的模型名称

## 管理端点代理

ProxyCast 可以代理 Amp 的认证和账户管理端点到上游服务器。

### /api/auth/*

代理认证相关请求。

```bash
# 登录
POST /api/auth/login

# 刷新 Token
POST /api/auth/refresh

# 登出
POST /api/auth/logout
```

### /api/user/*

代理用户账户相关请求。

```bash
# 获取用户信息
GET /api/user/profile

# 获取使用统计
GET /api/user/usage
```

### 配置

```yaml
ampcode:
  upstream_url: "https://ampcode.com"
  restrict_management_to_localhost: false
```

| 配置项 | 说明 |
|--------|------|
| `upstream_url` | Amp 上游服务器 URL |
| `restrict_management_to_localhost` | 是否限制管理端点只能从 localhost 访问 |

## 使用场景

### 场景 1：使用本地 OAuth 凭证

你有 Kiro 的 Claude 订阅，想用 Amp CLI 但不想额外付费：

1. 配置 ProxyCast 加载 Kiro OAuth 凭证
2. 在 Amp CLI 中配置 ProxyCast 作为 API 端点
3. Amp CLI 请求通过 ProxyCast 路由到 Kiro 凭证

### 场景 2：模型替换

Amp CLI 请求 Claude Opus 4.5，但你只有 Sonnet 4 的访问权限：

```yaml
ampcode:
  model_mappings:
    - from: "claude-opus-4.5"
      to: "claude-sonnet-4"
```

### 场景 3：多 Provider 负载均衡

配置多个凭证，ProxyCast 自动在它们之间负载均衡：

```yaml
credential_pool:
  kiro:
    - id: "kiro-1"
      token_file: "kiro/token-1.json"
    - id: "kiro-2"
      token_file: "kiro/token-2.json"
```

## Amp CLI 配置

在 Amp CLI 中配置 ProxyCast：

```bash
# 设置 API 端点
amp config set api.base_url http://127.0.0.1:8999/api/provider

# 设置 API Key
amp config set api.key your-proxycast-api-key
```

或在配置文件中：

```yaml
# ~/.amp/config.yaml
api:
  base_url: http://127.0.0.1:8999/api/provider
  key: your-proxycast-api-key
```

## 错误处理

### 模型不可用

当请求的模型不可用且没有配置映射时：

```json
{
  "error": {
    "message": "Model 'claude-opus-4.5' is not available",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}
```

### 上游连接失败

当无法连接到 Amp 上游服务器时：

```json
{
  "error": {
    "message": "Failed to connect to upstream server",
    "type": "upstream_error",
    "code": "connection_failed"
  }
}
```

### 凭证耗尽

当所有凭证都不可用时：

```json
{
  "error": {
    "message": "All credentials exhausted",
    "type": "service_unavailable",
    "code": "no_credentials_available"
  }
}
```

响应头会包含 `Retry-After` 指示何时可以重试。