feat(config): add `openclaw config validate` and improve startup error messages by Sid-Qin · Pull Request #31220 · openclaw/openclaw

Sid-Qin · 2026-03-02T03:13:29Z

Summary

Problem: OpenClaw does not validate config at write time for external edits. Invalid keys written to openclaw.json (by agents, jq, text editors) sit undetected until the next gateway restart, causing crash loops. The startup error says "Invalid config" without identifying which key is invalid.
Why it matters: In agentic deployments, agents modify config programmatically and have no way to verify the write was valid. One user experienced 28 restart cycles over ~14 minutes from a single unrecognized key.
What changed: (1) Added openclaw config validate CLI command for pre-flight config validation without starting the gateway. Supports --json for machine-readable output. (2) Improved the loadConfig error to include specific key paths in the Error message itself.
What did NOT change (scope boundary): The existing writeConfigFile validation (which already works for config set/config patch paths) is untouched. No changes to Zod schema strictness — .strict() was already applied to all objects.

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Closes Config write has no validation — invalid keys silently accepted, only caught on gateway restart #31148

User-visible / Behavior Changes

New CLI command: openclaw config validate — validates the current config against the active Zod schema, reports all offending key paths, and exits with code 0 (valid) or 1 (invalid).
--json flag: openclaw config validate --json outputs { "valid": true/false, "path": "...", "issues": [...] } for machine consumption. Agents can call this after writing config to detect errors before restart.
Improved error message: loadConfig() now throws with the full validation details in the Error message (e.g. "Invalid config at ~/.openclaw/openclaw.json:\n- agents.defaults.suppressToolErrorWarnings: Unrecognized key(s)"), making crash logs immediately actionable without searching separate log lines.

Security Impact (required)

New permissions/capabilities? No
Secrets/tokens handling changed? No
New/changed network calls? No
Command/tool execution surface changed? No — read-only validation, no config modification
Data access scope changed? No

Repro + Verification

Environment

OS: macOS (Apple M4)
Runtime/container: Node.js 22+
Model/provider: Any
Integration/channel (if any): Any
Relevant config (redacted): Standard openclaw.json

Steps

Add an unrecognized key to openclaw.json: { "agents": { "defaults": { "suppressToolErrorWarnings": true } } }
Run openclaw config validate
Observe clear error identifying the exact key path

Expected

openclaw config validate exits with code 1 and prints: × agents.defaults.suppressToolErrorWarnings: Unrecognized key(s) in object

Actual

Before this PR: No validate subcommand exists. Startup error says "Invalid config" without the key path.
After this PR: config validate catches the issue immediately. Startup error includes the key path.

Evidence

Failing test/log before + passing after
Trace/log snippets
Screenshot/recording
Perf numbers (if relevant)

Verified runConfigValidate with valid config (exit 0, "Config valid") and with invalid keys (exit 1, per-key error output). Verified --json mode produces parseable JSON.

Human Verification (required)

Verified scenarios: Valid config → exit 0; invalid key → exit 1 with key path; missing config file → exit 1; --json flag produces correct JSON structure.
Edge cases checked: Multiple validation issues reported; config file not found; <root> path fallback for top-level errors.
What you did not verify: Integration test in a full systemd deployment with crash-loop recovery.

Compatibility / Migration

Backward compatible? Yes — additive CLI subcommand, no existing behavior changed.
Config/env changes? No
Migration needed? No
If yes, exact upgrade steps: N/A

Failure Recovery (if this breaks)

How to disable/revert this change quickly: The validate subcommand is entirely additive. Removing it has no effect on gateway startup or config handling.
Files/config to restore: src/cli/config-cli.ts — remove runConfigValidate and the validate subcommand registration.
Known bad symptoms reviewers should watch for: None — the command is read-only.

Risks and Mitigations

Risk: CONFIG_PATH could resolve to undefined if called before config initialization.
- Mitigation: Falls back to "openclaw.json" literal. The readConfigFileSnapshot() call itself handles path resolution independently.

greptile-apps · 2026-03-02T03:20:19Z

Greptile Summary

This PR adds a openclaw config validate command for pre-flight config validation and improves error messages by including specific key paths in the Error message itself. The implementation is solid and addresses the stated problem of config validation in agentic deployments.

Key Changes:

Added runConfigValidate function with --json flag support for machine-readable output
Improved loadConfig error message to include path and validation details directly in the Error message
New CLI command properly handles missing files, invalid configs, and exceptions with appropriate exit codes

Minor Suggestion:

Consider using snapshot.path from the returned snapshot for output messages to ensure the displayed path matches the actual file being validated, especially in edge cases where environment variables or config candidates change between module load and runtime.

Confidence Score: 4/5

This PR is safe to merge with minimal risk - it's an additive CLI command that doesn't modify existing behavior
Score reflects well-structured implementation with proper error handling, exit codes, and JSON output formatting. One minor suggestion for path display accuracy doesn't impact functionality in typical use cases. The changes are isolated, read-only, and thoroughly address the stated problem.
No files require special attention - both changes are straightforward and well-implemented

_{Last reviewed commit: 88c8737}

greptile-apps

_{2 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

greptile-apps · 2026-03-02T03:20:23Z

src/cli/config-cli.ts

+  const configPath = CONFIG_PATH ?? "openclaw.json";
+  const shortPath = shortenHomePath(configPath);


Consider using snapshot.path instead of CONFIG_PATH for display accuracy. CONFIG_PATH is resolved at module load time, while readConfigFileSnapshot() resolves the path at runtime. If config candidates change or env vars are modified between module load and runtime, the displayed path might not match the actual file being validated. Replace configPath with snapshot.path in outputs (lines 338, 353, 369) and use shortenHomePath(snapshot.path) for lines 340, 355, 371.

Prompt To Fix With AI

This is a comment left during a code review. Path: src/cli/config-cli.ts Line: 330-331 Comment: Consider using `snapshot.path` instead of `CONFIG_PATH` for display accuracy. `CONFIG_PATH` is resolved at module load time, while `readConfigFileSnapshot()` resolves the path at runtime. If config candidates change or env vars are modified between module load and runtime, the displayed path might not match the actual file being validated. Replace `configPath` with `snapshot.path` in outputs (lines 338, 353, 369) and use `shortenHomePath(snapshot.path)` for lines 340, 355, 371. How can I resolve this? If you propose a fix, please make it concise.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4dc41036a0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-03-02T04:47:20Z

src/cli/config-cli.ts

+  const configPath = CONFIG_PATH ?? "openclaw.json";
+  const shortPath = shortenHomePath(configPath);


Use snapshot path for validate output

runConfigValidate reports path and human-readable location from the module-level CONFIG_PATH, but the file actually validated comes from readConfigFileSnapshot() and can differ from that constant (for example when candidate resolution selects another existing config path). In those cases config validate will claim it validated one file while reading another, which can mislead operators and break automation that relies on the emitted path; use snapshot.path for all output/error path fields instead.

Useful? React with 👍 / 👎.

…r messages Add a `config validate` CLI subcommand that checks the current config against the Zod schema without starting the gateway. Supports `--json` for machine-readable output so agents and scripts can validate after external file edits. Also improve the error thrown by `loadConfig` to include the specific offending key paths in the Error message itself, not just as a side property — making crash logs immediately actionable. Closes openclaw#31148 Made-with: Cursor

gumadeiras · 2026-03-02T05:45:54Z

Merged via squash.

Prepared head SHA: 4598f2a
Merge commit: 3002f13

Thanks @Sid-Qin!

@gumadeiras