openclaw-autoproxy 1.0.0

package/README.md

@@ -0,0 +1,210 @@
+# openclaw-autoproxy (OpenClaw Auto Gateway)
+
+Local proxy gateway that forwards OpenAI-compatible APIs and automatically switches model IDs when upstream returns retryable status codes (for example 412).
+
+## Features
+
+- 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
+
+1. Install Node.js 18 or newer.
+2. Install dependencies:
+
+```bash
+npm install
+```
+
+3. Create local env file:
+
+macOS/Linux:
+
+```bash
+cp .env.example .env
+```
+
+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:
+
+```bash
+npm run dev
+```
+
+Production mode:
+
+```bash
+npm start
+```
+
+## Global CLI Usage
+
+You can install this project globally and run it via `openclaw-autoproxy`:
+
+```bash
+npm i -g .
+openclaw-autoproxy gateway start
+```
+
+Watch mode:
+
+```bash
+openclaw-autoproxy gateway dev
+```
+
+Show CLI help:
+
+```bash
+openclaw-autoproxy gateway help
+```
+
+Backward-compatible aliases are still supported:
+
+```bash
+openclaw-autoproxy start
+openclaw-autoproxy dev
+openclaw-autoproxy help
+```
+
+## OpenAI-Compatible Calls For 3 Models
+
+After starting gateway locally, always call the local OpenAI-style endpoint:
+
+```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":"你好"}]
+  }'
+```
+
+```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":"你好"}]
+  }'
+```
+
+```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":"你好"}]
+  }'
+```
+
+## API
+
+- `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:
+
+```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":"你好"}]
+  }'
+```
+
+### 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.
+
+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.
+
+## Model Route Configuration
+
+`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
+
+`routes.yml` is required and loaded from the project root.
+
+## Notes
+
+- 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/bin/openclaw-autoproxy.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const args = process.argv.slice(2);
+
+const currentFilePath = fileURLToPath(import.meta.url);
+const packageRoot = path.resolve(path.dirname(currentFilePath), "..");
+const serverEntryPath = path.join(packageRoot, "src", "gateway", "server.ts");
+const tsxCliPath = path.join(packageRoot, "node_modules", "tsx", "dist", "cli.mjs");
+const packageJsonPath = path.join(packageRoot, "package.json");
+
+function printHelp() {
+  console.log(`openclaw-autoproxy - OpenClaw Auto Gateway CLI
+
+Usage:
+  openclaw-autoproxy gateway start
+  openclaw-autoproxy gateway dev
+  openclaw-autoproxy start
+  openclaw-autoproxy dev
+  openclaw-autoproxy help
+  openclaw-autoproxy --version
+
+Commands:
+  gateway   Gateway command group
+  start     Legacy alias of: openclaw-autoproxy gateway start
+  dev       Legacy alias of: openclaw-autoproxy gateway dev
+  help      Show root help
+`);
+}
+
+function printGatewayHelp() {
+  console.log(`openclaw-autoproxy gateway - Gateway command group
+
+Usage:
+  openclaw-autoproxy gateway start
+  openclaw-autoproxy gateway dev
+  openclaw-autoproxy gateway help
+
+Subcommands:
+  start     Start gateway server (default)
+  dev       Start gateway in watch mode
+  help      Show gateway help
+`);
+}
+
+async function printVersion() {
+  try {
+    const raw = await readFile(packageJsonPath, "utf8");
+    const pkg = JSON.parse(raw);
+    console.log(pkg.version ?? "unknown");
+  } catch {
+    console.log("unknown");
+  }
+}
+
+function runTsxMode(tsxArgs) {
+  if (!existsSync(tsxCliPath)) {
+    console.error("Missing tsx runtime. Reinstall dependencies and try again.");
+    process.exit(1);
+  }
+
+  const child = spawn(process.execPath, [tsxCliPath, ...tsxArgs], {
+    stdio: "inherit",
+    cwd: process.cwd(),
+    env: process.env,
+  });
+
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+
+    process.exit(code ?? 0);
+  });
+}
+
+function runDevMode(extraArgs) {
+  runTsxMode(["watch", serverEntryPath, ...extraArgs]);
+}
+
+function runStartMode(extraArgs) {
+  runTsxMode([serverEntryPath, ...extraArgs]);
+}
+
+function isHelpFlag(value) {
+  return value === "help" || value === "--help" || value === "-h";
+}
+
+function isVersionFlag(value) {
+  return value === "version" || value === "--version" || value === "-v";
+}
+
+function resolveGatewayAction(rawArgs) {
+  const subcommand = rawArgs[1] ?? "start";
+
+  if (isHelpFlag(subcommand)) {
+    return { type: "gateway-help" };
+  }
+
+  if (subcommand === "start") {
+    return {
+      type: "gateway-start",
+      passthrough: rawArgs.slice(2),
+    };
+  }
+
+  if (subcommand === "dev") {
+    return {
+      type: "gateway-dev",
+      passthrough: rawArgs.slice(2),
+    };
+  }
+
+  return {
+    type: "error",
+    message: `Unknown gateway subcommand: ${subcommand}`,
+  };
+}
+
+function resolveAction(rawArgs) {
+  const command = rawArgs[0];
+
+  if (!command) {
+    return {
+      type: "gateway-start",
+      passthrough: [],
+    };
+  }
+
+  if (isHelpFlag(command)) {
+    return { type: "root-help" };
+  }
+
+  if (isVersionFlag(command)) {
+    return { type: "version" };
+  }
+
+  if (command === "gateway") {
+    return resolveGatewayAction(rawArgs);
+  }
+
+  if (command === "start") {
+    return {
+      type: "gateway-start",
+      passthrough: rawArgs.slice(1),
+    };
+  }
+
+  if (command === "dev") {
+    return {
+      type: "gateway-dev",
+      passthrough: rawArgs.slice(1),
+    };
+  }
+
+  return {
+    type: "error",
+    message: `Unknown command: ${command}`,
+  };
+}
+
+async function main() {
+  const action = resolveAction(args);
+
+  if (action.type === "root-help") {
+    printHelp();
+    return;
+  }
+
+  if (action.type === "gateway-help") {
+    printGatewayHelp();
+    return;
+  }
+
+  if (action.type === "version") {
+    await printVersion();
+    return;
+  }
+
+  if (action.type === "gateway-start") {
+    runStartMode(action.passthrough);
+    return;
+  }
+
+  if (action.type === "gateway-dev") {
+    runDevMode(action.passthrough);
+    return;
+  }
+
+  console.error(action.message);
+  printHelp();
+  process.exitCode = 1;
+}
+
+main().catch((error) => {
+  console.error(
+    error instanceof Error
+      ? `Failed to run openclaw-autoproxy: ${error.message}`
+      : "Failed to run openclaw-autoproxy due to an unknown error.",
+  );
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "openclaw-autoproxy",
+  "version": "1.0.0",
+  "description": "Local model-switching proxy gateway with OpenAI-compatible APIs",
+  "type": "module",
+  "main": "src/gateway/server.ts",
+  "bin": {
+    "openclaw-autoproxy": "bin/openclaw-autoproxy.js"
+  },
+  "scripts": {
+    "cli": "node bin/openclaw-autoproxy.js",
+    "start": "node bin/openclaw-autoproxy.js gateway start",
+    "dev": "node bin/openclaw-autoproxy.js gateway dev",
+    "typecheck": "tsc --noEmit",
+    "test": "echo \"No tests configured\""
+  },
+  "keywords": [
+    "proxy",
+    "gateway",
+    "openclaw-autoproxy",
+    "openai-compatible",
+    "fallback"
+  ],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "dotenv": "^17.4.0",
+    "tsx": "^4.20.6",
+    "yaml": "^2.8.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.1",
+    "typescript": "^5.9.3"
+  }
+}