docs: sync from clawdbot main (Mar 9 sync 6+7, issue/PR updates, link fixes)

Author: centminmod

02-technical/architecture.md

@@ -91,7 +91,7 @@ Docs: https://docs.openclaw.ai/gateway/configuration
 
 ### Input sanitization
 
-`src/gateway/chat-sanitize.ts` strips platform envelope metadata (WhatsApp headers, message IDs, control characters) from user messages before processing. `sanitizeChatSendMessageInput()` (`src/gateway/server-methods/chat.ts:218`) rejects null bytes and strips disallowed control characters, allowing only tabs, newlines, carriage returns, and printable characters through.
+`src/gateway/chat-sanitize.ts` strips platform envelope metadata (WhatsApp headers, message IDs, control characters) from user messages before processing. `sanitizeChatSendMessageInput()` (`src/gateway/server-methods/chat.ts:228`) rejects null bytes and strips disallowed control characters, allowing only tabs, newlines, carriage returns, and printable characters through.
 
 ### Config merge-patch
 
@@ -172,7 +172,7 @@ Below is a conceptual pipeline. Exact details vary by channel.
 
 1.5) **Input sanitization**
 - Strip platform envelope metadata from user messages (`src/gateway/chat-sanitize.ts`)
-- Reject null bytes and strip unsafe control characters (`src/gateway/server-methods/chat.ts:218`)
+- Reject null bytes and strip unsafe control characters (`src/gateway/server-methods/chat.ts:228`)
 
 2) **Identity + authorization**
 - Resolve sender identity.

04-privacy-safety/detecting-openclaw-requests.md

