diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json
index b37dc7504..02acb5496 100644
--- a/.openclaw-sync/source.json
+++ b/.openclaw-sync/source.json
@@ -1,5 +1,5 @@
 {
   "repository": "openclaw/openclaw",
-  "sha": "dabddb21655c45cbdac0f2b8f31f08b0db1c35fd",
-  "syncedAt": "2026-05-01T21:04:37.266Z"
+  "sha": "407c84e5737f01cecb1311498cfb023d70c9de41",
+  "syncedAt": "2026-05-01T21:12:57.526Z"
 }
diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md
index 4f3395e63..3dd3b67af 100644
--- a/docs/gateway/configuration.md
+++ b/docs/gateway/configuration.md
@@ -522,6 +522,12 @@ cannot roll back unrelated user settings.
     - **Unsupported write-through**: root includes, include arrays, and includes
       with sibling overrides fail closed for OpenClaw-owned writes instead of
       flattening the config
+    - **Confinement**: `$include` paths must resolve under the directory holding
+      `openclaw.json`. To share a tree across machines or users, set
+      `OPENCLAW_INCLUDE_ROOTS` to a path-list (`:` on POSIX, `;` on Windows) of
+      additional directories that includes may reference. Symlinks are resolved
+      and re-checked, so a path that lexically lives in a config dir but whose
+      real target escapes every allowed root is still rejected.
     - **Error handling**: clear errors for missing files, parse errors, and circular includes
 
   </Accordion>
diff --git a/docs/help/environment.md b/docs/help/environment.md
index e35996b2c..7a91acbbb 100644
--- a/docs/help/environment.md
+++ b/docs/help/environment.md
@@ -103,11 +103,12 @@ Both resolve from process env at activation time. SecretRef details are document
 
 ## Path-related env vars
 
-| Variable               | Purpose                                                                                                                                                                          |
-| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `OPENCLAW_HOME`        | Override the home directory used for all internal path resolution (`~/.openclaw/`, agent dirs, sessions, credentials). Useful when running OpenClaw as a dedicated service user. |
-| `OPENCLAW_STATE_DIR`   | Override the state directory (default `~/.openclaw`).                                                                                                                            |
-| `OPENCLAW_CONFIG_PATH` | Override the config file path (default `~/.openclaw/openclaw.json`).                                                                                                             |
+| Variable                 | Purpose                                                                                                                                                                          |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `OPENCLAW_HOME`          | Override the home directory used for all internal path resolution (`~/.openclaw/`, agent dirs, sessions, credentials). Useful when running OpenClaw as a dedicated service user. |
+| `OPENCLAW_STATE_DIR`     | Override the state directory (default `~/.openclaw`).                                                                                                                            |
+| `OPENCLAW_CONFIG_PATH`   | Override the config file path (default `~/.openclaw/openclaw.json`).                                                                                                             |
+| `OPENCLAW_INCLUDE_ROOTS` | Path-list of directories where `$include` directives may resolve files outside the config directory (default: none — `$include` is confined to the config dir). Tilde-expanded.  |
 
 ## Logging