Manifestación Principal

Al ejecutar openclaw approvals get --gateway se produce una salida truncada con un estado de salud engañoso:

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

Manifestaciones Secundarias

• Código de salida: No cero (típicamente 124 indicando timeout, o 1 para error general)
• Tiempo: El comando falla entre 10s y 11s desde la invocación
• Salida parcial: Los datos del snapshot de aprobaciones pueden aparecer antes del fallo por timeout
• Sección Effective Policy: Se renderiza como texto literal Config unavailable. en lugar de los datos reales de la política

La Salud del Gateway Confirma el Informe Engañoso

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

Ejecución Exitosa con Timeout Extendido

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

Patrón de Llamadas RPC Secuenciales

El comando openclaw approvals get --gateway ejecuta dos llamadas RPC distintas de forma secuencial:

1. Llamada 1: Snapshot de Aprobaciones (approvals.get_snapshot)
   • Obtiene el conjunto completo de datos de aprobaciones
   • Típicamente se completa en 50-500ms en redes saludables
   • Llena correctamente la tabla de salida principal
2. Llamada 2: Config del Gateway (config.get)
   • Obtiene la configuración del gateway para el renderizado de Effective Policy
   • Necesario para la columna Effective Policy en la salida
   • En hosts de bajo rendimiento, esta llamada puede tomar 30-45 segundos

Arquitectura de Manejo de Timeout

// 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)
}

Insuficiencia del Timeout por Defecto

Ambigüedad del Mensaje de Error

La CLI confunde dos modos de fallo distintos:

• Indisponibilidad genuina: El gateway carece de configuración o el servicio de configuración está caído
• Timeout: El gateway está saludable pero la llamada RPC tardó más que el timeout de la CLI

Ambos escenarios producen salida idéntica: Config unavailable.

Ruta de Código Afectada

// 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 ...
}
}

Solución Alternativa Inmediata (Lado del Usuario)

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

Corrección de Configuración Permanente

Añade lo siguiente a tu archivo de configuración de OpenClaw CLI:

# 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

Override con Variable de Entorno

# 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

Alias Persistente (Bash/Zsh)

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

# Usage
openclaw-approvals

Override de Servicio Systemd (Modo Daemon)

# 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

Comparación Antes vs Después

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

gateway: healthy
Effective Policy -> orion: approved

Verificaciones Previas al Vuelo

# 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

Verificación Funcional

# 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

Confirmar que la Detección de Timeout Funciona

# 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

Validar la Sintaxis del Archivo de Configuración

# 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

Suite de Pruebas de Regresión

# 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

Trampas Específicas del Entorno

• Restricciones de Recursos del Contenedor Docker

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

  Solución: Aumenta los recursos del contenedor o usa --network host para reducir la sobrecarga de red.

• Clase QoS del Pod de Kubernetes

  Los pods con QoS BestEffort pueden experimentar retrasos de programación inconsistentes.

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

• Sobrecarga del Túnel SSH

  Los comandos ejecutados a través de túneles SSH añaden latencia. El timeout puede necesitar un buffer adicional de +10s.

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

Errores de Configuración

• Problemas de Indentación YAML

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

• Variables de Entorno en Conflicto

  Las variables de entorno pueden sobrescribir la configuración del archivo de manera inesperada.

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

• Cache de Configuración Obsoleta

  La CLI puede tener la configuración en caché. Fuerza la recarga.

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

Riesgos de Mala Interpretación

• Interpretar "Config unavailable" como Pérdida de Política

  Los operadores pueden entrar en pánico e iniciar una re-despliegue innecesario de políticas.

  Mitigación: Siempre ejecuta primero openclaw gateway status para confirmar la salud real del gateway.

• Asumir Regresión Después de una Actualización

  Actualizar OpenClaw puede introducir nuevas rutas de obtención de configuración.

  Mitigación: Revisa el changelog para cambios en approvals o gateway antes de asumir regresión.

Consideraciones de Red

# 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

Notas Específicas por Versión

Códigos de Error Comunes Relacionados

• ETIMEDOUT / Salida 124

  Timeout general de RPC. Indica que el timeout del lado del cliente se activó antes de que el servidor respondiera.

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

• ECONNREFUSED

  El gateway no está corriendo o es inaccesible. Distinto del timeout.

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

• gateway: unreachable

  El proceso del gateway está caído o la ruta de red está bloqueada.

• config.get: context canceled

  El cliente canceló la solicitud (ej., Ctrl+C) a mitad de vuelo.

Problemas Históricos

• Issue #4521: Gateway status cuelga en redes lentas

  Problema similar de manejo de timeout en el comando gateway status. Corregido añadiendo el flag --timeout en v2026.3.0.

• Issue #3890: Config unavailable a pesar de gateway saludable

  Reporte anterior del mismo patrón de síntomas. La causa raíz fue una condición de carrera en la inicialización del servicio de configuración (ahora corregido).

• Issue #5102: Timeout de fallback en approval exec

  Las aprobaciones de ejecución usando modo fallback tenían un timeout hardcodeado de 5s causando falsos negativos.

Patrones de Falsos Positivos Conocidos

Referencia de Comandos de Diagnóstico

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

Ruta de Escalamiento

1. Ejecuta openclaw gateway status para confirmar la salud real del gateway
2. Ejecuta openclaw approvals get --gateway --timeout 60000 con timeout extendido
3. Si el timeout extendido falla, recolecta: openclaw debug logs --since 5m
4. Reporta el issue con: versión, SO, timeout usado, y salida de error completa