diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json
index 6624fa1e3..5ab8665fe 100644
--- a/.openclaw-sync/source.json
+++ b/.openclaw-sync/source.json
@@ -1,5 +1,5 @@
 {
   "repository": "openclaw/openclaw",
-  "sha": "29741f696a74982cf79a2d98f2d6cc4e5c8ef93e",
-  "syncedAt": "2026-04-26T03:49:37.629Z"
+  "sha": "9ed11d6c49d800075cf5e1e923c28826942a77c6",
+  "syncedAt": "2026-04-26T04:01:15.793Z"
 }
diff --git a/docs/cli/gateway.md b/docs/cli/gateway.md
index 3237ac2aa..4c2cf0795 100644
--- a/docs/cli/gateway.md
+++ b/docs/cli/gateway.md
@@ -324,6 +324,7 @@ Command options:
 Notes:
 
 - `gateway install` supports `--port`, `--runtime`, `--token`, `--force`, `--json`.
+- Use `gateway restart` to restart a managed service. Do not chain `gateway stop` and `gateway start` as a restart substitute; on macOS, `gateway stop` intentionally disables the LaunchAgent before stopping it.
 - When token auth requires a token and `gateway.auth.token` is SecretRef-managed, `gateway install` validates that the SecretRef is resolvable but does not persist the resolved token into service environment metadata.
 - If token auth requires a token and the configured token SecretRef is unresolved, install fails closed instead of persisting fallback plaintext.
 - For password auth on `gateway run`, prefer `OPENCLAW_GATEWAY_PASSWORD`, `--password-file`, or a SecretRef-backed `gateway.auth.password` over inline `--password`.
diff --git a/docs/concepts/system-prompt.md b/docs/concepts/system-prompt.md
index 40521da24..660632f82 100644
--- a/docs/concepts/system-prompt.md
+++ b/docs/concepts/system-prompt.md
@@ -214,6 +214,10 @@ stale. The prompt also notes the public docs mirror, community Discord, and Claw
 ([https://clawhub.ai](https://clawhub.ai)) for skills discovery. It tells the model to
 consult docs first for OpenClaw behavior, commands, configuration, or architecture, and to
 run `openclaw status` itself when possible (asking the user only when it lacks access).
+For configuration specifically, it points agents to the `gateway` tool action
+`config.schema.lookup` for exact field-level docs and constraints, then to
+`docs/gateway/configuration.md` and `docs/gateway/configuration-reference.md`
+for broader guidance.
 
 ## Related
 
diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md
index 26a930ec2..8c8402aff 100644
--- a/docs/gateway/configuration-reference.md
+++ b/docs/gateway/configuration-reference.md
@@ -16,6 +16,11 @@ Code truth:
 - `config.schema.lookup` returns one path-scoped schema node for drill-down tooling
 - `pnpm config:docs:check` / `pnpm config:docs:gen` validate the config-doc baseline hash against the current schema surface
 
+Agent lookup path: use the `gateway` tool action `config.schema.lookup` for
+exact field-level docs and constraints before edits. Use
+[Configuration](/gateway/configuration) for task-oriented guidance and this page
+for the broader field map, defaults, and links to subsystem references.
+
 Dedicated deep references:
 
 - [Memory configuration reference](/reference/memory-config) for `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations`, and dreaming config under `plugins.entries.memory-core.config.dreaming`
diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md
index 14cd62e33..2d944edb4 100644
--- a/docs/gateway/configuration.md
+++ b/docs/gateway/configuration.md
@@ -21,6 +21,11 @@ If the file is missing, OpenClaw uses safe defaults. Common reasons to add a con
 
 See the [full reference](/gateway/configuration-reference) for every available field.
 
+Agents and automation should use `config.schema.lookup` for exact field-level
+docs before editing config. Use this page for task-oriented guidance and
+[Configuration reference](/gateway/configuration-reference) for the broader
+field map and defaults.
+
 <Tip>
 **New to configuration?** Start with `openclaw onboard` for interactive setup, or check out the [Configuration Examples](/gateway/configuration-examples) guide for complete copy-paste configs.
 </Tip>
@@ -575,6 +580,11 @@ For tooling that writes config over the gateway API, prefer this flow:
 - `config.apply` only when you intend to replace the entire config
 - `update.run` for explicit self-update plus restart
 
+Agents should treat `config.schema.lookup` as the first stop for exact
+field-level docs and constraints. Use [Configuration reference](/gateway/configuration-reference)
+when they need the broader config map, defaults, or links to dedicated
+subsystem references.
+
 <Note>
 Control-plane writes (`config.apply`, `config.patch`, `update.run`) are
 rate-limited to 3 requests per 60 seconds per `deviceId+clientIp`. Restart
diff --git a/docs/gateway/index.md b/docs/gateway/index.md
index 8af2ee77c..d527be86d 100644
--- a/docs/gateway/index.md
+++ b/docs/gateway/index.md
@@ -251,6 +251,8 @@ openclaw gateway restart
 openclaw gateway stop
 ```
 
+Use `openclaw gateway restart` for restarts. Do not chain `openclaw gateway stop` and `openclaw gateway start`; on macOS, `gateway stop` intentionally disables the LaunchAgent before stopping it.
+
 LaunchAgent labels are `ai.openclaw.gateway` (default) or `ai.openclaw.<profile>` (named profile). `openclaw doctor` audits and repairs service config drift.
 
   </Tab>
diff --git a/docs/tools/index.md b/docs/tools/index.md
index 53842f0c7..7e2d1293f 100644
--- a/docs/tools/index.md
+++ b/docs/tools/index.md
@@ -95,6 +95,8 @@ active runtime model label from the latest transcript usage entry.
 
 For partial changes, prefer `config.schema.lookup` then `config.patch`. Use
 `config.apply` only when you intentionally replace the entire config.
+For broader config docs, read [Configuration](/gateway/configuration) and
+[Configuration reference](/gateway/configuration-reference).
 The tool also refuses to change `tools.exec.ask` or `tools.exec.security`;
 legacy `tools.bash.*` aliases normalize to the same protected exec paths.