Skip to content

docs: add /nodes openclaw.json example (AI-assisted)#92678

Closed
ZengWen-DT wants to merge 1 commit into
openclaw:mainfrom
ZengWen-DT:docs/nodes-openclaw-json-example
Closed

docs: add /nodes openclaw.json example (AI-assisted)#92678
ZengWen-DT wants to merge 1 commit into
openclaw:mainfrom
ZengWen-DT:docs/nodes-openclaw-json-example

Conversation

@ZengWen-DT

@ZengWen-DT ZengWen-DT commented Jun 13, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Adds an AI-assisted docs clarification to /nodes with a compact ~/.openclaw/openclaw.json example for gateway.nodes.allowCommands and gateway.nodes.denyCommands.
  • Keeps the example next to the existing node command-policy explanation so the config shape is tied to the node command safety model, not presented as generic setup boilerplate.
  • Calls out that denyCommands uses exact command names and overrides defaults or explicit allow entries.
  • What did NOT change: runtime behavior, config schema, Gateway command policy, node pairing behavior, and the full configuration reference.
  • Review focus: whether the example belongs in the command-policy section and whether the allow/deny wording matches current node command semantics.

Linked context

Closes #92662

Requested by the issue reporter via docs feedback for https://docs.openclaw.ai/nodes.

Real behavior proof (required for external PRs)

  • Behavior or issue addressed: /nodes now includes a direct openclaw.json example for configuring selected high-risk node commands.
  • Real environment tested: OpenClaw source checkout on branch docs/nodes-openclaw-json-example, based on upstream/main at 4c23d1d597.
  • Exact steps or command run after this patch: pnpm docs:list; git diff --check upstream/main...HEAD; DOCS_I18N_GLOSSARY_BASE=upstream/main pnpm check:docs.
  • Evidence after fix (screenshot, recording, terminal capture, console output, redacted runtime log, linked artifact, or copied live output): docs/nodes/index.md now contains the JSON5 example under Command policy; pnpm check:docs completed with Summary: 0 error(s), Docs MDX check passed (677 files, 7778ms), and broken_links=0.
  • Observed result after fix: the docs page source has the requested ~/.openclaw/openclaw.json example and the docs validation suite passes against the upstream main base.
  • What was not tested: hosted Mintlify deployment rendering after merge.
  • Proof limitations or environment constraints: docs-only change; no Gateway runtime behavior was changed or exercised.
  • Before evidence (optional but encouraged): current /nodes source had gateway.nodes.allowCommands / gateway.nodes.denyCommands prose but no direct openclaw.json or JSON5 example on the reported page.

Tests and validation

  • pnpm docs:list
  • git diff --check upstream/main...HEAD
  • DOCS_I18N_GLOSSARY_BASE=upstream/main pnpm check:docs

No regression test was added because this is a docs-only clarification. The docs validation path covers formatting, markdownlint, MDX parsing, i18n glossary checks against the PR base, and internal links.

Risk checklist

Did user-visible behavior change? No

Did config, environment, or migration behavior change? No

Did security, auth, secrets, network, or tool execution behavior change? No

What is the highest-risk area?

Docs accuracy for node command allow/deny policy.

How is that risk mitigated?

The example is anchored to the existing /nodes Command policy section, uses the current gateway.nodes.* config keys, and explicitly states that denyCommands overrides defaults and allowCommands.

Current review state

Next action: maintainer review.

Waiting on: CI and reviewer feedback.

Bot/reviewer comments addressed: none yet.

@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation plugin: file-transfer size: XS proof: supplied External PR includes structured after-fix real behavior proof. labels Jun 13, 2026
@clawsweeper

clawsweeper Bot commented Jun 13, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge. Reviewed June 13, 2026, 9:16 AM ET / 13:16 UTC.

Summary
The PR adds a compact JSON5 ~/.openclaw/openclaw.json example for gateway.nodes.allowCommands and gateway.nodes.denyCommands to docs/nodes/index.md.

PR surface: Docs +24. Total +24 across 1 file.

Reproducibility: not applicable. as a runtime bug; this is a docs clarification. Source inspection of current docs/nodes/index.md confirms the page lacks the direct openclaw.json example requested by the linked feedback issue.

Review metrics: 2 noteworthy metrics.

  • Competing docs implementations: 2 open PRs close the same docs issue. Maintainers need to choose or reconcile the duplicate /nodes config examples before merge.
  • Runtime config surfaces: 0 added or changed; 2 existing fields documented. The PR documents existing gateway.nodes keys and does not change runtime config compatibility.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🌊 off-meta tidepool
Patch quality: 🦞 diamond lobster
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • Reconcile this focused example with the broader sibling PR and merge only one final /nodes config approach.

Risk before merge

  • [P1] Two open PRs currently close the same docs feedback issue and edit the same /nodes page; landing both without reconciliation would likely duplicate or split the openclaw.json guidance.

Maintainer options:

  1. Reconcile the duplicate docs approach (recommended)
    Compare this focused allow/deny example with the broader sibling PR and merge one final /nodes config section before either branch lands.
  2. Choose the focused snippet
    If maintainers prefer command-policy placement, merge this PR and close or update the sibling PR so the docs do not grow competing examples.
  3. Pause one duplicate branch
    Leave both PRs unmerged until a maintainer picks the canonical docs shape for the linked feedback issue.

Next step before merge

  • A maintainer should choose or reconcile the two open docs PRs for the same /nodes feedback before merging either one.

Security
Cleared: The diff is docs-only and introduces no executable code, dependency, workflow, secret-handling, or supply-chain surface.

Review details

