openclaw-autoproxy 1.0.2 → 1.0.5

package/README.md

@@ -1,210 +1,117 @@
-# openclaw-autoproxy (OpenClaw Auto Gateway)
+# Documentation: [English](README.md) · [简体中文](README.zh-CN.md)
 
-Local proxy gateway that forwards OpenAI-compatible APIs and automatically switches model IDs when upstream returns retryable status codes (for example 412).
+# Make Large Model APIs Always Available in OpenClaw
 
-## Features
+OpenClaw Auto Proxy Gateway — a local proxy that exposes OpenAI-compatible `/v1/*` and Anthropic-compatible `/anthropic/*` endpoints, forwarding requests to configured upstreams and supporting automatic model fallback based on `routes.yml`.
 
-- OpenAI-compatible proxy endpoint: `/v1/*`
-- Automatic model fallback on retryable statuses for `model: auto` only (default: 412, 429, 500, 502, 503, 504)
-- Model-based route selection: different models can use different upstream URLs and auth headers
-- Per-model and global fallback chains
-- TypeScript runtime powered by `tsx`
-- Node.js HTTP gateway server (openclaw-style)
-- Cross-platform startup on macOS and Windows (Node.js 18+)
-- Health endpoint: `/health`
+## Quick start
 
-## Quick Start
-
-1. Install Node.js 18 or newer.
-2. Install dependencies:
+1. Install globally (recommended):
 
 ```bash
-npm install
+npm i -g openclaw-autoproxy@latest
 ```
 
-3. Create local env file:
-
-macOS/Linux:
+2. Edit the route configuration in the project root:
 
 ```bash
-cp .env.example .env
+vim routes.yml
 ```
 
-Windows PowerShell:
-
-```powershell
-Copy-Item .env.example .env
-```
-
-4. Edit `.env` (runtime options) and `routes.yml` (all upstream route mappings and auth).
-5. Start the gateway:
+3. Start the gateway (installed mode):
 
 ```bash
-npm run dev
+openclaw-autoproxy start
 ```
 
-Production mode:
+Or run without installing (via `npx`):
 
 ```bash
-npm start
+npx openclaw-autoproxy@latest start
 ```
 
-## Global CLI Usage
+After starting, the local OpenAI-compatible endpoint is usually available at `http://127.0.0.1:8787/v1/*`, and the local Anthropic-compatible endpoint at `http://127.0.0.1:8787/anthropic/*` (port is configurable).
 
-You can install this project globally and run it via `openclaw-autoproxy`:
+## Example `routes.yml`
 
-```bash
-npm i -g .
-openclaw-autoproxy gateway start
-```
-
-Watch mode:
+```yaml
+# Optional global defaults
+defaults:
+  authHeader: cf-aig-authorization
+  authPrefix: "Bearer "
+  apiKey: xxxxxxxxxxxxxxxxxx
 
-```bash
-openclaw-autoproxy gateway dev
-```
+retryStatusCodes: [412, 429, 500, 502, 503, 504]
 
-Show CLI help:
+routes:
+  - name: openai
+    url: http://api.openai.com
+    model: gpt-4.1
+    # Route-level token (overrides defaults)
+    apiKeyEnv: UPSTREAM_API_KEY
 
-```bash
-openclaw-autoproxy gateway help
+  - name: azure
+    url: http://azure-openai-endpoint
+    model: gpt-3.5-turbo
+    apiKeyEnv: UPSTREAM_API_KEY
 ```
 
-Backward-compatible aliases are still supported:
+## Common commands
 
-```bash
-openclaw-autoproxy start
-openclaw-autoproxy dev
-openclaw-autoproxy help
-```
-
-## OpenAI-Compatible Calls For 3 Models
+- Start: `openclaw-autoproxy start`
+- Dev (watch): `openclaw-autoproxy dev`
+- Help: `openclaw-autoproxy help`
 
-After starting gateway locally, always call the local OpenAI-style endpoint:
+Quick run (installed):
 
 ```bash
