[rluo8]

Summary

Host-side OpenClaw config set now validates the complete candidate config with the installed OpenClaw runtime before replacing the live config.
Invalid candidates fail without changing the existing config or reaching the destructive gateway restart path.
The validated bytes and sandbox container identity are bound to the subsequent digest-protected write.

Related Issue

Fixes #6868

Changes

• Run openclaw config validate --json as the gateway user against the exact serialized candidate.
• Perform schema validation outside the sandbox and shields mutation locks.
• Re-read the config under both locks and require its source digest and serialized candidate bytes to remain unchanged.
• Bind validation and write operations to the same sandbox container identity.
• Limit candidates to 16 MiB and preserve relative OpenClaw config-include resolution.
• Redact validator stderr and surface schema or write failures as clean SandboxConfigError output.
• Keep onboarding, inference, and other generated OpenClaw writes on their existing digest-bound CAS path without adding runtime schema validation.
• Replace schema-invalid config set help examples.
• Add coverage for invalid candidates, validator failures and timeouts, size limits, lock ordering, exact-byte binding, and internal-writer compatibility.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification: this fixes validation of the existing config set workflow without adding or changing CLI syntax; rejected candidates return actionable CLI errors.
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification:
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification:
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result:
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Rui Luo ruluo@nvidia.com

Summary by CodeRabbit

• New Features

  • Sandbox configuration updates now validate OpenClaw settings against the schema before changes are applied.
  • Validation is safer against configuration changes mid-process, preventing inconsistent writes.

• Bug Fixes

  • Prevented invalid OpenClaw configurations from being written and from being recorded in audit history.
  • Improved error reporting with sanitized details, including clearer timeout/termination and “validation couldn’t run” messaging.
  • Added safeguards for oversized inputs and other validation-path failures.

• Documentation

  • Updated CLI examples for OpenClaw-related config keys, including a variant that demonstrates restart behavior for applying changes.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 6c413fee-fa8a-4a3b-be82-e13bf556a2c6

📥 Commits

Reviewing files that changed from the base of the PR and between 98aafd9 and e345d8b.

📒 Files selected for processing (3)

• src/lib/shields/openclaw-config-lock.test.ts
• src/lib/shields/openclaw-config-lock.ts
• test/config-set-nested-ssrf.test.ts

🚧 Files skipped from review as they are similar to previous changes (3)

• test/config-set-nested-ssrf.test.ts
• src/lib/shields/openclaw-config-lock.test.ts
• src/lib/shields/openclaw-config-lock.ts

---

📝 Walkthrough

Walkthrough

OpenClaw sandbox config updates validate serialized candidates before acquiring mutation locks, verify unchanged content after re-reading, and reuse the validated privileged execution context for writes. Validation errors, size limits, timeout handling, CLI examples, and transaction wiring receive test coverage.

Changes

OpenClaw config set transaction

Layer / File(s)	Summary
Schema candidate validation src/lib/shields/openclaw-config-lock.ts, src/lib/shields/openclaw-config-lock.test.ts	Candidates are size-limited, validated through openclaw config validate --json, and reported with sanitized schema or execution errors.
Lock-bound candidate commit src/lib/sandbox/config.ts, test/config-set-nested-ssrf.test.ts, test/openclaw-config-transaction-wiring.test.ts	Config set validates before locks, checks candidate bytes after re-reading, reuses the privileged handle for writing, and verifies lock/write ordering and CAS-only internal writes.
CLI examples and compatibility coverage src/commands/sandbox/config/set.ts, test/cli-oclif-compatibility.test.ts	Examples and compatibility assertions use nested agents.defaults.* OpenClaw configuration paths.

Estimated code review effort: 4 (Complex) | ~45 minutes

Suggested labels: bug-fix, integration: openclaw

