OpenClaw docs capability audit — initial pass

過去レポートのView/ソース規律バックフィルで生成したView。

Generated: 2026-05-10 13:24 JST

Why this exists

健人くん's point: if we're going to use OpenClaw, we should use the intended features instead of rebuilding half-working custom glue. The heartbeat misconfiguration showed a gap between docs/config intent and actual runtime behavior.

Docs reviewed in this pass

• docs/automation/index.md
• docs/gateway/heartbeat.md
• docs/automation/tasks.md
• docs/automation/taskflow.md
• docs/concepts/commitments.md
• Generated index: projects/task-queue-visibility/reports/openclaw-docs-capability-index-20260510-132119.md

Initial findings

1. Heartbeat: intended for flexible context-aware monitoring — now mostly aligned

Docs say heartbeat is a periodic main-session turn, not a task record, and can run a custom prompt / HEARTBEAT.md checklist. Earlier we had the classic mismatch: HEARTBEAT.md said one thing, active config prompt said another. That is now fixed and verified after restart.

Current risk: heartbeat still depends on main session and can be skipped when busy. That's acceptable for flexible monitoring, not exact jobs.

Action: keep heartbeat for recovery/autonomy checks. Do not use it for exact reminders.

2. Cron: intended for exact timing / isolated scheduled work — partially used

Docs say cron is for exact timing and isolated/background execution. We already use cron for watchdog and Obsidian sync. Good.

Gap: periodic OpenClaw docs/capability audit should probably be a low-frequency cron or heartbeat safe-step, but not yet scheduled. Scheduling is a persistent task change, so propose separately.

3. Tasks: intended as activity ledger, not backlog — now aligned

Docs explicitly say tasks are records, not schedulers. Our earlier confusion was treating runtime tasks as backlog. We fixed that by using Markdown task ledger and treating OpenClaw tasks as evidence.

Action: keep current ledger approach.

4. Task Flow: intended for durable multi-step flows — underused, but not urgent

Docs recommend Task Flow for multi-step pipelines across restarts. Our current safe-step loop is intentionally simple and local. For larger recurring audits/reports, Task Flow may be better than ad-hoc heartbeat scripting.

Action: add later candidate: convert docs capability audit into TaskFlow only if it becomes multi-step/recurring enough.

5. Commitments: intended for inferred follow-ups — enabled and verified

Docs say commitments are opt-in, delivered through heartbeat, not exact reminders. We enabled and verified config. Good.

Gap: no ongoing audit that commitments extraction/delivery behaves well over time.

Action: leave watch-only unless evidence shows missed follow-ups.

6. Sandbox/security: intended to reduce blast radius — investigated, not applied

OpenClaw security audit shows no critical issue. Docker is running now, so sandboxing non-main work is feasible, but changing config can break cron/subagents. Correct handling: propose with rollback and apply only after approval.

7. Recovery after restart: docs favor durable task/flow state — custom gap fixed

Gateway restart can abort the current turn. We added a checkpoint/resume watcher. This is consistent with docs' general emphasis on durable state and recovery.

Safe auto-fixes already done

• Heartbeat config prompt now actually runs recovery + autonomy step.
• Restart post-check checkpoint/resumer implemented.
• Runtime tasks no longer treated as backlog source of truth.
• Autonomy loop skips blocked/deferred tasks instead of stalling.

Next safe internal actions

1. Continue docs audit across remaining high-impact docs:

- gateway/sandboxing.md

- gateway/sandbox-vs-tool-policy-vs-elevated.md

- automation/cron-jobs.md

- automation/standing-orders.md

- concepts/memory*.md

- concepts/context*.md

- concepts/queue*.md

- concepts/retry.md

- concepts/progress-drafts.md

- channels/telegram.md

1. For each finding, classify: safe/internal auto-fix, needs approval, or watch/leave.
2. Implement safe internal fixes directly; create proposal notes for risky config changes.

Subagent review / live config evidence update — 13:30 JST

Read-only CC review agrees: OpenClaw is broadly aligned with intended usage, but custom workspace glue has grown and should be kept deliberate.

Safe fixes applied during this audit

• Memory index was dirty; ran openclaw memory index --force. Verified Dirty: no.
• Heartbeat config prompt was stale compared with HEARTBEAT.md; updated agents.defaults.heartbeat.prompt to include scripts/gateway_restart_resume_watch.py first. Config guard passes. Gateway restart is still needed to apply the prompt change.

Additional findings

• Telegram access posture is good: DM allowlist is 7789180125, groups disabled, progress notifications silent, completion notifications normal.
• Runtime task audit is clean.
• Commitments are enabled but pending entries are accumulating; watch for noise before changing maxPerDay.
• Memory wiki appears underused/empty per CC review; treat as candidate, not urgent.
• Browser automation exists but scope approval/config/tool policy is not fully ready.
• Sandbox remains the largest useful-but-risky adoption candidate; should be proposed with rollback and restart approval.
• Cron failure destinations could be tightened for visibility but are external notification behavior, so ask before applying.