Problem

When running OpenClaw behind an identity-aware reverse proxy (auth.mode: trusted-proxy), the local CLI and spawned sub-agents cannot authenticate because:

1. They connect from 127.0.0.1, which is in trustedProxies
2. But they cannot inject the userHeader (e.g. X-Auth-Request-Email) that the trusted-proxy auth check requires
3. The trusted-proxy auth handler does an early return with no fallback, so token auth is not tried

This means sessions_spawn and other sub-agent features are completely broken when using trusted-proxy mode, even though the gateway is running locally.

A proxy shim (injecting the header on loopback) also doesn't work because the gateway dynamically sets OPENCLAW_GATEWAY_PORT for child processes to its own listening port, causing sub-agents to connect directly to the gateway and bypass the proxy.

Proposed Solution

Add an optional trustedProxy.loopbackUser config field. When a connection arrives from a loopback address (127.0.0.1 / ::1) in trustedProxies without the user header, fall back to this identity instead of rejecting:

{
  gateway: {
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "X-Auth-Request-Email",
        loopbackUser: "derek@example.com", // used when no header present from loopback
        allowUsers: ["derek@example.com"]
      }
    }
  }
}

Why This Is Safe

• Only applies to connections from loopback addresses already in trustedProxies
• The identity is explicitly configured by the operator (not attacker-controlled)
• Loopback access already implies full local machine access
• Does not weaken external auth at all -- the proxy still handles all non-loopback connections

Current Workaround

auth.mode: "none" -- loses per-user identity tracking entirely.

Environment

• Gateway bind: lan
• Auth mode: trusted-proxy with nginx + oauth2-proxy
• Use case: home lab, single-user, CLI and sub-agents running on same host as gateway