Best possible solution:

Land one source-backed /nodes config example, either by choosing this focused command-policy snippet or reconciling it with the broader sibling docs PR before merge.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a runtime bug; this is a docs clarification. Source inspection of current docs/nodes/index.md confirms the page lacks the direct openclaw.json example requested by the linked feedback issue.

Is this the best way to solve the issue?

Yes, this is a maintainable docs-only solution because the snippet mirrors the current schema and runtime allow/deny semantics. The best merge path still requires choosing or reconciling it with the broader sibling PR.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against dc493bc9a2b6.

Label changes

Label changes:

  • add merge-risk: 🚨 other: The merge risk is duplicate or split documentation guidance because another open PR targets the same page and issue.
  • add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🦞 diamond lobster.
  • remove rating: 🦞 diamond lobster: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.

Label justifications:

  • P3: This is a low-risk documentation clarification for an existing config shape, not a runtime regression.
  • merge-risk: 🚨 other: The merge risk is duplicate or split documentation guidance because another open PR targets the same page and issue.
  • rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🦞 diamond lobster.
  • status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.
Evidence reviewed

PR surface:

Docs +24. Total +24 across 1 file.

View PR surface stats
Area Files Added Removed Net
Source 0 0 0 0
Tests 0 0 0 0
Docs 1 24 0 +24
Config 0 0 0 0
Generated 0 0 0 0
Other 0 0 0 0
Total 1 24 0 +24

What I checked:

  • PR diff adds focused command-policy example: The patch inserts a 24-line JSON5 Gateway config example next to the existing /nodes command-policy text and does not touch runtime, schema, workflow, package, or generated files. Public docs: docs/nodes/index.md. (docs/nodes/index.md:205, a56c52e40c78)
  • Current docs gap is real: Current main explains gateway.nodes.allowCommands and gateway.nodes.denyCommands but has no direct local openclaw.json/JSON5 example on the /nodes page before this PR. Public docs: docs/nodes/index.md. (docs/nodes/index.md:191, dc493bc9a2b6)
  • Config type matches the documented shape: GatewayNodesConfig defines allowCommands?: string[] and denyCommands?: string[], so the example documents existing fields rather than adding a new config surface. (src/config/types.gateway.ts:441, dc493bc9a2b6)
  • Strict schema matches the documented keys: The Zod config schema accepts gateway.nodes.allowCommands and gateway.nodes.denyCommands as optional string arrays under a strict gateway.nodes object. (src/config/zod-schema.ts:1207, dc493bc9a2b6)
  • Runtime deny semantics match the docs wording: The node command policy adds defaults, approved commands, and allowCommands, then trims and deletes each denyCommands entry from the allow set, matching the PR's override wording. (src/gateway/node-command-policy.ts:342, dc493bc9a2b6)
  • Existing tests cover the example's high-risk command behavior: The test suite confirms allowCommands: ["camera.snap", "screen.record"] enables those commands while camera.clip remains disabled unless separately allowed. (src/gateway/gateway-misc.test.ts:881, dc493bc9a2b6)

Likely related people:

  • steipete: History shows Peter Steinberger introduced early node allowlist behavior and later hardened node metadata policy; PR metadata also shows he merged the recent current-line carrier PR. (role: original and recent area contributor; confidence: high; commits: 9dbc1435a6ca, 0eac494db717, d2f6316c549a; files: src/gateway/node-command-policy.ts, docs/nodes/index.md, src/config/types.gateway.ts)
  • mbelinky: PR history for device pairing and phone control plugins includes the commits that made dangerous node commands opt-in, directly adjacent to the documented allow/deny behavior. (role: feature contributor; confidence: high; commits: 730f86dd5c43, ea0ad9fbcb2a, 355b69e04450; files: src/gateway/node-command-policy.ts, docs/nodes/index.md)
  • tangtaizong666: Current blame for the touched docs/config/policy lines points to the recent fix(agents): isolate invalid plugin model catalogs PR, though the commit appears broader than this node-docs semantic area. (role: recent line-blame carrier; confidence: low; commits: c9f0bfd4764d, 7f0d78b257aa; files: docs/nodes/index.md, src/config/types.gateway.ts, src/gateway/node-command-policy.ts)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works
  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

@clawsweeper clawsweeper Bot added rating: 🦞 diamond lobster Very strong PR readiness with only minor maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. labels Jun 13, 2026
@clawsweeper clawsweeper Bot mentioned this pull request Jun 13, 2026
Merged
@clawsweeper clawsweeper Bot added rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. merge-risk: 🚨 other 🚨 Merging this PR has meaningful risk outside the owned taxonomy. and removed rating: 🦞 diamond lobster Very strong PR readiness with only minor maintainer review expected. labels Jun 13, 2026
@vincentkoc

vincentkoc commented Jun 13, 2026

Copy link
Copy Markdown
Member

Closing this as covered by #92677, which has now landed as d912909.

I used #92677 as the canonical patch because it covers the broader /nodes config shape from #92662: node pairing, command allow/deny policy, node exec routing, and per-agent node pinning. I folded in the important part from this PR too: exact denyCommands matching plus the config-reference pointer, and credited you in the squash message.

Thanks for the parallel fix here.

@vincentkoc vincentkoc closed this Jun 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

docs Improvements or additions to documentation merge-risk: 🚨 other 🚨 Merging this PR has meaningful risk outside the owned taxonomy. P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. plugin: file-transfer proof: supplied External PR includes structured after-fix real behavior proof. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. size: XS status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Docs feedback: /nodes

3 participants

@ZengWen-DT @vincentkoc @Zeng-wen