Primary Manifestation

Executing openclaw approvals get --gateway produces truncated output with a misleading health status:

$ openclaw approvals get --gateway
gateway timeout after 10000ms
...
Effective Policy -> Config unavailable.
[Command exits with non-zero status]

Secondary Manifestations

• Exit code: Non-zero (typically 124 indicating timeout, or 1 for general error)
• Timing: Command fails between 10s and 11s from invocation
• Partial output: Approvals snapshot data may appear before the timeout failure
• Effective Policy section: Renders as literal text Config unavailable. instead of actual policy data

Gateway Health Confirms Misleading Report

$ openclaw gateway status
Runtime:     running
RPC Probe:   ok
Version:     2026.4.12
Last Check:  2026-04-15T10:30:00Z

Successful Execution with Extended Timeout

$ openclaw approvals get --gateway --timeout 60000
gateway: healthy
runtime: running
...
Effective Policy -> orion: approved, admin: approved
[Command exits 0]

Sequential RPC Call Pattern

The openclaw approvals get --gateway command executes two distinct RPC calls in sequence:

1. Call 1: Approvals Snapshot (approvals.get_snapshot)
   • Fetches the complete approvals dataset
   • Typically completes in 50-500ms on healthy networks
   • Successfully populates the primary output table
2. Call 2: Gateway Config (config.get)
   • Fetches gateway configuration for Effective Policy rendering
   • Required for the Effective Policy column in output
   • On low-spec hosts, this call can take 30-45 seconds

Timeout Handling Architecture

// Pseudocode representation of CLI behavior
func getApprovalsWithGateway(timeout_ms int) {
    // Step 1: Always succeeds
    snapshot := rpc.Call("approvals.get_snapshot")
    printSnapshot(snapshot)
// Step 2: Fails on timeout, caught silently
defer func() {
    if r := recover(); r != nil {
        print("Effective Policy -> Config unavailable.")
    }
}()

// This call blocks and respects timeout
config := rpc.CallWithTimeout("config.get", timeout_ms)
printEffectivePolicy(config)
}

Default Timeout Insufficiency

Error Message Ambiguity

The CLI conflates two distinct failure modes:

• Genuine unavailability: Gateway lacks config or config service is down
• Timeout: Gateway is healthy but RPC took longer than CLI's timeout

Both scenarios produce identical output: Config unavailable.

Affected Code Path

// File: cli/commands/approvals/get.go (inferred)
type GetCommand struct {
    Timeout int `flag:"timeout,10000"`  // <-- Hard-coded default
}
func (c *GetCommand) Execute(ctx context.Context) error {
snapshot, err := c.client.GetSnapshot(ctx)
if err != nil {
return fmt.Errorf(“snapshot fetch failed: %w”, err)
}
// Gateway mode requires config for Effective Policy
if c.gatewayMode {
    config, err := c.client.GetConfig(ctx, rpc.WithTimeout(c.Timeout))
    if err != nil {
        // Ambiguous error handling
        fmt.Println("Config unavailable.")
        // Returns success because partial data was retrieved
        return nil
    }
    // ... render config ...
}
}

Immediate Workaround (User-Side)

# Temporarily override the timeout for the approvals command
openclaw approvals get --gateway --timeout 60000

Permanent Configuration Fix

Add the following to your OpenClaw CLI configuration file:

# File: ~/.config/openclaw/CLI config or equivalent
# For Linux/macOS: ~/.config/openclaw/config.yaml
# For Windows: %APPDATA%\openclaw\config.yaml

approvals:
  get:
    timeout: 60000  # 60 seconds in milliseconds
    gateway:
      timeout: 60000

Environment Variable Override

# Set timeout via environment variable (if supported)
export OPENCLAW_APPROVALS_TIMEOUT=60000
export OPENCLAW_GATEWAY_TIMEOUT=60000

# Then run without explicit timeout flag
openclaw approvals get --gateway

Persistent Alias (Bash/Zsh)

# Add to ~/.bashrc or ~/.zshrc
alias openclaw-approvals='openclaw approvals get --gateway --timeout 60000'

# Usage
openclaw-approvals

Systemd Service Override (Daemon Mode)

# Create drop-in override
mkdir -p /etc/systemd/system/openclaw-gateway.service.d/

cat > /etc/systemd/system/openclaw-gateway.service.d/timeout.conf << EOF
[Service]
Environment="OPENCLAW_RPC_TIMEOUT=60000"
ExecStartPost=/usr/bin/openclaw approvals warm-cache --timeout 60000
EOF

systemctl daemon-reload
systemctl restart openclaw-gateway

Before vs After Comparison

gateway timeout after 10000ms
Effective Policy -> Config unavailable.

gateway: healthy
Effective Policy -> orion: approved

Pre-Flight Checks

# 1. Verify OpenClaw version
$ openclaw version
openclaw v2026.4.12 (commit: abc123)

# 2. Verify gateway is healthy
$ openclaw gateway status
Runtime:     running
RPC Probe:   ok
Uptime:      7d 12h 34m

Functional Verification

# Test with extended timeout - should complete successfully
$ openclaw approvals get --gateway --timeout 60000
gateway: healthy
runtime: running

APPROVALS SNAPSHOT
==================
ID       | Subject     | Policy      | Expires
---------|-------------|-------------|------------------
uuid-001 | alice       | orion       | 2026-04-20
uuid-002 | bob         | admin       | 2026-04-25

