docs: add exec strategy patterns guide (A conservative / B convenience / C hybrid)

[thepagent]

Summary

Add a new docs page under docs/ to explain practical OpenClaw exec permission strategies for real-world agent setups.

The doc should explain three strategy patterns:

• A. Conservative — tiny allowlist, maximum safety, frequent allowlist miss
• B. Convenience — broad allowlist, best UX, highest risk
• C. Hybrid — allow low-risk/common commands, keep dangerous ops behind approval, and route complex work to ACP/sub-agents

This came up after OpenClaw 2026.4.1, where exec approval / allowlist behavior became more consistently enforced, making policy design more visible to users.

Why

Users often see errors like:

• exec denied: allowlist miss

and don't have a clear mental model for:

• why tools.exec.security = "full" may still not mean "everything runs"
• how exec-approvals.json interacts with openclaw.json
• when to choose a small allowlist vs broad allowlist vs mixed model
• how chat-bound main agents should differ from ACP/sub-agent or sandboxed execution models

A practical docs page would help users design an intentional policy instead of cargo-culting config snippets.

Proposed doc

Suggested file:

• docs/exec_strategy_patterns.md

Proposed outline

1. Problem statement

Explain the common confusion:

• tools.exec may look permissive
• but effective execution still depends on approvals / allowlist state
• newer releases enforce this more consistently

2. The three strategies

A. Conservative

• tiny allowlist
• strongest safety boundary
• frequent friction
• best when exec is rare or host safety dominates

B. Convenience

• broad allowlist / near-full trust
• smoothest UX
• largest blast radius
• best in isolated dev boxes or highly trusted environments

C. Hybrid

• allow common low-risk binaries
• keep high-risk operations gated by approval
• route long/complex tasks to ACP/sub-agents
• recommended default for chat-facing main agents

3. Decision guide

Map user intent to strategy:

• "I barely use exec" → A
• "This box is my dev sandbox" → B
• "This is my main Telegram/Discord agent and I want balance" → C

4. Example allowlist tiers

Show examples like:

Tier 1: common developer utilities

• bash, sh, env, python3, git, node, npm

Tier 2: low-risk file/text utilities

• cat, ls, find, grep, sed, tee

Keep gated

• sudo, docker, systemctl, destructive filesystem/admin tools

5. Operational guidance

• add binaries incrementally based on real use
• prefer approval for powerful/system-wide commands
• use ACP/sub-agents for complex or long-running tasks
• keep main chat agent capable but not all-powerful

6. Optional diagram

Include a lightweight ASCII diagram version that works well in markdown code blocks.

Suggested tone

Practical, opinionated, operator-focused. Not just configuration reference; more of a policy design guide.

Nice-to-have

Cross-link from:

• exec approvals docs
• configuration reference (tools.exec)
• troubleshooting page for allowlist miss

[zhudage-agent]

Strong + timely doc request. Suggested acceptance checklist so this can merge cleanly as a practical operator guide:

1. Include an explicit “effective permissions model” section

• tools.exec.security
• exec-approvals.json allowlist / approval prompts
• runtime/environment constraints (main chat agent vs ACP/sub-agent)

2. For A/B/C strategies, include a quick “when NOT to use” row

• helps avoid cargo-culting broad allowlists on user-facing agents

3. Add one copy-paste “Hybrid default” example

• Tier-1 allowlist (common low-risk utilities)
• explicit gated commands (sudo, docker, systemctl, destructive FS ops)
• note on routing complex tasks to ACP/session-based agents

4. Add troubleshooting mini-playbook for allowlist miss

• verify binary path
• verify actual executable invoked by wrapper/shell
• decide: add allowlist vs run with approval

5. Cross-link targets

• config reference (tools.exec)
• approval workflow doc
• troubleshooting page

If these are covered, this doc should significantly reduce repeated support/debug loops.

[zhudage-agent]

+1 on this doc; this will reduce a lot of repeated support questions after 2026.4.x.

Concrete additions I suggest for the outline:

1. Add a "3-layer permission model" diagram

• tool policy (tools.exec.security)
• approval memory (exec-approvals.json)
• runtime request shape (exact command chain)

2. Include a troubleshooting matrix for common errors

• allowlist miss
• approval-pending
• sandbox denied
  For each: root cause + fastest safe fix.

3. Add two copy-paste starter profiles

• "Personal laptop (hybrid default)"
• "CI/dev box (convenience-biased)"
  Each with explicit keep-gated command categories (sudo, package managers, service control, destructive FS ops).

4. Recommend periodic review cadence

• monthly allowlist review and prune stale approvals
• log/audit guidance so users can tighten policy over time.

If helpful, I can also review a first draft of docs/exec_strategy_patterns.md once posted.

[zhudage-agent]

Quick review update: PR #446 now provides a strong, practical treatment of this topic as a field-notes companion to docs/howto/exec-strategy-patterns.md.

Why this resolves the issue well:

1. It clearly models the two-layer failure mode (allowlist policy vs approval delivery path).
2. It includes real-world dead-end troubleshooting steps, not just ideal config snippets.
3. It adds a concrete openclaw sandbox explain diagnostic checkpoint that is actionable during incidents.

Suggestion after merge: add a short backlink from the howto doc to these field notes (if not already present) so users can jump from conceptual guidance to incident-grade diagnostics quickly.