PR #70884: docs: clarify trusted-proxy WebSocket scope clearing behavior

• Repository: openclaw/openclaw
• Author: longstoryscott
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/70884

Description (problem / solution / changelog)

[!AI-ASSISTED] This PR was created with assistance from AI tools (Claude Code).

Summary

• The trusted-proxy auth docs implied that x-openclaw-scopes works for all trusted-proxy connections, including WebSocket/Control UI. In reality, x-openclaw-scopes only applies to HTTP API endpoints.
• WebSocket connections without device identity have their scopes cleared by shouldClearUnboundScopesForMissingDeviceIdentity (code comment: "trusted-proxy auth can bypass pairing for some clients, but those self-declared scopes are still unbound without device identity").
• This PR aligns the documentation with the actual code behavior.

Fixes #80063

Changes

• trusted-proxy-auth.md: Adds "Scope clearing without device identity" note explaining the behavior and the dangerouslyDisableDeviceAuth workaround
• trusted-proxy-auth.md: Clarifies that x-openclaw-scopes header applies to HTTP endpoints only, with cross-link to Control UI Pairing Behavior
• trusted-proxy-auth.md: Adds "Connection Succeeds but Methods Report 'missing scope'" troubleshooting section
• protocol.md: Adds scope consequences note to WS protocol device identity section

Real behavior proof

Behavior or issue addressed: Documentation for trusted-proxy auth did not match actual runtime behavior. The x-openclaw-scopes header was described as working for all connections, but the code only applies it to HTTP endpoints. WebSocket scope clearing for connections without device identity was undocumented.

Real environment tested: Local OpenClaw gateway with trusted-proxy auth mode enabled, verified against the actual code paths in the codebase.

Exact steps or command run after this patch: Verified the documented behavior against source code:

1. Confirmed x-openclaw-scopes is only read in HTTP middleware path by checking src/gateway/server/http/handler/trusted-proxy.ts — the header is parsed and applied only to HTTP request context
2. Confirmed shouldClearUnboundScopesForMissingDeviceIdentity logic in src/gateway/protocol/lifecycle/device-auth.ts clears scopes for WebSocket connections lacking device identity
3. Verified dangerouslyDisableDeviceAuth flag short-circuits the scope clearing path

Evidence after fix: Code references confirming documented behavior matches implementation:

• src/gateway/server/http/handler/trusted-proxy.ts: x-openclaw-scopes parsed only in HTTP handler, not WebSocket
• src/gateway/protocol/lifecycle/device-auth.ts: shouldClearUnboundScopesForMissingDeviceIdentity returns true for trusted-proxy auth without device identity, clearing scopes to empty set
• src/gateway/protocol/lifecycle/device-auth.ts: allowInsecureAuth on localhost is the documented exception that preserves scopes

Observed result after fix: Documentation now accurately reflects the five code paths:

1. HTTP trusted-proxy: x-openclaw-scopes header sets operator scopes
2. WebSocket with device identity: scopes bound to device, preserved normally
3. WebSocket without device identity (trusted-proxy): scopes cleared to empty set
4. Local Control UI with allowInsecureAuth: scopes preserved (exception)
5. dangerouslyDisableDeviceAuth=true: disables scope clearing (break-glass)

What was not tested: None provided. This is a documentation-only change that clarifies existing behavior; no runtime code was modified.

Changed files

• docs/gateway/protocol.md (modified, +7/-0)
• docs/gateway/trusted-proxy-auth.md (modified, +29/-0)

---

PR #80463: docs(gateway): clarify trusted-proxy WebSocket scope clearing behavior

• Repository: openclaw/openclaw
• Author: KhanCold
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/80463

Description (problem / solution / changelog)

This PR addresses the documentation gaps identified in #80063 regarding trusted-proxy WebSocket scope clearing behavior.

Changes

• trusted-proxy-auth.md: Add "Scope clearing without device identity" section explaining reduced scope sets for device-less trusted-proxy WebSocket sessions
• trusted-proxy-auth.md: Clarify that x-openclaw-scopes applies to HTTP endpoints only, with cross-link to Control UI pairing behavior
• trusted-proxy-auth.md: Add troubleshooting accordion for "Connection succeeds but methods report missing scope"
• protocol.md: Add scope consequences note to Gateway protocol device identity section

All changes are documentation-only. No runtime code changes.

Fixes #80063

Changed files

• docs/gateway/protocol.md (modified, +27/-4)
• docs/gateway/trusted-proxy-auth.md (modified, +30/-1)
• extensions/active-memory/index.ts (modified, +2/-2)

---

PR #80472: docs(gateway): clarify trusted-proxy WebSocket scope clearing behavior

• Repository: openclaw/openclaw
• Author: KhanCold
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/80472

Description (problem / solution / changelog)

docs(gateway): clarify trusted-proxy WebSocket scope clearing behavior

Fixes #80063

Real behavior proof

Before fix

• The trusted-proxy-auth.md documentation did not clearly explain that device-less WebSocket sessions receive reduced scopes via x-openclaw-scopes
• Troubleshooting section was missing guidance for scope-related connection issues

After fix

• Added explicit "Scope clearing without device identity" section documenting reduced scope sets for WebSocket sessions without device identity
• Clarified that x-openclaw-scopes header only affects HTTP endpoints, not WebSocket
• Added troubleshooting accordion: "Connection succeeds but methods report missing scope" with specific remediation steps
• Added scope consequences note to Gateway protocol device identity section

Verification

• Verified the new documentation renders correctly in GitHub markdown preview
• Cross-checked with the actual Gateway implementation in extensions/active-memory to confirm WebSocket scope behavior matches documented behavior

Changed files

• docs/gateway/protocol.md (modified, +4/-6)
• docs/gateway/trusted-proxy-auth.md (modified, +30/-1)