Summary

Prevent Gateway crashes by validating configuration files before startup and providing clear error messages for invalid configuration keys.

Problem

Real-world incident: An invalid configuration key groupAllowFrom caused Gateway to crash in a loop without any clear error message. The only way to diagnose was to manually check logs and trace back to the configuration issue.

Impact:

• Gateway enters crash loop, becoming unresponsive
• No clear indication of what went wrong
• Users waste time debugging instead of getting actionable feedback
• Remote instances become inaccessible

Proposed Solution

1. Pre-startup Configuration Validation

$ openclaw gateway start
❌ Configuration error: Unknown key "groupAllowFrom" at line 42
   Valid keys for this section: allowedOrigins, token, port...
   
Run 'openclaw doctor' for detailed diagnostics.

2. Schema-based Validation

• Define JSON schema for all configuration sections
• Reject unknown keys with suggestions for correct keys
• Type checking for values (string, number, boolean, array)
• Required field validation

3. Doctor Integration

$ openclaw doctor
✓ Checking configuration...
  ✗ Invalid: Unknown key "groupAllowFrom" in gateway section
    → Did you mean "allowedOrigins"?
  ✓ Valid: token, port, model defaults

4. Graceful Degradation

• Warn but don't crash for non-critical config issues
• Only crash for critical errors (auth, model config)
• Log all configuration warnings at startup

Benefits

• Faster debugging: Immediate feedback on config errors
• Reduced support burden: Self-service error resolution
• Better UX: Clear, actionable error messages
• Prevention: Catch errors before they cause downtime

Implementation Notes

• Can use JSON Schema for validation
• Should be backwards compatible (warn on deprecated keys, not error)
• Could be incremental: start with critical sections, expand over time

中文说明

问题

无效配置键 groupAllowFrom 导致 Gateway 崩溃循环，无明确错误提示，只能手动查日志定位。

建议

1. 启动前校验配置，拒绝无效键
2. 基于 JSON Schema 的配置校验
3. openclaw doctor 集成配置诊断
4. 优雅降级：非关键配置警告不崩溃

收益

• 快速定位配置错误
• 减少支持负担
• 提升用户体验
• 预防停机事故

Acknowledgments

First, I want to express my sincere gratitude to the OpenClaw team. The project has been incredibly helpful in my daily workflow, and the community support on Discord has been excellent. This suggestion comes from real-world usage experience, and I hope it can help make OpenClaw even more robust for everyone. Thank you for building such an amazing tool! 🦞

🤖 This issue was AI-assisted based on production incident experience.