Effective Policy
================
orion -> approved
admin -> approved

# Verify exit code is 0
$ echo $?
0

Confirm Timeout Detection Works

# Test that artificially short timeout produces expected error
$ openclaw approvals get --gateway --timeout 100
gateway timeout after 100ms

# Verify non-zero exit code
$ echo $?
124

Validate Configuration File Syntax

# If using config file override, validate YAML syntax
$ cat ~/.config/openclaw/config.yaml | python3 -c "import yaml, sys; yaml.safe_load(sys.stdin)"
# No output means valid YAML

# Check effective configuration
$ openclaw config show --verbose 2>&1 | grep -i timeout

Regression Test Suite

# Create a test script for CI/CD
#!/bin/bash
set -e

TIMEOUT_MS=60000
EXPECTED_EXIT=0

openclaw approvals get --gateway --timeout $TIMEOUT_MS > /tmp/output.txt
ACTUAL_EXIT=$?

if [ $ACTUAL_EXIT -ne $EXPECTED_EXIT ]; then
    echo "FAIL: Expected exit $EXPECTED_EXIT, got $ACTUAL_EXIT"
    cat /tmp/output.txt
    exit 1
fi

if grep -q "Config unavailable" /tmp/output.txt; then
    echo "FAIL: Output contains 'Config unavailable'"
    cat /tmp/output.txt
    exit 1
fi

if ! grep -q "Effective Policy" /tmp/output.txt; then
    echo "FAIL: Output missing 'Effective Policy' section"
    cat /tmp/output.txt
    exit 1
fi

echo "PASS: Approvals command completed successfully"
exit 0

Environment-Specific Traps

• Docker Container Resource Constraints

  # Running inside memory/CPU-limited container may exacerbate latency
  docker run --memory=256m --cpus=0.5 openclaw:latest approvals get --gateway --timeout 60000

  Fix: Increase container resources or use --network host to reduce network overhead.

• Kubernetes Pod QoS Class

  Pods with BestEffort QoS may experience inconsistent scheduling delays.

  # Ensure pod spec includes guaranteed resources
  resources:
    requests:
      memory: "256Mi"
      cpu: "500m"
    limits:
      memory: "512Mi"
      cpu: "1000m"

• SSH Tunnel Overhead

  Commands run over SSH tunnels add latency. Timeout may need +10s buffer.

  # From remote host (within SSH session)
  ssh user@gateway-host "openclaw approvals get --gateway --timeout 60000"

Configuration Errors

• YAML Indentation Issues

  # WRONG - tabs or wrong indentation
  approvals:
  get:
    timeout: 60000
  CORRECT - proper YAML indentation
  approvals:
  get:
  timeout: 60000

• Conflicting Environment Variables

  Environment variables may override config file settings unexpectedly.

  # Check what is actually being applied
  openclaw debug config --show-sources

• Stale Configuration Cache

  CLI may cache config. Force reload.

  openclaw config reload
  openclaw approvals get --gateway --timeout 60000

Misinterpretation Risks

• Interpreting "Config unavailable" as Policy Loss

  Operators may panic and initiate unnecessary policy re-deployment.

  Mitigation: Always run openclaw gateway status first to confirm actual gateway health.

• Assuming Regression After Upgrade

  Upgrading OpenClaw may introduce new config fetch paths.

  Mitigation: Check changelog for approvals or gateway changes before assuming regression.

Network Considerations

# Latency test to gateway
ping -c 5 gateway-host

# RPC round-trip timing
openclaw debug rpc ping --count 5 --format json

# Firewall/MTU issues
openclaw gateway status --verbose
# Look for: "RPC latency: Xms" in output

Version-Specific Notes

Common Related Error Codes

• ETIMEDOUT / Exit 124

  General RPC timeout. Indicates the client-side timeout fired before the server responded.

  # Example
  openclaw approvals get --gateway
  # Error: context deadline exceeded: timeout 10000ms

• ECONNREFUSED

  Gateway not running or unreachable. Distinct from timeout.

  $ openclaw gateway status
  Error: dial tcp 127.0.0.1:9090: connect: connection refused

• gateway: unreachable

  Gateway process is down or network path is blocked.

• config.get: context canceled

  Client cancelled the request (e.g., Ctrl+C) mid-flight.

Historical Issues

• Issue #4521: Gateway status hangs on slow networks

  Similar timeout handling issue in gateway status command. Fixed by adding --timeout flag in v2026.3.0.

• Issue #3890: Config unavailable despite healthy gateway

  Earlier report of same symptom pattern. Root cause was config service initialization race condition (now fixed).

• Issue #5102: Approval exec fallback timeout

  Execution approvals using fallback mode had hardcoded 5s timeout causing false negatives.

Known False Positive Patterns

Diagnostic Commands Reference

# Full diagnostic suite
openclaw gateway status --verbose
openclaw config show --effective
openclaw approvals list --all --format json
openclaw debug rpc stats --since 1h

Escalation Path

1. Run openclaw gateway status to confirm actual gateway health
2. Run openclaw approvals get --gateway --timeout 60000 with extended timeout
3. If extended timeout fails, collect: openclaw debug logs --since 5m
4. File issue with: version, OS, timeout used, and full error output