Type: Documentation / Developer Experience (DX) / Bug?
OpenClaw Version: 2026.1.30

Context

During a manual setup of OpenClaw on Windows 11 using a WSL2 (Ubuntu) backend, we encountered several friction points that might discourage or confuse new users.

Friction Points

1. Strict gateway.bind Validation

The CLI schema validation (Zod) specifically rejects IP literals like 127.0.0.1 or 0.0.0.0 in favor of loopback or lan.

• Observed Error: Invalid config at ~/.openclaw/openclaw.json: - gateway.bind: Invalid input
• Expected Behavior: Allow standard IP literals or provide a more descriptive error message within the CLI itself explaining the move to logical identifiers (loopback/lan). Forcing logical identifiers breaks the "standard" dev-environment setup flow.

2. Configuration Schema for agents.defaults.model

Manual configuration of the agent model often leads to a failure if a string is provided instead of the required object structure.

• Requirement: { "agents": { "defaults": { "model": { "primary": "model-id" } } } }
• Confusion: Many users expect a top-level string for simplicity. The error message when this is missing is not always intuitive regarding the nested structure required.

3. "Device Identity Required" on WSL2/LAN access

Accessing the Control UI via a LAN IP (standard for WSL2 users who can't use localhost across the bridge easily) triggers a security context check that requires WebCrypto.

• Impact: Browser blocks identity generation over insecure (non-HTTPS) LAN IPs, leading to a persistent "device identity required" error.
• Suggestion:
  • Add a first-class hint in the openclaw status or logs when gateway.bind: lan is detected, warning user about the insecure context and suggesting ?token=... or allowInsecureAuth: true.
  • Improve documentation regarding the "WSL2 -> Windows Host" networking bridge which often forces a non-localhost access.

4. RAM Management / Ollama Failures

When running local models (e.g., Llama 3.2 3B) on machines with limited RAM (e.g., 16GB total), Ollama can fail silently or allocate too much memory.

• Mitigation used: We created a custom model with reduced num_ctx (4096) and num_predict (2048) to fit within a ~13 GiB free RAM window.
• Suggestion: Provide a "Low RAM" optimization preset or documentation for Ollama-based local setups.

Proposed Resolution

• Relax Zod schema for gateway.bind to accept common IP literals.
• Update openclaw doctor to check for secure contexts when bound to lan.
• Update onboarding docs with a "WSL2 Guide".