@@ -169,7 +169,7 @@ headers: {
 - **SSRF guard behavior:** The internal SSRF guard may produce distinctive redirect-following or timing patterns.
 - **Static version:** The hardcoded Chrome 122 version string will become increasingly stale over time, making it detectable via version-age analysis.
 
-**Configurable:** Yes — `tools.web.fetch.userAgent` in the config (`src/config/types.tools.ts:502`).
+**Configurable:** Yes — `tools.web.fetch.userAgent` in the config (`src/config/types.tools.ts:508`).
 
 ---
 

04-privacy-safety/hardening-checklist.md

@@ -340,7 +340,7 @@ for line in sys.stdin:
 "
 ```
 
-Source: `src/config/io.ts:495-538` (audit helpers), `src/config/io.ts:1187-1237` (audit record builder)
+Source: `src/config/io.ts:511-538` (audit helpers), `src/config/io.ts:1187-1237` (audit record builder)
 
 See: [AI Self-Misconfiguration Guide](../05-worst-case-security/ai-self-misconfiguration.md), [Attack #28](../05-worst-case-security/prompt-injection-attacks.md#-attack-28-config-self-modification-via-gateway-tool)
 

05-worst-case-security/ai-self-misconfiguration.md

@@ -123,7 +123,7 @@ The system prompt example above is one instance of a broader pattern: **OpenClaw
 | System prompt | `src/agents/system-prompt.ts:484` | Soft — model can ignore |
 | SKILL.md instructions | Skill directories | Soft — model can ignore |
 | CLAUDE.md project rules | Project root | Soft — model can ignore |
-| Tool allowlist (`tools.exec.security: "allowlist"`) | Config (`src/config/types.tools.ts:184`) | **Hard — code enforced** |
+| Tool allowlist (`tools.exec.security: "allowlist"`) | Config (`src/config/types.tools.ts:232`) | **Hard — code enforced** |
 | Tool profiles (`"coding"`) | `src/agents/tool-policy.ts:63-80` | **Hard — code enforced** |
 | `set -euo pipefail` in scripts | Shell | **Hard — shell enforced** |
 | PreToolUse hooks | `.claude/hooks/` | **Hard — hook enforced** |
@@ -1048,12 +1048,12 @@ OpenClaw has several built-in protections. Understanding them helps you build on
 | **Dangerous env var blocklist** | Blocks `LD_PRELOAD`, `NODE_OPTIONS`, etc. from being set via exec tools | `src/agents/bash-tools.exec-runtime.ts:40-54` |
 | **Small model risk audit** | Warns when small/older models have tool access | `src/security/audit-extra.sync.ts:1088-1177` |
 | **ALLOWED_FILE_NAMES** | Restricts which agent bootstrap files can be modified via `agents.files.set` | `src/gateway/server-methods/agents.ts:66` |
-| **File permissions** | Config files created with `0o600`, directories with `0o700` | `src/config/io.ts:1121,1247` |
+| **File permissions** | Config files created with `0o600`, directories with `0o700` | `src/config/io.ts:1137,1263` |
 | **Tool profiles** | `"coding"` profile excludes the gateway tool entirely | `src/agents/tool-policy.ts:63-80` |
 | **System prompt warning** | Soft instruction to not run `config.apply` without user request | `src/agents/system-prompt.ts:480` |
 | **Restart sentinel** | Logs timestamp, session key, message, and stats on config-triggered restarts | `src/infra/restart-sentinel.ts:30-48` |
 | **Strict schema validation** | Zod `.strict()` rejects unknown top-level keys and type errors | `src/config/zod-schema.ts:879` |
-| **Forensic config write audit** | Every config write logged to `config-audit.jsonl` with PID, PPID, CWD, argv, content hashes, byte sizes, gateway-mode changes, and anomaly flags (size drops >50%, missing meta, gateway-mode removal) | `src/config/io.ts:495-538` (audit helpers), `:1177-1227` (audit record builder + append) |
+| **Forensic config write audit** | Every config write logged to `config-audit.jsonl` with PID, PPID, CWD, argv, content hashes, byte sizes, gateway-mode changes, and anomaly flags (size drops >50%, missing meta, gateway-mode removal) | `src/config/io.ts:511-538` (audit helpers), `:1177-1227` (audit record builder + append) |
 
 ---
 

05-worst-case-security/operational-gotchas.md

@@ -589,7 +589,7 @@ set -euo pipefail
 
 # 3. Use tool security modes
 # tools.exec.security: "allowlist" restricts which commands models can run
-# Source: src/config/types.tools.ts:231
+# Source: src/config/types.tools.ts:232
 openclaw config set tools.exec.security allowlist
 
 # 4. Test model instruction-following before trusting with destructive ops

05-worst-case-security/prompt-injection-attacks.md

@@ -957,8 +957,8 @@ Alice
 
 **OpenClaw's Defense:**
 OpenClaw wraps external hook content (including emails) with security boundaries:
-- `buildSafeExternalPrompt()` at `src/cron/isolated-agent/run.ts:386-394`
-- Suspicious pattern detection and logging at `src/cron/isolated-agent/run.ts:374-381`
+- `buildSafeExternalPrompt()` at `src/cron/isolated-agent/run.ts:453-462`
+- Suspicious pattern detection and logging at `src/cron/isolated-agent/run.ts:444-450`
 - External content wrapped with `<<<EXTERNAL_UNTRUSTED_CONTENT>>>` markers and security warnings (`src/security/external-content.ts:47-64`)
 
 **Additional Defense:**

06-optimizations/resource-usage.md

@@ -37,7 +37,7 @@ Users report OpenClaw can be resource-intensive. This guide documents every reso
 | 11 | **Memory sync** — file hashing + markdown chunking + embedding + SQLite FTS5/vec indexing | `src/memory/manager.ts:380+` | Medium (periodic) | Like re-indexing a library catalog — scanning, categorizing, and filing every document |
 | 12 | **TTS generation** — ElevenLabs/OpenAI/Edge TTS API calls + audio buffer handling | `src/tts/tts.ts:557-724` | Medium | API calls are remote but audio buffer conversion is local CPU work |
 | 13 | **Agent execution loop** — continuous model response processing | `src/auto-reply/reply/agent-runner-execution.ts:74` | Medium (continuous) | The main "brain" loop — always running while the bot is responding |
-| 14 | **Cron timer loop** — re-arming `setTimeout` for scheduled job processing | `src/cron/service/timer.ts:533` | Low (idle) | Like a clock ticking in the background — minimal CPU unless jobs are firing |
+| 14 | **Cron timer loop** — re-arming `setTimeout` for scheduled job processing | `src/cron/service/timer.ts:547` | Low (idle) | Like a clock ticking in the background — minimal CPU unless jobs are firing |
 
 ### Other CPU consumers
 
@@ -58,7 +58,7 @@ Users report OpenClaw can be resource-intensive. This guide documents every reso
 - `src/memory/qmd-manager.ts` — QMD process output is now unbounded (the previous `appendOutputWithCap()` output cap was removed; `MAX_QMD_OUTPUT_CHARS` no longer exists). The `resolveSpawnInvocation()` helper at `:72` handles Windows-compatible spawn routing.
 
 **Media fetch buffering:**
-- `src/media/fetch.ts:132-148` — media fetch is now **bounded** when `maxBytes` is specified: `readResponseWithLimit()` (`src/media/read-response-with-limit.ts`) streams chunk-by-chunk and aborts early on overflow, preventing unbounded memory consumption. Falls back to unbounded `arrayBuffer()` only when no limit is specified (e.g., document fetches without size constraints).
+- `src/media/fetch.ts:137-159` — media fetch is now **bounded** when `maxBytes` is specified: `readResponseWithLimit()` (`src/media/read-response-with-limit.ts`) streams chunk-by-chunk and aborts early on overflow, preventing unbounded memory consumption. Falls back to unbounded `arrayBuffer()` only when no limit is specified (e.g., document fetches without size constraints).
 
 ---
 
@@ -74,9 +74,9 @@ Users report OpenClaw can be resource-intensive. This guide documents every reso
 | Discord presence cache | `src/discord/monitor/presence-cache.ts:9` | 5000/account LRU | Low |
 | Telegram sent message cache | `src/telegram/sent-message-cache.ts:12` | 24h TTL, 100/chat | Low-Medium |
 | History map | `src/auto-reply/reply/history.ts:7` | 1000 keys LRU | Well bounded |
-| Inbound dedupe | `src/auto-reply/reply/inbound-dedupe.ts:8` | 5000 max, 20min TTL | Well bounded |
+| Inbound dedupe | `src/auto-reply/reply/inbound-dedupe.ts:9` | 5000 max, 20min TTL | Well bounded |
 | Gateway dedupe | `src/gateway/server-constants.ts:33-34` | 1000 max, 5min TTL | Well bounded |
-| Browser roleRefs | `src/browser/pw-session.ts:109-110` | 50 max LRU | Well bounded |
+| Browser roleRefs | `src/browser/pw-session.ts:112-113` | 50 max LRU | Well bounded |
 | Followup queues | `src/auto-reply/reply/queue/state.ts:18` | 20/queue, no queue count cap; `clearFollowupQueue()` (`queue/cleanup.ts:24`) clears individual queues during session cleanup | **Partially mitigated** — individual queues can be cleared but total queue-map still uncapped |
 | Agent event seqByRun | `src/infra/agent-events.ts:23` | **No cleanup** (`seqByRun` never pruned; `runContextById` now cleaned via `clearAgentRunContext()` at `:49`) | **Partial leak** — `runContextById` fixed, `seqByRun` still leaks |
 | Agent run sequence | `src/gateway/server-runtime-state.ts:198` | **No pruning** (maintenance timer skips it) | **Leak risk** |
@@ -93,10 +93,10 @@ Users report OpenClaw can be resource-intensive. This guide documents every reso
 
 ### Browser memory
 
-- **Chromium instance** (Playwright CDP): `src/browser/pw-session.ts:116` — singleton, but Chromium itself can consume **200MB to 2GB+**
+- **Chromium instance** (Playwright CDP): `src/browser/pw-session.ts:119` — singleton, but Chromium itself can consume **200MB to 2GB+**
   > *Like having a full web browser running invisibly in the background — it alone can use more memory than everything else combined.*
-- Per-page state caps: console (500), errors (200), network requests (500) — `src/browser/pw-session.ts:112-114`
-- WeakMaps used for page/context state (GC-friendly): `src/browser/pw-session.ts:102-105`
+- Per-page state caps: console (500), errors (200), network requests (500) — `src/browser/pw-session.ts:115-117`
+- WeakMaps used for page/context state (GC-friendly): `src/browser/pw-session.ts:105-108`
 
 ### Model context accumulation
 

08-security-analysis/hudson-rock-infostealer-analysis.md

@@ -47,7 +47,7 @@
 
 | # | Article Claim | Verdict | Codebase Evidence |
 |---|---------------|---------|-------------------|
-| 1 | `openclaw.json` contains gateway token | **CONFIRMED** | `gateway.auth.token` field; stored as plaintext JSON5 with `0o600` perms (`src/config/io.ts:1239`) |
+| 1 | `openclaw.json` contains gateway token | **CONFIRMED** | `gateway.auth.token` field; stored as plaintext JSON5 with `0o600` perms (`src/config/io.ts:1263`) |
 | 2 | `openclaw.json` contains email address | **LIKELY** | `auth.profiles.*.email` optional string field exists (`src/config/types.auth.ts:10`); OAuth profiles commonly include email |
 | 3 | `openclaw.json` contains workspace path | **CONFIRMED** | `agents[].dir` field configures workspace directories |
 | 4 | `device.json` contains crypto keys | **CONFIRMED** | ED25519 private + public key pair, device ID (SHA256 fingerprint) (`src/infra/device-identity.ts:57-63`); stored at `~/.openclaw/identity/device.json` (`src/infra/device-identity.ts:20-21`) with `0o600` perms (`src/infra/device-identity.ts:84,116-118`) |

08-security-analysis/issue-1796-argus-audit.md

@@ -16,7 +16,7 @@ All four AI-generated summaries in this project covered the report. The followin
 | [Gemini 3.0 Pro](../explain-clawdbot-gemini-3.0-pro/README.md) | Brief index entry only; lists "race conditions" as a key risk | **Inaccurate on race conditions** -- code uses `withFileLock()` from `src/infra/file-lock.ts` with PID-based stale detection; no race exists |
 | [Kimi K2.5](../explain-clawdbot-kilocode-kimi-k2.5/security-analysis.md#github-issue-1796-argus-security-audit) | Detailed 8-claim breakdown with code snippets, scanner statistics, remediation advice | **Inaccurate** -- accepts all 8 CRITICAL claims at face value; does not verify against source code; presents "plaintext storage" and "hardcoded secrets" as vulnerabilities rather than standard CLI practice per RFC 8252 |
 
-**Key disagreement resolved:** Gemini 3.0 Pro accepted the race condition claim at face value. Code review (`src/agents/auth-profiles/oauth.ts:158` for `refreshOAuthTokenWithLock()`, config in `constants.ts:12`) confirms locking is correctly implemented. The other three models correctly identified this as a false positive.
+**Key disagreement resolved:** Gemini 3.0 Pro accepted the race condition claim at face value. Code review (`src/agents/auth-profiles/oauth.ts:154` for `refreshOAuthTokenWithLock()`, config in `constants.ts:12`) confirms locking is correctly implemented. The other three models correctly identified this as a false positive.
 
 **Additional disagreement (Kimi K2.5):** Kimi K2.5 presents all 8 CRITICAL findings as actual vulnerabilities requiring remediation, including recommending keychain integration for token storage and disabling `config.patch` entirely. Code review confirms: (1) token storage with `0o600` permissions is standard CLI practice per RFC 8252, (2) `config.patch` executes inside Docker containers with `no-new-privileges`, (3) DNS pinning (`src/infra/net/ssrf.ts:276-363`) prevents the SSRF chain Kimi K2.5 describes, and (4) RBAC (`src/gateway/server-methods.ts:98-155`) prevents agent self-approval. The remediation advice in Kimi K2.5 is well-intentioned but addresses non-existent vulnerabilities.
 
@@ -27,11 +27,11 @@ All four AI-generated summaries in this project covered the report. The followin
 | 1 | Plaintext OAuth token storage | **True, by design** | `src/infra/json-file.ts:22` sets `0o600` on every write. Standard for CLI tools (`gh`, `gcloud`). |
 | 2 | Missing CSRF in OAuth state | **False** | `extensions/google-gemini-cli-auth/oauth.ts:690` performs strict `state !== verifier` check. |
 | 3 | Hardcoded OAuth client secret | **True, standard practice** | [RFC 8252 Sections 8.4-8.5](https://datatracker.ietf.org/doc/html/rfc8252#section-8.4): CLI apps are "public clients." |
-| 4 | Token refresh race condition | **False** | `withFileLock()` from `src/infra/file-lock.ts` with PID-based stale detection, lock held throughout refresh+save (`src/agents/auth-profiles/oauth.ts:158`). |
+| 4 | Token refresh race condition | **False** | `withFileLock()` from `src/infra/file-lock.ts` with PID-based stale detection, lock held throughout refresh+save (`src/agents/auth-profiles/oauth.ts:154`). |
 | 5 | Insufficient file permission checks | **True, by design** | `0o600` on every write + `openclaw security audit`/`fix` tooling. |
 | 6 | Path traversal in agent dirs | **False** | Paths go through `resolveUserPath()` (`src/agents/agent-paths.ts:10,13`) which calls `path.resolve()` (`src/utils.ts:306,308`), normalizing traversal. IDs from env/config, not user input. |
 | 7 | Webhook signature bypass | **True, properly gated** | `skipVerification` in `extensions/voice-call/src/webhook-security.ts` requires explicit param; dev-only, off by default. |
-| 8 | Insufficient token expiry validation | **False** | `Date.now() < cred.expires` checked on every token use via inline checks (`src/agents/auth-profiles/oauth.ts:172,236`) and `tryResolveOAuthProfile()` (`src/agents/auth-profiles/oauth.ts:217-258`). |
+| 8 | Insufficient token expiry validation | **False** | `Date.now() < cred.expires` checked on every token use via inline checks (`src/agents/auth-profiles/oauth.ts:168,232`) and `tryResolveOAuthProfile()` (`src/agents/auth-profiles/oauth.ts:213-252`). |
 
 **Result: 0 of 8 CRITICAL claims are actual security vulnerabilities.**