fix: allow private network provider request opt-in (openclaw#63671)

* feat(models): allow private network via models.providers.*.request
Add optional request.allowPrivateNetwork for operator-controlled self-hosted
OpenAI-compatible bases (LAN/overlay/split DNS). Plumbs the flag into
resolveProviderRequestPolicyConfig for streaming provider HTTP and OpenAI
responses WebSocket so SSRF policy can allow private-resolved model URLs
when explicitly enabled.
Updates zod schema, config help/labels, and unit tests for sanitize/merge.

* agents thread provider request into websocket stream

* fix(config): scope allowPrivateNetwork to model requests

* fix(agents): refresh websocket manager on request changes

* fix(agents): scope runtime private-network overrides to models

* fix: allow private network provider request opt-in (openclaw#63671) (thanks @qas)

---------

Co-authored-by: Ayaan Zaidi <hi@obviy.us>

Author: qas

CHANGELOG.md

@@ -11,6 +11,7 @@ Docs: https://docs.openclaw.ai
 - Docs i18n: chunk raw doc translation, reject truncated tagged outputs, avoid ambiguous body-only wrapper unwrapping, and recover from terminated Pi translation sessions without changing the default `openai/gpt-5.4` path. (#62969, #63808) Thanks @hxy91819.
 - QA/testing: add a `--runner multipass` lane for `openclaw qa suite` so repo-backed QA scenarios can run inside a disposable Linux VM and write back the usual report, summary, and VM logs. (#63426) Thanks @shakkernerd.
 - Gateway: split startup and runtime seams so gateway lifecycle sequencing, reload state, and shutdown behavior stay easier to maintain without changing observed behavior. (#63975) Thanks @gumadeiras.
+- Models/providers: add per-provider `models.providers.*.request.allowPrivateNetwork` for trusted self-hosted OpenAI-compatible endpoints, keep the opt-in scoped to model request surfaces, and refresh cached WebSocket managers when request transport overrides change. (#63671) Thanks @qas.
 
 ### Fixes
 

docs/gateway/configuration-reference.md

@@ -2402,6 +2402,7 @@ OpenClaw uses the built-in model catalog. Add custom providers via `models.provi
   - `request.auth`: auth strategy override. Modes: `"provider-default"` (use provider's built-in auth), `"authorization-bearer"` (with `token`), `"header"` (with `headerName`, `value`, optional `prefix`).
   - `request.proxy`: HTTP proxy override. Modes: `"env-proxy"` (use `HTTP_PROXY`/`HTTPS_PROXY` env vars), `"explicit-proxy"` (with `url`). Both modes accept an optional `tls` sub-object.
   - `request.tls`: TLS override for direct connections. Fields: `ca`, `cert`, `key`, `passphrase` (all accept SecretRef), `serverName`, `insecureSkipVerify`.
+  - `request.allowPrivateNetwork`: when `true`, allow HTTPS to `baseUrl` when DNS resolves to private, CGNAT, or similar ranges, via the provider HTTP fetch guard (operator opt-in for trusted self-hosted OpenAI-compatible endpoints). WebSocket uses the same `request` for headers/TLS but not that fetch SSRF gate. Default `false`.
 - `models.providers.*.models`: explicit provider model catalog entries.
 - `models.providers.*.models.*.contextWindow`: native model context window metadata.
 - `models.providers.*.models.*.contextTokens`: optional runtime context cap. Use this when you want a smaller effective context budget than the model's native `contextWindow`.

src/agents/openai-ws-connection.ts

@@ -19,7 +19,7 @@ import { buildOpenAIWebSocketWarmUpPayload } from "./openai-ws-request.js";
 import {
   buildProviderRequestTlsClientOptions,
   resolveProviderRequestPolicyConfig,
-  type ProviderRequestTransportOverrides,
+  type ModelProviderRequestTransportOverrides,
 } from "./provider-request-config.js";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -289,7 +289,7 @@ export interface OpenAIWebSocketManagerOptions {
   /** Extra headers merged into the initial WebSocket handshake request. */
   headers?: Record<string, string>;
   /** Optional transport overrides for provider-owned auth or TLS wiring. */
-  request?: ProviderRequestTransportOverrides;
+  request?: ModelProviderRequestTransportOverrides;
 }
 
 export type OpenAIWebSocketConnectionState =
@@ -346,7 +346,7 @@ export class OpenAIWebSocketManager extends EventEmitter<InternalEvents> {
   private readonly backoffDelaysMs: readonly number[];
   private readonly socketFactory: (url: string, options: ClientOptions) => WebSocket;
   private readonly headers?: Record<string, string>;
-  private readonly request?: ProviderRequestTransportOverrides;
+  private readonly request?: ModelProviderRequestTransportOverrides;
 
   constructor(options: OpenAIWebSocketManagerOptions = {}) {
     super();
@@ -467,6 +467,7 @@ export class OpenAIWebSocketManager extends EventEmitter<InternalEvents> {
         },
         precedence: "defaults-win",
         request: this.request,
+        allowPrivateNetwork: this.request?.allowPrivateNetwork === true,
       });
       const socket = this.socketFactory(this.wsUrl, {
         headers: requestConfig.headers,

src/agents/openai-ws-stream.test.ts

@@ -3428,6 +3428,87 @@ describe("releaseWsSession / hasWsSession", () => {
   it("releaseWsSession is a no-op for unknown sessions", () => {
     expect(() => releaseWsSession("nonexistent-session")).not.toThrow();
   });
+
+  it("recreates the cached manager when request overrides change for the same session", async () => {
+    const sessionId = "registry-test";
+    const firstStreamFn = createOpenAIWebSocketStreamFn("sk-test", sessionId, {
+      managerOptions: {
+        request: {
+          headers: { "x-test": "one" },
+        },
+      },
+    });
+    const firstStream = firstStreamFn(
+      {
+        api: "openai-responses",
+        provider: "openai",
+        id: "gpt-5.4",
+        contextWindow: 128000,
+        maxTokens: 4096,
+        reasoning: false,
+        input: ["text"],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        name: "GPT-5.4",
+      } as Parameters<typeof firstStreamFn>[0],
+      {
+        systemPrompt: "test",
+        messages: [userMsg("Hi") as Parameters<typeof convertMessagesToInputItems>[0][number]],
+        tools: [],
+      } as Parameters<typeof firstStreamFn>[1],
+    );
+
+    await new Promise((r) => setImmediate(r));
+    const firstManager = MockManager.lastInstance!;
+    firstManager.simulateEvent({
+      type: "response.completed",
+      response: makeResponseObject("resp-first", "done"),
+    });
+    for await (const _ of await resolveStream(firstStream)) {
+      // consume
+    }
+
+    const secondStreamFn = createOpenAIWebSocketStreamFn("sk-test", sessionId, {
+      managerOptions: {
+        request: {
+          headers: { "x-test": "two" },
+          allowPrivateNetwork: true,
+        },
+      },
+    });
+    const secondStream = secondStreamFn(
+      {
+        api: "openai-responses",
+        provider: "openai",
+        id: "gpt-5.4",
+        contextWindow: 128000,
+        maxTokens: 4096,
+        reasoning: false,
+        input: ["text"],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        name: "GPT-5.4",
+      } as Parameters<typeof secondStreamFn>[0],
+      {
+        systemPrompt: "test",
+        messages: [userMsg("Again") as Parameters<typeof convertMessagesToInputItems>[0][number]],
+        tools: [],
+      } as Parameters<typeof secondStreamFn>[1],
+    );
+
+    await new Promise((r) => setImmediate(r));
+    expect(MockManager.instances).toHaveLength(2);
+    expect(firstManager.closeCallCount).toBe(1);
+    const secondManager = MockManager.lastInstance!;
+    expect(secondManager).not.toBe(firstManager);
+    expect(secondManager.connectCallCount).toBe(1);
+
+    secondManager.simulateEvent({
+      type: "response.completed",
+      response: makeResponseObject("resp-second", "done"),
+    });
+    for await (const _ of await resolveStream(secondStream)) {
+      // consume
+    }
+  });
 });
 
 describe("convertMessagesToInputItems — phase inheritance", () => {

src/agents/openai-ws-stream.ts

@@ -71,6 +71,7 @@ import { mergeTransportMetadata } from "./transport-stream-shared.js";
 
 interface WsSession {
   manager: OpenAIWebSocketManager;
+  managerConfigSignature: string;
   /** Number of messages that were in context.messages at the END of the last streamFn call. */
   lastContextLength: number;
   /** True if the connection has been established at least once. */
@@ -336,6 +337,30 @@ function createWsManager(
   });
 }
 
+function stringifyStable(value: unknown): string {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => stringifyStable(entry)).join(",")}]`;
+  }
+  const entries = Object.entries(value).toSorted(([left], [right]) => left.localeCompare(right));
+  return `{${entries
+    .map(([key, entry]) => `${JSON.stringify(key)}:${stringifyStable(entry)}`)
+    .join(",")}}`;
+}
+
+function resolveWsManagerConfigSignature(
+  managerOptions: OpenAIWebSocketManagerOptions | undefined,
+  sessionHeaders?: Record<string, string>,
+): string {
+  return stringifyStable({
+    headers: sessionHeaders,
+    request: managerOptions?.request,
+    url: managerOptions?.url,
+  });
+}
+
 const AZURE_OPENAI_PROVIDER_IDS = new Set(["azure-openai", "azure-openai-responses"]);
 const OPENAI_CODEX_PROVIDER_ID = "openai-codex";
 
@@ -661,10 +686,15 @@ export function createOpenAIWebSocketStreamFn(
 
       while (true) {
         let session = wsRegistry.get(sessionId);
+        const managerConfigSignature = resolveWsManagerConfigSignature(
+          opts.managerOptions,
+          sessionHeaders,
+        );
         if (!session) {
           const manager = createWsManager(opts.managerOptions, sessionHeaders);
           session = {
             manager,
+            managerConfigSignature,
             lastContextLength: 0,
             everConnected: false,
             warmUpAttempted: false,
@@ -673,6 +703,13 @@ export function createOpenAIWebSocketStreamFn(
             degradeCooldownMs: wsSessionPolicy.degradeCooldownMs,
           };
           wsRegistry.set(sessionId, session);
+        } else if (session.managerConfigSignature !== managerConfigSignature) {
+          resetWsSession({
+            session,
+            createManager: () => createWsManager(opts.managerOptions, sessionHeaders),
+          });
+          session.managerConfigSignature = managerConfigSignature;
+          session.degradeCooldownMs = wsSessionPolicy.degradeCooldownMs;
         }
 
         if (transport !== "websocket" && isWsSessionDegraded(session)) {

src/agents/pi-embedded-runner/stream-resolution.ts

@@ -2,6 +2,7 @@ import type { StreamFn } from "@mariozechner/pi-agent-core";
 import { streamSimple } from "@mariozechner/pi-ai";
 import { createAnthropicVertexStreamFnForModel } from "../anthropic-vertex-stream.js";
 import { createOpenAIWebSocketStreamFn } from "../openai-ws-stream.js";
+import { getModelProviderRequestTransport } from "../provider-request-config.js";
 import { createBoundaryAwareStreamFnForModel } from "../provider-transport-stream.js";
 import { stripSystemPromptCacheBoundary } from "../system-prompt-cache-boundary.js";
 import type { EmbeddedRunAttemptParams } from "./run/types.js";
@@ -105,6 +106,9 @@ export function resolveEmbeddedAgentStreamFn(params: {
     return params.wsApiKey
       ? createOpenAIWebSocketStreamFn(params.wsApiKey, params.sessionId, {
           signal: params.signal,
+          managerOptions: {
+            request: getModelProviderRequestTransport(params.model),
+          },
         })
       : currentStreamFn;
   }

src/agents/provider-request-config.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest";
 import {
   buildProviderRequestDispatcherPolicy,
+  mergeModelProviderRequestOverrides,
   mergeProviderRequestOverrides,
   resolveProviderRequestPolicyConfig,
   resolveProviderRequestConfig,
@@ -9,6 +10,7 @@ import {
   sanitizeConfiguredProviderRequest,
   sanitizeRuntimeProviderRequestOverrides,
 } from "./provider-request-config.js";
+import type { ProviderRequestTransportOverrides } from "./provider-request-config.js";
 
 describe("provider request config", () => {
   it("merges discovered, provider, and model headers in precedence order", () => {
@@ -332,6 +334,35 @@ describe("provider request config", () => {
     });
   });
 
+  it("preserves request.allowPrivateNetwork for operator-trusted LAN/overlay model bases", () => {
+    expect(sanitizeConfiguredModelProviderRequest({ allowPrivateNetwork: true })).toEqual({
+      allowPrivateNetwork: true,
+    });
+    expect(sanitizeConfiguredModelProviderRequest({ allowPrivateNetwork: false })).toEqual({
+      allowPrivateNetwork: false,
+    });
+    expect(
+      sanitizeConfiguredProviderRequest({
+        allowPrivateNetwork: true,
+      } as ProviderRequestTransportOverrides),
+    ).toBeUndefined();
+  });
+
+  it("merges allowPrivateNetwork with later override winning", () => {
+    expect(
+      mergeModelProviderRequestOverrides(
+        { allowPrivateNetwork: true },
+        { allowPrivateNetwork: false },
+      ),
+    ).toEqual({ allowPrivateNetwork: false });
+    expect(
+      mergeModelProviderRequestOverrides(
+        { allowPrivateNetwork: false },
+        { allowPrivateNetwork: true },
+      ),
+    ).toEqual({ allowPrivateNetwork: true });
+  });
+
   it("merges configured request overrides with later entries winning", () => {
     expect(
       mergeProviderRequestOverrides(

src/agents/provider-request-config.ts

@@ -59,6 +59,10 @@ export type ProviderRequestTransportOverrides = {
   tls?: ProviderRequestTlsOverride;
 };
 
+export type ModelProviderRequestTransportOverrides = ProviderRequestTransportOverrides & {
+  allowPrivateNetwork?: boolean;
+};
+
 export type ResolvedProviderRequestAuthConfig =
   | {
       configured: false;
@@ -158,7 +162,7 @@ type ResolveProviderRequestPolicyConfigParams = {
   } | null;
   modelId?: string | null;
   allowPrivateNetwork?: boolean;
-  request?: ProviderRequestTransportOverrides;
+  request?: ModelProviderRequestTransportOverrides;
 };
 
 function sanitizeConfiguredRequestString(value: unknown, path: string): string | undefined {
@@ -173,7 +177,7 @@ function sanitizeConfiguredRequestString(value: unknown, path: string): string |
 }
 
 export function sanitizeConfiguredProviderRequest(
-  request: ConfiguredModelProviderRequest | ProviderRequestTransportOverrides | undefined,
+  request: ProviderRequestTransportOverrides | undefined,
 ): ProviderRequestTransportOverrides | undefined {
   if (!request || typeof request !== "object" || Array.isArray(request)) {
     return undefined;
@@ -300,8 +304,17 @@ export function sanitizeConfiguredProviderRequest(
 
 export function sanitizeConfiguredModelProviderRequest(
   request: ConfiguredModelProviderRequest | undefined,
-): ProviderRequestTransportOverrides | undefined {
-  return sanitizeConfiguredProviderRequest(request);
+): ModelProviderRequestTransportOverrides | undefined {
+  const sanitized = sanitizeConfiguredProviderRequest(request);
+  const rawAllow = request?.allowPrivateNetwork;
+  const allowPrivateNetwork = rawAllow === true ? true : rawAllow === false ? false : undefined;
+  if (!sanitized && allowPrivateNetwork === undefined) {
+    return undefined;
+  }
+  return {
+    ...sanitized,
+    ...(allowPrivateNetwork !== undefined ? { allowPrivateNetwork } : {}),
+  };
 }
 
 export function mergeProviderRequestOverrides(
@@ -325,11 +338,29 @@ export function mergeProviderRequestOverrides(
       ...(current.auth ? { auth: current.auth } : {}),
       ...(current.proxy ? { proxy: current.proxy } : {}),
       ...(current.tls ? { tls: current.tls } : {}),
+      ...(current.allowPrivateNetwork !== undefined
+        ? { allowPrivateNetwork: current.allowPrivateNetwork }
+        : {}),
     };
   }
   return merged;
 }
 
+export function mergeModelProviderRequestOverrides(
+  ...overrides: Array<ModelProviderRequestTransportOverrides | undefined>
+): ModelProviderRequestTransportOverrides | undefined {
+  let merged = mergeProviderRequestOverrides(...overrides);
+  for (const current of overrides) {
+    if (current?.allowPrivateNetwork !== undefined) {
+      merged = {
+        ...merged,
+        allowPrivateNetwork: current.allowPrivateNetwork,
+      };
+    }
+  }
+  return merged;
+}
+
 export function normalizeBaseUrl(baseUrl: string | undefined, fallback: string): string;
 export function normalizeBaseUrl(
   baseUrl: string | undefined,
@@ -691,12 +722,12 @@ const MODEL_PROVIDER_REQUEST_TRANSPORT_SYMBOL = Symbol.for(
 );
 
 type ModelWithProviderRequestTransport = {
-  [MODEL_PROVIDER_REQUEST_TRANSPORT_SYMBOL]?: ProviderRequestTransportOverrides;
+  [MODEL_PROVIDER_REQUEST_TRANSPORT_SYMBOL]?: ModelProviderRequestTransportOverrides;
 };
 
 export function attachModelProviderRequestTransport<TModel extends object>(
   model: TModel,
-  request: ProviderRequestTransportOverrides | undefined,
+  request: ModelProviderRequestTransportOverrides | undefined,
 ): TModel {
   if (!request) {
     return model;
@@ -708,6 +739,6 @@ export function attachModelProviderRequestTransport<TModel extends object>(
 
 export function getModelProviderRequestTransport(
   model: object,
-): ProviderRequestTransportOverrides | undefined {
+): ModelProviderRequestTransportOverrides | undefined {
   return (model as ModelWithProviderRequestTransport)[MODEL_PROVIDER_REQUEST_TRANSPORT_SYMBOL];
 }

src/agents/provider-transport-fetch.ts

@@ -55,13 +55,15 @@ function buildManagedResponse(response: Response, release: () => Promise<void>):
 }
 
 function resolveModelRequestPolicy(model: Model<Api>) {
+  const request = getModelProviderRequestTransport(model);
   return resolveProviderRequestPolicyConfig({
     provider: model.provider,
     api: model.api,
     baseUrl: model.baseUrl,
     capability: "llm",
     transport: "stream",
-    request: getModelProviderRequestTransport(model),
+    request,
+    allowPrivateNetwork: request?.allowPrivateNetwork === true,
   });
 }