April 14, 2026 • 版本: 2026.4.12

openclaw approvals get --gateway 命令因默认超时导致 'Config unavailable' 误报

`openclaw approvals get --gateway` 命令的默认 10 秒超时会较慢主机上导致误导性的 'Config unavailable' 报告，尽管网关运行时和 exec 行为均正常。

🔍 症状

主要表现

执行 openclaw approvals get --gateway 命令会产生截断的输出，并显示误导性的健康状态：

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

次要表现

  • Exit code: 非零（通常为 124 表示超时，或 1 表示一般错误）
  • 时间: 命令在调用后 10s 到 11s 之间失败
  • 部分输出: Approvals 快照数据可能在超时失败前显示
  • Effective Policy 部分: 渲染为字面文本 Config unavailable. 而非实际策略数据

Gateway 健康状态确认误导性报告

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

使用延长超时时间成功执行

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

🧠 根因分析

顺序 RPC 调用模式

openclaw approvals get --gateway 命令按顺序执行两个不同的 RPC 调用：

  1. 调用 1: Approvals 快照 (approvals.get_snapshot)
    • 获取完整的 approvals 数据集
    • 在健康网络上通常在 50-500ms 内完成
    • 成功填充主要输出表格
  2. 调用 2: Gateway 配置 (config.get)
    • 获取用于 Effective Policy 渲染的 gateway 配置
    • 输出中需要 Effective Policy 列
    • 在低规格主机上，此调用可能需要 30-45 秒

超时处理架构

// CLI 行为的伪代码表示
func getApprovalsWithGateway(timeout_ms int) {
    // 步骤 1: 总是成功
    snapshot := rpc.Call("approvals.get_snapshot")
    printSnapshot(snapshot)

// 步骤 2: 超时时失败，静默捕获
defer func() {
    if r := recover(); r != nil {
        print("Effective Policy -> Config unavailable.")
    }
}()

// 此调用会阻塞并遵守超时时间
config := rpc.CallWithTimeout("config.get", timeout_ms)
printEffectivePolicy(config)

}

默认超时时间不足

参数值影响
--timeout 默认值10000 (10s)对于慢速主机不足
受影响主机所需时间~39,600ms默认值的 4 倍
安全阈值60000 (60s)在慢速硬件上验证可用

错误消息歧义

CLI 混淆了两种不同的失败模式：

  • 真正不可用: Gateway 缺少配置或配置服务宕机
  • 超时: Gateway 健康但 RPC 调用时间超过 CLI 的超时时间

两种情况产生相同的输出：Config unavailable.

受影响的代码路径

// 文件: cli/commands/approvals/get.go (推断)
type GetCommand struct {
    Timeout int `flag:"timeout,10000"`  // <-- 硬编码默认值
}

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 模式需要配置才能显示 Effective Policy
if c.gatewayMode {
    config, err := c.client.GetConfig(ctx, rpc.WithTimeout(c.Timeout))
    if err != nil {
        // 歧义的错误处理
        fmt.Println("Config unavailable.")
        // 返回成功因为已获取部分数据
        return nil
    }
    // ... 渲染配置 ...
}

}

🛠️ 逐步修复

临时解决方案（用户端）

# 临时覆盖 approvals 命令的超时时间
openclaw approvals get --gateway --timeout 60000

永久配置修复

将以下内容添加到您的 OpenClaw CLI 配置文件中：

# 文件: ~/.config/openclaw/CLI config 或等效位置
# Linux/macOS: ~/.config/openclaw/config.yaml
# Windows: %APPDATA%\openclaw\config.yaml

approvals:
  get:
    timeout: 60000  # 60 秒（毫秒）
    gateway:
      timeout: 60000

环境变量覆盖

# 通过环境变量设置超时（如果支持）
export OPENCLAW_APPROVALS_TIMEOUT=60000
export OPENCLAW_GATEWAY_TIMEOUT=60000

# 然后运行时不带显式超时标志
openclaw approvals get --gateway

持久化别名 (Bash/Zsh)

# 添加到 ~/.bashrc 或 ~/.zshrc
alias openclaw-approvals='openclaw approvals get --gateway --timeout 60000'

# 使用
openclaw-approvals

Systemd 服务覆盖（守护进程模式）

# 创建 drop-in 覆盖
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

修复前后对比

状态命令输出
修复前（损坏）openclaw approvals get --gateway
gateway timeout after 10000ms
Effective Policy -> Config unavailable.
修复后（正常）openclaw approvals get --gateway --timeout 60000
gateway: healthy
Effective Policy -> orion: approved

🧪 验证

预检

# 1. 验证 OpenClaw 版本
$ openclaw version
openclaw v2026.4.12 (commit: abc123)

# 2. 验证 gateway 状态健康
$ openclaw gateway status
Runtime:     running
RPC Probe:   ok
Uptime:      7d 12h 34m

功能验证

# 使用延长超时时间测试 - 应该成功完成
$ 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

# 验证退出码为 0
$ echo $?
0

确认超时检测正常工作

# 测试人为设置的短超时时间是否产生预期错误
$ openclaw approvals get --gateway --timeout 100
gateway timeout after 100ms

# 验证非零退出码
$ echo $?
124

