PR #69654: docs: warn about node Accessibility grants

• Repository: openclaw/openclaw
• Author: yuaiccc
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/69654

Description (problem / solution / changelog)

Summary

• Problem: macOS Accessibility docs did not clearly warn about granting permissions to a shared node runtime.
• Why it matters: TCC grants Accessibility to the process identity macOS sees, so a node grant can apply to any npm package launched through that same binary.
• What changed: Added a prominent Node/CLI runtime warning to the macOS permissions docs and linked to it from the Peekaboo Bridge security notes.
• What did NOT change (scope boundary): No runtime behavior, permission prompts, signing logic, or bridge authorization behavior changed.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #69561
• Related #
• This PR fixes a bug or regression

Root Cause (if applicable)

N/A

• Root cause: N/A
• Missing detection / guardrail: N/A
• Contributing context (if known): N/A

Regression Test Plan (if applicable)

N/A

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: pnpm check:docs
• Scenario the test should lock in: Documentation formatting, linting, glossary, and internal links remain valid.
• Why this is the smallest reliable guardrail: The change is docs-only.
• Existing test that already covers this (if any): pnpm check:docs
• If no new test is added, why not: Docs-only change.

User-visible / Behavior Changes

Users reading macOS permission docs now see a warning that granting Accessibility to node is broader than granting it to a signed app/helper.

Diagram (if applicable)

N/A

Before:
[user reads macOS permission docs] -> [no explicit node Accessibility warning]

After:
[user reads macOS permission docs] -> [sees node runtime warning] -> [can choose signed app/helper instead]

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: macOS
• Runtime/container: local repository checkout
• Model/provider: N/A
• Integration/channel (if any): docs
• Relevant config (redacted): N/A

Steps

1. Read docs/platforms/mac/permissions.md.
2. Read docs/platforms/mac/peekaboo.md.
3. Run pnpm check:docs.

Expected

• Docs warn that granting Accessibility to node grants broad GUI automation access to packages run by that Node binary.
• Docs checks pass.

Actual

• Docs warning added.
• pnpm check:docs passed.

Evidence

Attach at least one:

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

pnpm check:docs passed locally:

• markdownlint: 0 errors
• docs-link-audit: broken_links=0

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: Reviewed the updated docs and ran pnpm check:docs.
• Edge cases checked: Internal link from Peekaboo docs to the new permissions section resolves in the docs link audit.
• What you did not verify: Rendered docs site in a browser.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: The warning could be interpreted as a runtime change.
  • Mitigation: The summary and security impact sections explicitly state this is docs-only.

Changed files

• docs/platforms/mac/peekaboo.md (modified, +4/-0)
• docs/platforms/mac/permissions.md (modified, +20/-0)