-curl -X POST http://127.0.0.1:8787/v1/chat/completions \
-  -H "Content-Type: application/json" \
-  -d '{
-    "model": "GLM-4.7-Flash",
-    "messages": [{"role":"user","content":"你好"}]
-  }'
+npm i -g openclaw-autoproxy@latest
+vim routes.yml
+openclaw-autoproxy start
 ```
 
-```bash
-curl -X POST http://127.0.0.1:8787/v1/chat/completions \
-  -H "Content-Type: application/json" \
-  -d '{
-    "model": "doubao-seed-2-0-pro-260215",
-    "messages": [{"role":"user","content":"你好"}]
-  }'
-```
+Quick run (npx):
 
 ```bash
-curl -X POST http://127.0.0.1:8787/v1/chat/completions \
-  -H "Content-Type: application/json" \
-  -d '{
-    "model": "ernie-4.5-turbo-128k",
-    "messages": [{"role":"user","content":"你好"}]
-  }'
+npx openclaw-autoproxy@latest start
 ```
 
-## API
+## Usage example
 
-- `ALL /v1/*`: Forward to upstream; automatic model fallback is used only when request model is `auto`.
-- `GET /health`: Health check and active retry status list.
-
-## Project Structure
-
-```text
-src/
-  gateway/
-    config.ts
-    proxy.ts
-    server-http.ts
-    server.impl.ts
-    server.ts
-```
-
-### Example Chat Request
-
-```bash
-curl -X POST http://127.0.0.1:8787/v1/chat/completions \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer <your-upstream-token>" \
-  -d '{
-    "model": "gpt-4.1",
-    "messages": [{"role": "user", "content": "hello"}],
-    "temperature": 0.2
-  }'
-```
-
-Then call local gateway:
+Call the gateway locally:
 
 ```bash
 curl -X POST http://127.0.0.1:8787/v1/chat/completions \
-  -H "Content-Type: application/json" \
-  -d '{
-    "model": "GLM-4.7-Flash",
-    "messages": [{"role":"user","content":"你好"}]
+  --header 'Content-Type: application/json' \
+  --data '{
+    "model": "auto",
+    "messages": [
+      {
+        "role": "user",
+        "content": "what model are you"
+      }
+    ]
   }'
 ```
 
-### Helpful Response Headers
-
-- `x-gateway-model-used`: The actual model used by this attempt.
-- `x-gateway-attempt-count`: Number of attempts before returning response.
-- `x-gateway-switched`: `1` when model fallback happened in this response.
-
-### Switch Notice In Response Data
-
-- JSON response: when fallback happened, gateway appends `gateway_notice` at top-level JSON.
-- SSE response: when fallback happened, gateway prepends one event:
-
-```text
-event: gateway_notice
-data: {"fromModel":"...","toModel":"...","triggerStatus":412,...}
-```
-
-## Fallback Strategy
-
-The gateway behavior is split by request model:
-
-1. `model != auto`: pinned mode, only the requested model is used (no automatic switch).
-2. `model == auto`: automatic mode, candidates are all enabled route models from `routes.yml`, and each request uses a round-robin start model.
+Notes:
+- Using `"model": "auto"` causes the gateway to automatically rotate and fallback between candidate models configured in `routes.yml` when upstream returns retryable errors.
+- To pin a specific model, replace `"auto"` with the desired model name (for example, `"gpt-4.1"`).
 
-When upstream returns a status in `retryStatusCodes` (from `routes.yml`), automatic mode retries using the next candidate model in the same rotated list. If this key is absent, it falls back to `RETRY_STATUS_CODES` env.
+## Anthropic Compatibility
 
-## Model Route Configuration
+- The local `/anthropic/v1/messages` endpoint can translate Anthropic Messages API requests into OpenAI-compatible `chat/completions` requests when the selected upstream route is OpenAI-style rather than native Anthropic.
+- This translation covers both non-streaming and streaming text/tool-call responses for OpenAI-style upstream routes.
+- When an upstream returns `4xx` or `5xx`, the gateway now logs a compact `[gateway] upstream_error ...` line with the selected route, model, upstream URL, and a response body snippet.
 
-`routes.yml` is loaded automatically from the project root.
 
-Recommended YAML shape:
-
-- `defaults`: optional global auth defaults used by all routes
-- `retryStatusCodes`: optional array of retryable HTTP status codes (for example `[412, 429, 500, 502, 503, 504]`)
-- `routes`: required array of route objects
-
-Top-level array is also supported when you do not need global defaults.
-
-Each route object supports:
-
-- `name`: optional logical route name
-- `url`: upstream URL
-- `model`: model list (or a single string)
-- `authHeader`: optional auth header name
-- `authPrefix`: optional auth value prefix (default `Bearer `)
-- `apiKey`: inline token value (preferred in this setup)
-- `apiKeyEnv`: optional env-based token fallback
-- `headers`: optional fixed headers map
-- `isBaseUrl`: optional boolean to force base URL behavior
-- `enabled`: optional boolean (default `true`), set `false` to disable the route without deleting it
+## Notes
 
-`routes.yml` is required and loaded from the project root.
+- `routes.yml` is loaded from the project root.
+- Prefer `UPSTREAM_API_KEY` as an environment variable for upstream authentication. Route-level `apiKey` is supported but not recommended for production.
+- If a route authenticates with the standard `Authorization` header, the client `Authorization` header is forwarded unless route credentials override it. If a route authenticates with a different header such as `cf-aig-authorization`, the gateway strips conflicting client auth headers such as `Authorization` and `x-api-key` to avoid leaking dummy or incompatible provider tokens upstream.
+- Streaming responses are forwarded as streams when an attempt succeeds.
+- When automatic model fallback occurs, the gateway may append a `gateway_notice` in JSON responses or emit a `gateway_notice` SSE event.
 
-## Notes
+See the implementation and more configuration options under `src/gateway`.
 
-- If client request already includes `Authorization`, gateway forwards it.
-- If client request does not include `Authorization`, gateway uses `UPSTREAM_API_KEY`.
-- Streaming responses are forwarded as stream when an attempt succeeds.
-- Requests with invalid JSON body return `400`.

package/README.zh-CN.md

@@ -0,0 +1,127 @@
+# 在 OpenClaw 中让大模型 API 永远可用
+
+OpenClaw 自动代理网关 — 在本地同时提供 OpenAI 兼容的 `/v1/*` 和 Anthropic 兼容的 `/anthropic/*` 接口，转发请求到配置的上游，并根据 `routes.yml` 支持模型自动回退与路由选择。
+
+## 快速开始
+
+1. 全局安装（推荐）：
+
+```bash
+npm i -g openclaw-autoproxy@latest
+```
+
+2. 编辑路由配置（位于项目根目录）：
+
+```bash
+vim routes.yml
+```
+
+3. 启动代理（已安装模式）：
+
+```bash
+openclaw-autoproxy start
+```
+
+或使用 `npx`（无需安装）：
+
+```bash
+npx openclaw-autoproxy@latest start
+```
+
+启动后，本地 OpenAI 兼容接口通常可通过 `http://127.0.0.1:8787/v1/*` 访问，本地 Anthropic 兼容接口可通过 `http://127.0.0.1:8787/anthropic/*` 访问（端口可配置）。
+
+## 示例 `routes.yml`
+
+```yaml
+# 可选全局默认设置
+defaults:
+  authHeader: cf-aig-authorization
+  authPrefix: "Bearer "
+  apiKey: xxxxxxxxxxxxxxxxxx
+
+retryStatusCodes: [412, 429, 500, 502, 503, 504]
+
+routes:
+  - name: openai
+    url: https://api.openai.com
+    model: gpt-4.1
+    # 路由级 token（优先于 defaults）
+    apiKeyEnv: UPSTREAM_API_KEY
+
+  - name: azure
+    url: https://your-azure-endpoint
+    model: gpt-3.5-turbo
+    apiKeyEnv: UPSTREAM_API_KEY
+```
+
+## 常用命令
+
+- 启动：`openclaw-autoproxy start`
+- 开发（热重载）：`openclaw-autoproxy dev`
+- 帮助：`openclaw-autoproxy help`
+
+快速示例（安装并立即启动）：
+
+```bash
+npm i -g openclaw-autoproxy@latest
+vim routes.yml
+openclaw-autoproxy start
+```
+
+使用 npx 直接运行（win）：
+
+```bash
+npx openclaw-autoproxy@latest start
+```
+
+## 使用示例
+
+通过本地代理调用模型（示例）：
+
+```bash
+curl -X POST http://127.0.0.1:8787/v1/chat/completions \
+  --header 'Content-Type: application/json' \
+  --data '{
+    "model": "auto",
+    "messages": [
+      {
+        "role": "user",
+        "content": "你是啥模型"
+      }
+    ]
+  }'
+```
+
+说明：
+- 使用 `model: "auto"` 时，网关会在 `routes.yml` 中已启用的候选模型间自动切换并在可重试的上游错误时进行回退。
+- 若希望指定具体模型，请替换 `"model": "auto"` 为目标模型名（例如 `"gpt-4.1"`）。
+
+## Anthropic 兼容说明
+
+- 本地 `/anthropic/v1/messages` 在命中 OpenAI 风格上游时，会把 Anthropic Messages API 请求转换为 OpenAI `chat/completions` 请求。
+- 当前转换同时支持非流式和流式的文本/工具调用返回，即使选中的上游是 OpenAI 风格路由也可以使用 Anthropic Messages 流式接口。
+- 当上游返回 `4xx` 或 `5xx` 时，网关现在会输出一条精简的 `[gateway] upstream_error ...` 日志，包含路由、模型、上游 URL 和响应体摘要。
+
+## 对接 Claude Code
+
+Claude Code 使用 Anthropic 风格接口。这个网关在本地暴露 `/anthropic/*`，并在转发到上游时自动映射为 `/v1/*`。
+
+让 Claude Code 指向本地网关：
+
+```bash
+export ANTHROPIC_BASE_URL=http://127.0.0.1:8787/anthropic
+export ANTHROPIC_API_KEY=dummy-key
+```
+
+说明：
+- 如果上游鉴权由网关路由凭证负责，`ANTHROPIC_API_KEY` 可以是占位值。
+- 为兼容历史配置，当路由 URL 固定为 `/v1/chat/completions` 时，网关也会自动把 Claude 相关路径（`/v1/messages*`、`/v1/models`、`/v1/complete`）重写到对应上游路径。
+
+## 说明
+
+- `routes.yml`：项目根目录下的上游路由与认证配置。
+- `UPSTREAM_API_KEY`：建议通过环境变量提供上游认证密钥；`apiKey` 可用于临时或测试场景但不推荐在生产中明文存放。
+- 如果某条路由本身就是通过标准 `Authorization` 头鉴权，客户端传入的 `Authorization` 会继续转发，除非被路由凭证覆盖。如果某条路由使用 `cf-aig-authorization` 这类非标准鉴权头，网关会移除冲突的客户端认证头，例如 `Authorization` 和 `x-api-key`，避免把本地 dummy key 或不兼容的 provider token 透传到上游。
+- 当发生自动回退时，网关可能在 JSON 返回中附加 `gateway_notice`，或在 SSE 中发送 `gateway_notice` 事件。
+
+更多高级配置与实现细节请查看 `src/gateway` 目录。