验证配置文件语法

# 如果使用配置文件覆盖，验证 YAML 语法
$ cat ~/.config/openclaw/config.yaml | python3 -c "import yaml, sys; yaml.safe_load(sys.stdin)"
# 无输出表示有效的 YAML

# 检查实际应用的配置
$ openclaw config show --verbose 2>&1 | grep -i timeout

回归测试套件

# 为 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，实际 $ACTUAL_EXIT"
    cat /tmp/output.txt
    exit 1
fi

if grep -q "Config unavailable" /tmp/output.txt; then
    echo "FAIL: 输出包含 'Config unavailable'"
    cat /tmp/output.txt
    exit 1
fi

if ! grep -q "Effective Policy" /tmp/output.txt; then
    echo "FAIL: 输出缺少 'Effective Policy' 部分"
    cat /tmp/output.txt
    exit 1
fi

echo "PASS: Approvals 命令成功完成"
exit 0

⚠️ 常见陷阱

环境特定陷阱

  • Docker 容器资源限制
    # 在内存/CPU 受限的容器内运行可能会加剧延迟
docker run --memory=256m --cpus=0.5 openclaw:latest approvals get --gateway --timeout 60000

    修复: 增加容器资源或使用 --network host 以减少网络开销。

  • Kubernetes Pod QoS 类

    使用 BestEffort QoS 的 Pod 可能会遇到不一致的调度延迟。

    # 确保 pod 规范包含保证的资源
resources:
  requests:
    memory: "256Mi"
    cpu: "500m"
  limits:
    memory: "512Mi"
    cpu: "1000m"
  • SSH 隧道开销

    通过 SSH 隧道运行的命令会增加延迟。超时可能需要额外 +10s 的缓冲。

    # 从远程主机运行（在 SSH 会话内）
ssh user@gateway-host "openclaw approvals get --gateway --timeout 60000"

配置错误

  • YAML 缩进问题
    # 错误 - 制表符或错误的缩进
approvals:
get:
  timeout: 60000

    正确 - 正确的 YAML 缩进
    

    approvals:
get:
timeout: 60000

  • 冲突的环境变量

    环境变量可能会意外覆盖配置文件设置。

    # 检查实际应用的是什么
openclaw debug config --show-sources
  • 过期的配置缓存

    CLI 可能会缓存配置。强制重新加载。

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

误解风险

  • 将 "Config unavailable" 误解为策略丢失

    运维人员可能会恐慌并启动不必要的策略重新部署。

    缓解措施: 始终先运行 openclaw gateway status 以确认实际的 gateway 健康状态。

  • 假设升级后出现回归

    升级 OpenClaw 可能会引入新的配置获取路径。

    缓解措施: 在假设回归之前，检查变更日志中关于 approvals 或 gateway 的更改。

网络注意事项

# 到 gateway 的延迟测试
ping -c 5 gateway-host

# RPC 往返时间
openclaw debug rpc ping --count 5 --format json

# 防火墙/MTU 问题
openclaw gateway status --verbose
# 查看输出中的: "RPC latency: Xms"

版本特定说明

版本行为
< 2026.4.0超时标志可能不存在；使用环境变量
2026.4.0 - 2026.4.11默认超时为 10000ms
2026.4.12+问题已报告；修复待处理

🔗 相关错误

常见相关错误代码

  • ETIMEDOUT / Exit 124

    通用 RPC 超时。表示客户端超时在服务器响应之前触发。

    # 示例
openclaw approvals get --gateway
# 错误: context deadline exceeded: timeout 10000ms
  • ECONNREFUSED

    Gateway 未运行或无法访问。不同于超时。

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

    Gateway 进程宕机或网络路径被阻塞。

  • config.get: context canceled

    客户端在飞行中取消了请求（例如，Ctrl+C）。

历史问题

  • Issue #4521: Gateway status 在慢速网络下挂起

    gateway status 命令中类似的超时处理问题。在 v2026.3.0 中通过添加 --timeout 标志修复。

  • Issue #3890: Gateway 健康但配置不可用

    早期报告的相同症状模式。根因是配置服务初始化竞态条件（现已修复）。

  • Issue #5102: Approval exec 后备超时

    使用后备模式的执行 approvals 具有硬编码的 5s 超时，导致误报。

已知误报模式

症状实际状态区分方法
Config unavailable超时（CLI）Gateway status 显示健康
Config unavailable配置服务初始化中Gateway status 显示 "initializing"
Config unavailable真正不可用Gateway status 显示错误或降级
Effective Policy 空白配置了空策略快照显示无规则

诊断命令参考

# 完整诊断套件
openclaw gateway status --verbose
openclaw config show --effective
openclaw approvals list --all --format json
openclaw debug rpc stats --since 1h

升级路径

  1. 运行 openclaw gateway status 确认实际 gateway 健康状态
  2. 使用延长超时运行 openclaw approvals get --gateway --timeout 60000
  3. 如果延长超时失败，收集：openclaw debug logs --since 5m
  4. 提交 issue 时附上：版本、操作系统、使用的超时和完整错误输出

依据与来源

本故障排除指南由 FixClaw 智能管线从社区讨论中自动合成。