diff --git a/.env.example b/.env.example
index 23a609a..e072f3d 100644
--- a/.env.example
+++ b/.env.example
@@ -4,7 +4,13 @@
 DEBUG=True
 APP_ENV=development
 
-# docker build args
+# Frontend API URL (used as Docker build arg for Next.js)
+# This is a BUILD-TIME variable: it gets embedded into the frontend JS bundle during build.
+# Default works for local development (localhost). For remote/LAN deployment, change to your host IP or domain:
+#   NEXT_PUBLIC_API_URL=http://192.168.1.100:8000/api
+#   NEXT_PUBLIC_API_URL=https://your-domain.com/api
+# Note: When using docker-compose, only this root .env is used (not web/.env).
+# If you change this value after building, you must rebuild: docker compose build
 NEXT_PUBLIC_API_URL="http://localhost:8000/api"
 
 AGENT_RECURSION_LIMIT=30
diff --git a/README.md b/README.md
index d3b3b61..450cbf0 100644
--- a/README.md
+++ b/README.md
@@ -523,7 +523,34 @@ docker stop deer-flow-api-app
 
 ### Docker Compose (include both backend and frontend)
 
-DeerFlow provides a docker-compose setup to easily run both the backend and frontend together:
+DeerFlow provides a docker-compose setup to easily run both the backend and frontend together.
+
+#### Configuration
+
+Before building, configure the root `.env` file (copied from `.env.example`):
+
+```bash
+cp .env.example .env
+cp conf.yaml.example conf.yaml
+```
+
+> [!IMPORTANT]
+> The `docker-compose.yml` only uses the **root `.env`** file (not `web/.env`). You do **not** need to create or modify `web/.env` when using Docker Compose.
+
+If you are deploying on a **remote server** or accessing from a **LAN IP** (not `localhost`), you **must** update `NEXT_PUBLIC_API_URL` in the root `.env` to your actual host IP or domain:
+
+```bash
+# Example: accessing from LAN IP
+NEXT_PUBLIC_API_URL=http://192.168.1.100:8000/api
+
+# Example: remote deployment with domain
+NEXT_PUBLIC_API_URL=https://your-domain.com/api
+```
+
+> [!NOTE]
+> `NEXT_PUBLIC_API_URL` is a **build-time** variable for Next.js — it gets embedded into the frontend JavaScript bundle during `docker compose build`. If you change this value later, you must rebuild with `docker compose build` for the change to take effect.
+
+#### Build and Run
 
 ```bash
 # building docker image
@@ -534,7 +561,7 @@ docker compose up
 ```
 
 > [!WARNING]
-> If you want to deploy the deer flow into production environments, please add authentication to the website and evaluate your security check of the MCPServer and Python Repl. 
+> If you want to deploy the deer flow into production environments, please add authentication to the website and evaluate your security check of the MCPServer and Python Repl.
 
 ## Examples
 
diff --git a/README_zh.md b/README_zh.md
index a6baf6b..72333f8 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -476,7 +476,34 @@ docker stop deer-flow-api-app
 
 ### Docker Compose
 
-您也可以使用 docker compose 设置此项目：
+您也可以使用 docker compose 同时运行后端和前端。
+
+#### 配置
+
+构建前，先配置根目录的 `.env` 文件（从 `.env.example` 复制）：
+
+```bash
+cp .env.example .env
+cp conf.yaml.example conf.yaml
+```
+
+> [!IMPORTANT]
+> `docker-compose.yml` 只使用**根目录的 `.env`** 文件（不使用 `web/.env`）。使用 Docker Compose 时，您**不需要**创建或修改 `web/.env`。
+
+如果您在**远程服务器**上部署或通过**局域网 IP**（非 `localhost`）访问，**必须**将根目录 `.env` 中的 `NEXT_PUBLIC_API_URL` 修改为实际的主机 IP 或域名：
+
+```bash
+# 示例：通过局域网 IP 访问
+NEXT_PUBLIC_API_URL=http://192.168.1.100:8000/api
+
+# 示例：使用域名的远程部署
+NEXT_PUBLIC_API_URL=https://your-domain.com/api
+```
+
+> [!NOTE]
+> `NEXT_PUBLIC_API_URL` 是 Next.js 的**构建时**变量——它会在 `docker compose build` 时被嵌入到前端 JavaScript 包中。如果之后修改了此值，必须重新执行 `docker compose build` 才能生效。
+
+#### 构建和运行
 
 ```bash
 # 构建docker镜像