Suggested reviewers: cv

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The changes add pre-write validation and lock hardening, but they do not address the reported config set --restart gateway restart hang or stale lock cleanup.	Update the restart flow so config set --restart completes, applies the config to the running agent, and cleans up stale shields-transition locks on failure or timeout.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the primary change: validating OpenClaw config candidates before writes.
Out of Scope Changes check	✅ Passed	The added docs, tests, and OpenClaw validation changes all support the config-set workflow and appear within scope.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions
Status: No actionable findings remain in the canonical review ledger.

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 1 warning · 0 suggestions
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 1 more warning, the same number of suggestions.

Nemotron output stays in workflow artifacts and does not change the assessment above.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: credential-sanitization, security-posture

2 optional E2E recommendations

• shields-config
• ubuntu-repo-cloud-openclaw

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/lib/sandbox/config.ts (1)

1019-1074: 📐 Maintainability & Code Quality | 🟠 Major | 🏗️ Heavy lift

Move the validation-and-commit workflow into a sandbox action.

This block now owns container resolution, schema validation, lock sequencing, byte verification, writing, and audit orchestration inside transitional src/lib/sandbox/**. Introduce one typed action under src/lib/actions/**, route the command and internal callers through it, and keep this module limited to adapters/domain helpers.

As per path instructions, “Actions own lifecycle workflows” and sandbox operations moved to actions must use one authoritative path.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/lib/sandbox/config.ts` around lines 1019 - 1074, Extract the OpenClaw
validation-and-commit workflow currently surrounding validatedOpenClawCandidate
and withSandboxMutationLock into one typed action under src/lib/actions,
including container resolution, schema validation, lock sequencing,
digest/serialized-byte checks, writing, and audit orchestration. Route the
command and all internal callers through this action, leaving
src/lib/sandbox/config.ts responsible only for adapters and domain helpers and
ensuring no alternate sandbox write path remains.

Source: Path instructions

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/lib/shields/openclaw-config-lock.ts`:
- Around line 161-167: Update the validation-result branch around
schemaIssuePaths and hasSchemaIssues to require a clean validator execution
before treating payload.valid === false as a schema rejection. Track and check
the validator’s successful, non-timeout, non-terminated, non-error execution
status so partial output from failed runs cannot enter this branch; preserve the
existing schema issue handling for clean executions.

In `@test/config-set-nested-ssrf.test.ts`:
- Around line 371-428: Extend the “surfaces an OpenClaw schema rejection…” test
to pass an events array and invoke configSet with restart: true. Assert the
events contain only “validate”, guardSpy remains untouched, and the restart
adapter is not called, replacing the insufficient audit-only assertion while
preserving the existing SandboxConfigError checks.

---

Outside diff comments:
In `@src/lib/sandbox/config.ts`:
- Around line 1019-1074: Extract the OpenClaw validation-and-commit workflow
currently surrounding validatedOpenClawCandidate and withSandboxMutationLock
into one typed action under src/lib/actions, including container resolution,
schema validation, lock sequencing, digest/serialized-byte checks, writing, and
audit orchestration. Route the command and all internal callers through this
action, leaving src/lib/sandbox/config.ts responsible only for adapters and
domain helpers and ensuring no alternate sandbox write path remains.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 431757af-8503-45eb-a180-2f8521339408

📥 Commits

Reviewing files that changed from the base of the PR and between 5b67372 and 98aafd9.

📒 Files selected for processing (7)

• src/commands/sandbox/config/set.ts
• src/lib/sandbox/config.ts
• src/lib/shields/openclaw-config-lock.test.ts
• src/lib/shields/openclaw-config-lock.ts
• test/cli-oclif-compatibility.test.ts
• test/config-set-nested-ssrf.test.ts
• test/openclaw-config-transaction-wiring.test.ts

[cv]

Validated exact head e345d8b: candidate schema validation precedes mutation locks, binds exact bytes and container identity through the CAS write, redacts execution output, and has failure/race/no-write coverage. Product scope is the accepted #6868 QA defect.