From 93fa1d1802f33beed9c6cf3239dfe629f329945d Mon Sep 17 00:00:00 2001 From: Luis Pater Date: Thu, 20 Nov 2025 21:07:20 +0800 Subject: [PATCH] **docs: add Amp CLI integration guide to Chinese documentation** - Updated `README_CN.md` to introduce Amp CLI and IDE support. - Added detailed integration guide in `docs/amp-cli-integration_CN.md`. - Covered setup, configuration, OAuth, security, and usage of Amp CLI with Google/ChatGPT/Claude subscriptions. --- README_CN.md | 11 + docs/amp-cli-integration_CN.md | 392 +++++++++++++++++++++++++++++++++ 2 files changed, 403 insertions(+) create mode 100644 docs/amp-cli-integration_CN.md diff --git a/README_CN.md b/README_CN.md index 1719ebf8..be0aa234 100644 --- a/README_CN.md +++ b/README_CN.md @@ -48,6 +48,17 @@ CLIProxyAPI 用户手册： [https://help.router-for.me/](https://help.router-fo 请参见 [MANAGEMENT_API_CN.md](https://help.router-for.me/cn/management/api) +## Amp CLI 支持 + +CLIProxyAPI 已内置对 [Amp CLI](https://ampcode.com) 和 Amp IDE 扩展的支持，可让你使用自己的 Google/ChatGPT/Claude OAuth 订阅来配合 Amp 编码工具： + +- 提供商路由别名，兼容 Amp 的 API 路径模式（`/api/provider/{provider}/v1...`） +- 管理代理，处理 OAuth 认证和账号功能 +- 智能模型回退与自动路由 +- 以安全为先的设计，管理端点仅限 localhost + +**→ [Amp CLI 完整集成指南](docs/amp-cli-integration_CN.md)** + ## SDK 文档 - 使用文档：[docs/sdk-usage_CN.md](docs/sdk-usage_CN.md) diff --git a/docs/amp-cli-integration_CN.md b/docs/amp-cli-integration_CN.md new file mode 100644 index 00000000..19748b31 --- /dev/null +++ b/docs/amp-cli-integration_CN.md @@ -0,0 +1,392 @@ +# Amp CLI 集成指南 + +本指南说明如何在 Amp CLI 和 Amp IDE 扩展中使用 CLIProxyAPI，通过 OAuth 让你能够把已有的 Google/ChatGPT/Claude 订阅与 Amp 的 CLI 一起使用。 + +## 目录 + +- [概述](#概述) + - [应该认证哪些服务提供商？](#应该认证哪些服务提供商) +- [架构](#架构) +- [配置](#配置) +- [设置](#设置) +- [用法](#用法) +- [故障排查](#故障排查) + +## 概述 + +Amp CLI 集成为 Amp 的 API 模式添加了专用路由，同时保持与现有 CLIProxyAPI 功能的完全兼容。这样你可以在同一个代理服务器上同时使用传统 CLIProxyAPI 功能和 Amp CLI。 + +### 主要特性 + +- **提供者路由别名**：将 Amp 的 `/api/provider/{provider}/v1...` 路径映射到 CLIProxyAPI 处理器 +- **管理代理**：将 OAuth 和账号管理请求转发到 Amp 控制平面 +- **智能回退**：自动将未配置的模型路由到 ampcode.com +- **密钥管理**：可配置优先级（配置 > 环境变量 > 文件），缓存 5 分钟 +- **安全优先**：管理路由默认限制为 localhost +- **自动 gzip 处理**：自动解压来自 Amp 上游的响应 + +### 你可以做什么 + +- 使用 Amp CLI 搭配你的 Google 账号（Gemini 3 Pro Preview、Gemini 2.5 Pro、Gemini 2.5 Flash） +- 使用 Amp CLI 搭配你的 ChatGPT Plus/Pro 订阅（GPT-5、GPT-5 Codex 模型） +- 使用 Amp CLI 搭配你的 Claude Pro/Max 订阅（Claude Sonnet 4.5、Opus 4.1） +- 将 Amp IDE 扩展（VS Code、Cursor、Windsurf 等）与同一个代理一起使用 +- 通过一个代理同时运行多个 CLI 工具（Factory + Amp） +- 将未配置的模型自动路由到 ampcode.com + +### 应该认证哪些服务提供商？ + +**重要**：需要认证的提供商取决于你安装的 Amp 版本当前使用的模型和功能。Amp 的不同智能模式和子代理会使用不同的提供商： + +- **Smart 模式**：使用 Google/Gemini 模型（Gemini 3 Pro） +- **Rush 模式**：使用 Anthropic/Claude 模型（Claude Haiku 4.5） +- **Oracle 子代理**：使用 OpenAI/GPT 模型（GPT-5 medium reasoning） +- **Librarian 子代理**：使用 Anthropic/Claude 模型（Claude Sonnet 4.5） +- **Search 子代理**：使用 Anthropic/Claude 模型（Claude Haiku 4.5） +- **Review 功能**：使用 Google/Gemini 模型（Gemini 2.5 Flash-Lite） + +有关 Amp 当前使用哪些模型的最新信息，请参阅 **[Amp 模型文档](https://ampcode.com/models)**。 + +#### 回退行为 + +CLIProxyAPI 采用智能回退机制： + +1. **本地已认证提供商**（`--login`、`--codex-login`、`--claude-login`）： + - 请求使用**你的 OAuth 订阅**（ChatGPT Plus/Pro、Claude Pro/Max、Google 账号） + - 享受订阅自带的额度 + - 不消耗 Amp 额度 + +2. **本地未认证提供商**： + - 请求自动转发到 **ampcode.com** + - 使用 Amp 的后端提供商连接 + - 如果提供商是付费的（OpenAI、Anthropic 付费档），**需要消耗 Amp 额度** + - 若 Amp 额度不足，可能产生错误 + +**建议**：对你有订阅的所有提供商都进行认证，以最大化价值并尽量减少 Amp 额度消耗。如果没有覆盖 Amp 使用的全部提供商，请确保为回退请求准备足够的 Amp 额度。 + +## 架构 + +### 请求流 + +``` +Amp CLI/IDE + ↓ + ├─ Provider API requests (/api/provider/{provider}/v1/...) + │ ↓ + │ ├─ Model configured locally? + │ │ YES → Use local OAuth tokens (OpenAI/Claude/Gemini handlers) + │ │ NO → Forward to ampcode.com (reverse proxy) + │ ↓ + │ Response + │ + └─ Management requests (/api/auth, /api/user, /api/threads, ...) + ↓ + ├─ Localhost check (security) + ↓ + └─ Reverse proxy to ampcode.com + ↓ + Response (auto-decompressed if gzipped) +``` + +### 组件 + +Amp 集成以模块化路由模块（`internal/api/modules/amp/`）实现，包含以下组件： + +1. **路由别名**（`routes.go`）：将 Amp 风格的路径映射到标准处理器 +2. **反向代理**（`proxy.go`）：将管理请求转发到 ampcode.com +3. **回退处理器**（`fallback_handlers.go`）：将未配置的模型路由到 ampcode.com +4. **密钥管理**（`secret.go`）：多来源 API 密钥解析并带缓存 +5. **主模块**（`amp.go`）：负责注册和配置 + +## 配置 + +### 基础配置 + +在 `config.yaml` 中新增以下字段： + +```yaml +# Amp 上游控制平面（管理路由必需） +amp-upstream-url: "https://ampcode.com" + +# 可选：覆盖 API key（否则使用环境变量或文件） +# amp-upstream-api-key: "your-amp-api-key" + +# 安全性：将管理路由限制为 localhost（推荐） +amp-restrict-management-to-localhost: true +``` + +### 密钥解析优先级 + +Amp 模块以如下优先级解析 API key： + +| 来源 | 键名 | 优先级 | 缓存 | +|------|------|--------|------| +| 配置文件 | `amp-upstream-api-key` | 高 | 无 | +| 环境变量 | `AMP_API_KEY` | 中 | 无 | +| Amp 密钥文件 | `~/.local/share/amp/secrets.json` | 低 | 5 分钟 | + +**建议**：日常使用时采用 Amp 密钥文件（最低优先级）。该文件由 `amp login` 自动管理。 + +### 安全设置 + +**`amp-restrict-management-to-localhost`**（默认：`true`） + +启用后，管理路由（`/api/auth`、`/api/user`、`/api/threads` 等）只接受来自 localhost（127.0.0.1、::1）的连接，可防止： +- 浏览器探测式攻击 +- 对管理端点的远程访问 +- 基于 CORS 的攻击 +- 伪造头攻击（例如 `X-Forwarded-For: 127.0.0.1`） + +#### 工作原理 + +此限制使用**实际的 TCP 连接地址**（`RemoteAddr`），而非 `X-Forwarded-For` 等 HTTP 头，能防止头部伪造，但有重要影响： + +- ✅ **直接连接可用**：在本机或服务器直接运行 CLIProxyAPI 时适用 +- ⚠️ **可能不适用于反向代理场景**：部署在 nginx、Cloudflare 等代理后，请求源会显示为代理 IP 而非 localhost + +#### 反向代理部署 + +若需要在反向代理（nginx、Caddy、Cloudflare Tunnel 等）后运行 CLIProxyAPI： + +1. **关闭 localhost 限制**： + ```yaml + amp-restrict-management-to-localhost: false + ``` + +2. **使用替代安全措施**： + - 防火墙规则限制管理路由访问 + - 代理层认证（HTTP Basic Auth、OAuth） + - 网络隔离（VPN、Tailscale、Cloudflare Access） + - 将 CLIProxyAPI 仅绑定 `127.0.0.1`，并通过 SSH 隧道访问 + +3. **nginx 示例配置**（阻止外部访问管理路由）： + ```nginx + location /api/auth { deny all; } + location /api/user { deny all; } + location /api/threads { deny all; } + location /api/internal { deny all; } + ``` + +**重要**：只有在理解安全影响并已采取其他防护措施时，才关闭 `amp-restrict-management-to-localhost`。 + +## 设置 + +### 1. 配置 CLIProxyAPI + +创建或编辑 `config.yaml`： + +```yaml +port: 8317 +auth-dir: "~/.cli-proxy-api" + +# Amp 集成 +amp-upstream-url: "https://ampcode.com" +amp-restrict-management-to-localhost: true + +# 其他常规设置... +debug: false +logging-to-file: true +``` + +### 2. 认证提供商 + +为要使用的提供商执行 OAuth 登录： + +**Google 账号（Gemini 2.5 Pro、Gemini 2.5 Flash、Gemini 3 Pro Preview）：** +```bash +./cli-proxy-api --login +``` + +**ChatGPT Plus/Pro（GPT-5、GPT-5 Codex）：** +```bash +./cli-proxy-api --codex-login +``` + +**Claude Pro/Max（Claude Sonnet 4.5、Opus 4.1）：** +```bash +./cli-proxy-api --claude-login +``` + +令牌会保存到： +- Gemini: `~/.cli-proxy-api/gemini-.json` +- OpenAI Codex: `~/.cli-proxy-api/codex-.json` +- Claude: `~/.cli-proxy-api/claude-.json` + +### 3. 启动代理 + +```bash +./cli-proxy-api --config config.yaml +``` + +或使用 tmux 在后台运行（推荐用于远程服务器）： + +```bash +tmux new-session -d -s proxy "./cli-proxy-api --config config.yaml" +``` + +### 4. 配置 Amp CLI + +#### 方案 A：配置文件 + +编辑 `~/.config/amp/settings.json`： + +```json +{ + "amp.url": "http://localhost:8317" +} +``` + +#### 方案 B：环境变量 + +```bash +export AMP_URL=http://localhost:8317 +``` + +### 5. 登录并使用 Amp + +通过代理登录（请求会被代理到 ampcode.com）： + +```bash +amp login +``` + +像平常一样使用 Amp： + +```bash +amp "Write a hello world program in Python" +``` + +### 6. （可选）配置 Amp IDE 扩展 + +该代理同样适用于 VS Code、Cursor、Windsurf 等 Amp IDE 扩展。 + +1. 在 IDE 中打开 Amp 扩展设置 +2. 将 **Amp URL** 设置为 `http://localhost:8317` +3. 用你的 Amp 账号登录 +4. 在 IDE 中开始使用 Amp + +CLI 和 IDE 可同时使用该代理。 + +## 用法 + +### 支持的路由 + +#### 提供商别名（始终可用） + +这些路由即使未配置 `amp-upstream-url` 也可使用： + +- `/api/provider/openai/v1/chat/completions` +- `/api/provider/openai/v1/responses` +- `/api/provider/anthropic/v1/messages` +- `/api/provider/google/v1beta/models/:action` + +Amp CLI 会使用你在 CLIProxyAPI 中通过 OAuth 认证的模型来调用这些路由。 + +#### 管理路由（需要 `amp-upstream-url`） + +这些路由会被代理到 ampcode.com： + +- `/api/auth` - 认证 +- `/api/user` - 用户资料 +- `/api/meta` - 元数据 +- `/api/threads` - 会话线程 +- `/api/telemetry` - 使用遥测 +- `/api/internal` - 内部 API + +**安全性**：默认限制为 localhost。 + +### 模型回退行为 + +当 Amp 请求模型时： + +1. **检查本地配置**：CLIProxyAPI 是否有该模型提供商的 OAuth 令牌？ +2. **如果有**：路由到本地处理器（使用你的 OAuth 订阅） +3. **如果没有**：转发到 ampcode.com（使用 Amp 的默认路由） + +这实现了无缝混用： +- 你已配置的模型（Gemini、ChatGPT、Claude）→ 你的 OAuth 订阅 +- 未配置的模型 → Amp 的默认提供商 + +### 示例 API 调用 + +**使用本地 OAuth 的聊天补全：** +```bash +curl http://localhost:8317/api/provider/openai/v1/chat/completions \ + -H "Content-Type: application/json" \ + -d '{ + "model": "gpt-5", + "messages": [{"role": "user", "content": "Hello"}] + }' +``` + +**管理端点（仅限 localhost）：** +```bash +curl http://localhost:8317/api/user +``` + +## 故障排查 + +### 常见问题 + +| 症状 | 可能原因 | 解决方案 | +|------|----------|----------| +| `/api/provider/...` 返回 404 | 路径错误 | 确保路径准确：`/api/provider/{provider}/v1...` | +| `/api/user` 返回 403 | 非 localhost 请求 | 在同一机器上访问，或关闭 `amp-restrict-management-to-localhost`（不推荐） | +| 提供商返回 401/403 | OAuth 缺失或过期 | 重新运行 `--codex-login` 或 `--claude-login` | +| Amp gzip 错误 | 响应解压问题 | 更新到最新构建；自动解压应能处理 | +| 模型未走代理 | Amp URL 设置错误 | 检查 `amp.url` 设置或 `AMP_URL` 环境变量 | +| CORS 错误 | 受保护的管理端点 | 使用 CLI/终端而非浏览器 | + +### 诊断 + +**查看代理日志：** +```bash +# 若 logging-to-file: true +tail -f logs/requests.log + +# 若运行在 tmux 中 +tmux attach-session -t proxy +``` + +**临时开启调试模式：** +```yaml +debug: true +``` + +**测试基础连通性：** +```bash +# 检查代理是否运行 +curl http://localhost:8317/v1/models + +# 检查 Amp 特定路由 +curl http://localhost:8317/api/provider/openai/v1/models +``` + +**验证 Amp 配置：** +```bash +# 检查 Amp 是否使用代理 +amp config get amp.url + +# 或检查环境变量 +echo $AMP_URL +``` + +### 安全清单 + +- ✅ 保持 `amp-restrict-management-to-localhost: true`（默认） +- ✅ 不要将代理暴露到公共网络（绑定到 localhost 或使用防火墙/VPN） +- ✅ 使用 `amp login` 管理的 Amp 密钥文件（`~/.local/share/amp/secrets.json`） +- ✅ 定期重新登录轮换 OAuth 令牌 +- ✅ 若处理敏感数据，使用加密磁盘存储配置和 auth-dir +- ✅ 保持代理二进制为最新版本以获取安全修复 + +## 其他资源 + +- [CLIProxyAPI 主文档](https://help.router-for.me/) +- [Amp CLI 官方手册](https://ampcode.com/manual) +- [管理 API 参考](https://help.router-for.me/management/api) +- [SDK 文档](sdk-usage.md) + +## 免责声明 + +此集成仅用于个人或教育用途。使用反向代理或替代 API 基址可能违反提供商的服务条款。你需要对自己的使用方式负责。账号可能会被限速、锁定或封禁。软件不附带任何保证，使用风险自负。