docs: clarify docker sandbox mount paths (#3833)

Co-authored-by: ly-wang19 <ly-wang19@users.noreply.github.com>

backend/docs/CONFIGURATION.md

@@ -380,6 +380,27 @@ sandbox:
 
 `allow_host_bash` is intentionally `false` by default. DeerFlow's local sandbox is a host-side convenience mode, not a secure shell isolation boundary. If you need `bash`, prefer `AioSandboxProvider`. Only set `allow_host_bash: true` for fully trusted single-user local workflows.
 
+When `LocalSandboxProvider` runs under `make up`, it runs inside the `deer-flow-gateway` container. In that mode, `sandbox.mounts[].host_path` is resolved from the gateway container's filesystem, not from your Docker host. If you need a local-sandbox custom mount in production Docker, bind the host directory into the gateway service first, then use the in-container path in `config.yaml`:
+
+```yaml
+# docker/docker-compose.yaml or an override file
+services:
+  gateway:
+    volumes:
+      - ${DEER_FLOW_REPO_ROOT}/.deer-flow/knowledge:/app/.deer-flow/knowledge:ro
+```
+
+```yaml
+sandbox:
+  use: deerflow.sandbox.local:LocalSandboxProvider
+  mounts:
+    - host_path: /app/.deer-flow/knowledge
+      container_path: /mnt/knowledge
+      read_only: true
+```
+
+If the configured `host_path` is not visible to the gateway process, DeerFlow logs an error and ignores that mount.
+
 **Option 2: Docker Sandbox** (isolated, more secure):
 ```yaml
 sandbox:

frontend/src/content/en/harness/sandbox.mdx

@@ -163,6 +163,32 @@ sandbox:
   `/mnt/skills`, `/mnt/acp-workspace`, or `/mnt/user-data`.
 </Callout>
 
+When `LocalSandboxProvider` runs under production Docker (`make up`), the
+provider runs inside the `deer-flow-gateway` container. In that mode,
+`host_path` is resolved from the gateway container's filesystem, not directly
+from your Docker host. Bind the host directory into the gateway service first,
+then use the in-container path in `config.yaml`:
+
+```yaml
+# docker/docker-compose.yaml or an override file
+services:
+  gateway:
+    volumes:
+      - ${DEER_FLOW_REPO_ROOT}/.deer-flow/knowledge:/app/.deer-flow/knowledge:ro
+```
+
+```yaml
+sandbox:
+  use: deerflow.sandbox.local:LocalSandboxProvider
+  mounts:
+    - host_path: /app/.deer-flow/knowledge
+      container_path: /mnt/knowledge
+      read_only: true
+```
+
+If the configured `host_path` is not visible to the gateway process, DeerFlow
+logs an error and ignores that mount.
+
 ## Output truncation
 
 The sandbox tools limit output size to keep the agent's context manageable. These limits are configurable:

frontend/src/content/zh/harness/sandbox.mdx

@@ -153,6 +153,30 @@ sandbox:
   <code>/mnt/user-data</code>。
 </Callout>
 
+当 `LocalSandboxProvider` 运行在生产 Docker（`make up`）中时，它实际运行在
+`deer-flow-gateway` 容器里。此时 `host_path` 是从 gateway
+容器的文件系统解析，而不是直接从 Docker 宿主机解析。需要先把宿主机目录 bind
+mount 到 gateway 服务，再在 `config.yaml` 中使用容器内路径：
+
+```yaml
+# docker/docker-compose.yaml 或 override 文件
+services:
+  gateway:
+    volumes:
+      - ${DEER_FLOW_REPO_ROOT}/.deer-flow/knowledge:/app/.deer-flow/knowledge:ro
+```
+
+```yaml
+sandbox:
+  use: deerflow.sandbox.local:LocalSandboxProvider
+  mounts:
+    - host_path: /app/.deer-flow/knowledge
+      container_path: /mnt/knowledge
+      read_only: true
+```
+
+如果配置的 `host_path` 对 gateway 进程不可见，DeerFlow 会记录错误日志并忽略该挂载。
+
 ## 输出截断
 
 沙箱工具限制输出大小以保持 Agent 上下文可控。这些限制可配置：