fix(openclaw): normalize provider proxy routing

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

plugins/openclaw/README.md

@@ -85,7 +85,7 @@ By default, the plugin also rewrites the built-in `openai-codex` provider base U
 
 This does not replace Headroom's existing Codex routing rules. The proxy already decides between `api.openai.com` and `chatgpt.com/backend-api/codex/responses` based on ChatGPT auth. The plugin change only points OpenClaw's provider config at the active proxy in memory and preserves the rest of the provider config.
 
-You can also route additional provider ids such as `anthropic`, `copilot`, or `minimax-portal` through the same proxy:
+You can also route additional provider ids such as `anthropic`, `github-copilot`, `google`, or `openrouter` through the same proxy:
 
 ```json
 {
@@ -94,7 +94,7 @@ You can also route additional provider ids such as `anthropic`, `copilot`, or `m
       "headroom": {
         "enabled": true,
         "config": {
-          "gatewayProviderIds": ["openai-codex", "anthropic", "copilot", "minimax-portal"]
+          "gatewayProviderIds": ["openai-codex", "anthropic", "github-copilot", "google", "openrouter"]
         }
       }
     }
@@ -104,6 +104,20 @@ You can also route additional provider ids such as `anthropic`, `copilot`, or `m
 
 When `gatewayProviderIds` is set, it becomes the exact list the plugin rewrites in memory for the current gateway process.
 
+For convenience, the plugin also accepts family aliases:
+- `codex` -> `openai-codex`
+- `claude` -> `anthropic`
+- `copilot` -> `github-copilot`
+- `gemini` -> `google`
+
+When OpenClaw has already resolved a provider's upstream `baseUrl`, the plugin preserves protocol-specific path segments while swapping only the origin. That keeps provider families on the right proxy route:
+- Codex / ChatGPT backend: `/backend-api`
+- OpenAI-compatible providers: `/v1` or `/api/v1`
+- GitHub Copilot Claude-family models: `/anthropic`
+- Gemini: `/v1beta`
+
+GitHub Copilot is a special case because OpenClaw can route it through either OpenAI Responses or Anthropic Messages depending on the selected model. The plugin only rewrites Copilot when OpenClaw has already resolved the upstream `baseUrl`, so it can preserve the correct `/v1` or `/anthropic` path instead of guessing.
+
 The routing is intentionally lightweight and reversible:
 - the plugin does not persist provider `baseUrl` changes back to `openclaw.json`
 - disabling the plugin, clearing `gatewayProviderIds`, or restarting without Headroom restores OpenClaw's normal provider resolution
@@ -189,7 +203,7 @@ Compression is lossless via CCR (Compress-Cache-Retrieve): originals are stored
 | `autoStart` | `true` | Auto-start a local `headroom proxy` if not already running (local URLs only; ignored for remote proxies) |
 | `startupTimeoutMs` | `20000` | Time to wait for auto-started proxy to become healthy |
 | `routeCodexViaProxy` | `true` | Rewrite OpenClaw's built-in `openai-codex` provider to use the active Headroom proxy in memory so upstream Codex requests pass through Headroom. |
-| `gatewayProviderIds` | `[]` | Optional explicit list of OpenClaw provider ids to route through the active Headroom proxy in memory. When set, this overrides the default `openai-codex` routing list. |
+| `gatewayProviderIds` | `[]` | Optional explicit list of OpenClaw provider ids to route through the active Headroom proxy in memory. Friendly aliases `codex`, `claude`, `copilot`, and `gemini` are also accepted. When set, this overrides the default `openai-codex` routing list. |
 
 ## Comparison with lossless-claw
 

plugins/openclaw/openclaw.plugin.json

@@ -28,7 +28,7 @@
     },
     "gatewayProviderIds": {
       "label": "Gateway Provider IDs",
-      "help": "Optional list of OpenClaw provider ids to route through the active Headroom proxy in memory. When set, this overrides the default openai-codex-only routing."
+      "help": "Optional list of OpenClaw provider ids to route through the active Headroom proxy in memory. Friendly aliases codex, claude, copilot, and gemini are also accepted. When set, this overrides the default openai-codex-only routing."
     }
   },
   "configSchema": {

plugins/openclaw/src/gateway-config.ts

@@ -6,6 +6,15 @@ const DEFAULT_PROVIDER_BASE_URLS: Readonly<Record<string, string>> = {
   "openai-codex": "https://chatgpt.com/backend-api",
 };
 
+const GATEWAY_PROVIDER_ID_ALIASES: Readonly<Record<string, string>> = {
+  codex: "openai-codex",
+  claude: "anthropic",
+  copilot: "github-copilot",
+  gemini: "google",
+};
+
+const EXPLICIT_BASE_URL_REQUIRED_PROVIDER_IDS = new Set<string>(["github-copilot"]);
+
 export function resolveGatewayProviderIds(config: Record<string, unknown> | undefined): string[] {
   const configuredProviderIds = normalizeGatewayProviderIds(config?.gatewayProviderIds);
   if (configuredProviderIds.length > 0) {
@@ -32,7 +41,8 @@ function normalizeGatewayProviderIds(value: unknown): string[] {
       continue;
     }
 
-    const providerId = entry.trim();
+    const rawProviderId = entry.trim();
+    const providerId = GATEWAY_PROVIDER_ID_ALIASES[rawProviderId.toLowerCase()] ?? rawProviderId;
     if (!providerId || seen.has(providerId)) {
       continue;
     }
@@ -74,13 +84,22 @@ export function applyGatewayProviderBaseUrlsInPlace(
         ? currentValue
         : {};
     const nextConfig = { ...currentConfig };
+    const currentBaseUrl =
+      typeof nextConfig.baseUrl === "string" && nextConfig.baseUrl.trim().length > 0
+        ? nextConfig.baseUrl
+        : undefined;
+    const defaultBaseUrl = DEFAULT_PROVIDER_BASE_URLS[providerId];
+    if (
+      !currentBaseUrl &&
+      !defaultBaseUrl &&
+      EXPLICIT_BASE_URL_REQUIRED_PROVIDER_IDS.has(providerId)
+    ) {
+      continue;
+    }
     const nextBaseUrl = routeBaseUrlThroughProxy({
       providerId,
       proxyUrl,
-      currentBaseUrl:
-        typeof nextConfig.baseUrl === "string" && nextConfig.baseUrl.trim().length > 0
-          ? nextConfig.baseUrl
-          : undefined,
+      currentBaseUrl,
     });
 
     if (!Array.isArray(nextConfig.models)) {

plugins/openclaw/test/gateway-config.test.ts

@@ -13,17 +13,17 @@ describe("resolveGatewayProviderIds", () => {
   it("allows an explicit provider list to override the default", () => {
     expect(
       resolveGatewayProviderIds({
-        gatewayProviderIds: ["anthropic", "copilot", "minimax-portal"],
+        gatewayProviderIds: ["anthropic", "github-copilot", "minimax-portal"],
       }),
-    ).toEqual(["anthropic", "copilot", "minimax-portal"]);
+    ).toEqual(["anthropic", "github-copilot", "minimax-portal"]);
   });
 
-  it("normalizes explicit provider ids", () => {
+  it("normalizes explicit provider ids and friendly aliases", () => {
     expect(
       resolveGatewayProviderIds({
-        gatewayProviderIds: [" anthropic ", "", "copilot", "anthropic"],
+        gatewayProviderIds: [" claude ", "", "copilot", "codex", "gemini", "anthropic"],
       }),
-    ).toEqual(["anthropic", "copilot"]);
+    ).toEqual(["anthropic", "github-copilot", "openai-codex", "google"]);
   });
 
   it("allows routing to be disabled", () => {
@@ -46,7 +46,7 @@ describe("applyGatewayProviderBaseUrls", () => {
     const result = applyGatewayProviderBaseUrls(
       {},
       "http://127.0.0.1:8787",
-      ["anthropic", "copilot", "minimax-portal"],
+      ["anthropic", "openrouter", "google", "minimax-portal"],
     );
 
     expect(result.changed).toBe(true);
@@ -55,7 +55,11 @@ describe("applyGatewayProviderBaseUrls", () => {
         baseUrl: "http://127.0.0.1:8787",
         models: [],
       },
-      copilot: {
+      openrouter: {
+        baseUrl: "http://127.0.0.1:8787",
+        models: [],
+      },
+      google: {
         baseUrl: "http://127.0.0.1:8787",
         models: [],
       },
@@ -129,6 +133,101 @@ describe("applyGatewayProviderBaseUrls", () => {
       models: [],
     });
   });
+
+  it("preserves protocol-specific GitHub Copilot OpenAI-family paths", () => {
+    const result = applyGatewayProviderBaseUrls(
+      {
+        models: {
+          providers: {
+            "github-copilot": {
+              baseUrl: "https://api.githubcopilot.com/v1",
+            },
+          },
+        },
+      },
+      "http://127.0.0.1:8787",
+      ["github-copilot"],
+    );
+
+    expect(result.changed).toBe(true);
+    expect((result.config as any).models.providers["github-copilot"]).toEqual({
+      baseUrl: "http://127.0.0.1:8787/v1",
+      models: [],
+    });
+  });
+
+  it("preserves protocol-specific GitHub Copilot Claude-family paths", () => {
+    const result = applyGatewayProviderBaseUrls(
+      {
+        models: {
+          providers: {
+            "github-copilot": {
+              baseUrl: "https://api.githubcopilot.com/anthropic",
+            },
+          },
+        },
+      },
+      "http://127.0.0.1:8787",
+      ["github-copilot"],
+    );
+
+    expect(result.changed).toBe(true);
+    expect((result.config as any).models.providers["github-copilot"]).toEqual({
+      baseUrl: "http://127.0.0.1:8787/anthropic",
+      models: [],
+    });
+  });
+
+  it("preserves OpenAI-compatible /api/v1 paths", () => {
+    const result = applyGatewayProviderBaseUrls(
+      {
+        models: {
+          providers: {
+            openrouter: {
+              baseUrl: "https://openrouter.ai/api/v1",
+            },
+          },
+        },
+      },
+      "http://127.0.0.1:8787",
+      ["openrouter"],
+    );
+
+    expect(result.changed).toBe(true);
+    expect((result.config as any).models.providers.openrouter).toEqual({
+      baseUrl: "http://127.0.0.1:8787/api/v1",
+      models: [],
+    });
+  });
+
+  it("preserves Gemini /v1beta paths", () => {
+    const result = applyGatewayProviderBaseUrls(
+      {
+        models: {
+          providers: {
+            google: {
+              baseUrl: "https://generativelanguage.googleapis.com/v1beta",
+            },
+          },
+        },
+      },
+      "http://127.0.0.1:8787",
+      ["google"],
+    );
+
+    expect(result.changed).toBe(true);
+    expect((result.config as any).models.providers.google).toEqual({
+      baseUrl: "http://127.0.0.1:8787/v1beta",
+      models: [],
+    });
+  });
+
+  it("does not invent a GitHub Copilot proxy baseUrl without an upstream baseUrl", () => {
+    const result = applyGatewayProviderBaseUrls({}, "http://127.0.0.1:8787", ["github-copilot"]);
+
+    expect(result.changed).toBe(false);
+    expect((result.config as any).models?.providers?.["github-copilot"]).toBeUndefined();
+  });
 });
 
 describe("applyGatewayProviderBaseUrlsInPlace", () => {

plugins/openclaw/test/plugin-runtime-routing.test.ts

@@ -55,7 +55,7 @@ describe("headroomPlugin runtime routing", () => {
           entries: {
             headroom: {
               config: {
-                gatewayProviderIds: ["openai-codex", "anthropic", "github-copilot"],
+                gatewayProviderIds: ["codex", "claude", "copilot", "gemini", "openrouter"],
               },
             },
           },
@@ -64,6 +64,16 @@ describe("headroomPlugin runtime routing", () => {
           providers: {
             anthropic: {
               api: "anthropic-messages",
+              baseUrl: "https://api.anthropic.com",
+            },
+            "github-copilot": {
+              baseUrl: "https://api.githubcopilot.com/v1",
+            },
+            google: {
+              baseUrl: "https://generativelanguage.googleapis.com/v1beta",
+            },
+            openrouter: {
+              baseUrl: "https://openrouter.ai/api/v1",
             },
           },
         },
@@ -108,7 +118,15 @@ describe("headroomPlugin runtime routing", () => {
       models: [],
     });
     expect(api.config.models.providers["github-copilot"]).toEqual({
-      baseUrl: "http://127.0.0.1:8787",
+      baseUrl: "http://127.0.0.1:8787/v1",
+      models: [],
+    });
+    expect(api.config.models.providers.google).toEqual({
+      baseUrl: "http://127.0.0.1:8787/v1beta",
+      models: [],
+    });
+    expect(api.config.models.providers.openrouter).toEqual({
+      baseUrl: "http://127.0.0.1:8787/api/v1",
       models: [],
     });