docs: Update environment variable configuration and setup documentation across various files. (#297)

Author: NikkeTryHard

.env.example

@@ -20,8 +20,9 @@ DEFAULT_CAMOUFOX_PORT=9222
 # =============================================================================
 
 # 自动保存认证信息 (Auto Save Auth)
-# 设置为 true 以在每次成功登录后自动保存认证状态 (cookies/localStorage)，无需人工确认。
-# 强烈建议在 headless 模式下开启，以便长期运行。
+# 设置为 true 以在成功登录后自动保存认证状态 (cookies/localStorage)，无需人工确认。
+# [IMPORTANT] 必须在 debug 模式下设置为 true 才能保存新的认证配置文件！
+# Headless 模式使用已保存的配置文件，不需要此设置。
 # Default: false
 AUTO_SAVE_AUTH=false
 

README.md

@@ -42,11 +42,12 @@ poetry install
 
 # 2️⃣ 配置环境
 cp .env.example .env
-nano .env  # 编辑配置（可选）
+nano .env  # 设置 AUTO_SAVE_AUTH=true 以保存认证
 
 # 3️⃣ 首次认证并启动
 poetry run python launch_camoufox.py --debug  # 首次认证（需登录 Google）
-# 认证成功后，Ctrl+C 停止，然后：
+# 认证成功后，将 auth_profiles/saved/*.json 移至 auth_profiles/active/
+# 然后：
 poetry run python launch_camoufox.py --headless
 ```
 

docker/README-Docker.md

@@ -25,7 +25,7 @@ Docker 部署提供了以下优势：
 ## 🔧 Docker 环境规格
 
 - **基础镜像**: Python 3.10-slim-bookworm (稳定且轻量)
-- **Python版本**: 3.10 (在容器内运行，与主机Python版本无关)
+- **Python 版本**: 3.10 (在容器内运行，与主机 Python 版本无关)
 - **依赖管理**: Poetry (现代化 Python 依赖管理)
 - **构建方式**: 多阶段构建 (builder + runtime)
 - **架构支持**: x86_64 和 ARM64 (Apple Silicon)
@@ -180,6 +180,7 @@ docker run -d \
    ```
 
    **`.env` 文件的优势:**
+
    - ✅ **版本更新无忧**: 一个 `git pull` 就完成更新，无需重新配置
    - ✅ **配置集中管理**: 所有配置项统一在 `.env` 文件中
    - ✅ **Docker 兼容**: 容器会自动读取挂载的 `.env` 文件
@@ -241,6 +242,8 @@ TRACE_LOGS_ENABLED=false
 
 # 认证配置
 AUTO_CONFIRM_LOGIN=true
+# 注意：AUTO_SAVE_AUTH 仅在 debug 模式下用于保存新认证文件
+# Docker 容器运行于 headless 模式，使用预先生成的认证文件，此设置无效
 AUTO_SAVE_AUTH=false
 AUTH_SAVE_TIMEOUT=30
 

docs/authentication-setup.md

@@ -24,8 +24,13 @@ DEFAULT_FASTAPI_PORT=2048
 STREAM_PORT=0
 LAUNCH_MODE=normal
 DEBUG_LOGS_ENABLED=true
+
+# [IMPORTANT] 必须设置为 true 才能保存认证配置文件！
+AUTO_SAVE_AUTH=true
 ```
 
+> [!WARNING] > `AUTO_SAVE_AUTH=true` 是保存认证配置文件的必要条件。如果设置为 `false`（默认值），登录成功后将不会保存认证状态。
+
 ```bash
 # 简化启动命令 (推荐)
 python launch_camoufox.py --debug

docs/env-variables-reference.md

@@ -181,7 +181,10 @@
 - **类型**: 布尔值
 - **默认值**: `false`
 - **示例**: `AUTO_SAVE_AUTH=true`
-- **说明**: 启用后会自动保存 Google 认证 Cookie 到 `auth_profiles/` 目录
+- **说明**: 启用后会自动保存 Google 认证 Cookie 到 `auth_profiles/saved/` 目录
+
+> [!WARNING]
+> 必须在 **debug 模式** 下设置为 `true` 才能保存新的认证配置文件！Headless 模式使用已保存的配置文件，此设置对其无效。
 
 ### AUTH_SAVE_TIMEOUT
 

docs/environment-configuration.md

@@ -108,6 +108,7 @@ SERVER_REDIRECT_PRINT=false
 
 ```env
 # 自动保存认证信息
+# [IMPORTANT] 必须在 debug 模式下设置为 true 才能保存新的认证配置文件！
 AUTO_SAVE_AUTH=false
 
 # 认证保存超时时间 (秒)
@@ -117,6 +118,8 @@ AUTH_SAVE_TIMEOUT=30
 ONLY_COLLECT_CURRENT_USER_ATTACHMENTS=false
 ```
 
+> [!WARNING] > `AUTO_SAVE_AUTH=true` 是在 debug 模式下保存认证配置文件的必要条件。首次设置时请务必启用此选项。Headless 模式使用已保存的配置文件，此设置对其无效。
+
 ### 浏览器配置
 
 ```env

docs/quick-start-guide.md

@@ -184,6 +184,15 @@ SERVER_LOG_LEVEL=INFO
 
 首次运行需要进行 Google 账号认证，获取访问 AI Studio 所需的 Cookie。
 
+### 配置认证保存
+
+在 `.env` 文件中确保设置了自动保存认证：
+
+```env
+# [IMPORTANT] 必须设置为 true 才能保存认证配置文件！
+AUTO_SAVE_AUTH=true
+```
+
 ### 使用调试模式认证
 
 ```bash
@@ -196,13 +205,22 @@ poetry run python launch_camoufox.py --debug
 1. **浏览器窗口打开** - Camoufox 浏览器会自动打开
 2. **登录 Google 账号** - 在浏览器中登录您的 Google 账号
 3. **访问 AI Studio** - 浏览器会自动导航到 AI Studio 页面
-4. **等待保存** - 认证信息会自动保存到 `auth_profiles/active/` 目录
+4. **等待保存** - 认证信息会自动保存到 `auth_profiles/saved/` 目录
 5. **查看日志** - 终端会显示认证文件保存成功的消息
 
 **成功标志**:
 
 ```
-✅ 认证文件已保存到: auth_profiles/active/XXXXXXXX.json
+✅ 认证文件已保存到: auth_profiles/saved/XXXXXXXX.json
+```
+
+### 激活认证文件
+
+将保存的认证文件移动到 `active` 目录：
+
+```bash
+# 将认证文件从 saved 移到 active
+mv auth_profiles/saved/*.json auth_profiles/active/
 ```
 
 ### 关闭调试模式

launcher/config.py

@@ -31,7 +31,7 @@
 SAVED_AUTH_DIR = os.path.join(AUTH_PROFILES_DIR, "saved")
 LOG_DIR = os.path.join(os.path.dirname(os.path.dirname(__file__)), "logs")
 LAUNCHER_LOG_FILE_PATH = os.path.join(LOG_DIR, "launch_app.log")
-DIRECT_LAUNCH = os.environ.get("DIRECT_LAUNCH", False)
+DIRECT_LAUNCH = os.environ.get("DIRECT_LAUNCH", "").lower() in ("true", "1", "yes")
 
 # --- WebSocket 端点正则表达式 ---
 import re