diff --git a/docs/content/assistants/configuration.md b/docs/content/assistants/configuration.md
index da28d1e..962c63f 100644
--- a/docs/content/assistants/configuration.md
+++ b/docs/content/assistants/configuration.md
@@ -98,6 +98,111 @@
 - `tool.called` - 工具被调用
 - `human.transfer` - 转人工
 
+## 配置持久化与运行时覆盖
+
+助手配置分为两层：
+
+1. **数据库持久化配置（基线配置）**：通过助手管理 API 保存，后续会话默认读取这一层。
+2. **会话级覆盖配置（runtime overrides）**：仅对当前 WebSocket 会话生效，不会写回数据库。
+
+### 哪些配置会存到数据库
+
+以下字段会持久化在 `assistants` / `assistant_opener_audio` 等表中（通过创建/更新助手写入）：
+
+| 类别 | 典型字段 |
+|------|---------|
+| 对话行为 | `name`、`prompt`、`opener`、`firstTurnMode`、`generatedOpenerEnabled` |
+| 输出与打断 | `voiceOutputEnabled`、`voice`、`speed`、`botCannotBeInterrupted`、`interruptionSensitivity` |
+| 工具与知识库 | `tools`、`knowledgeBaseId` |
+| 模型与外部模式 | `configMode`、`apiUrl`、`apiKey`、`llmModelId`、`asrModelId`、`embeddingModelId`、`rerankModelId` |
+| 开场音频 | `openerAudioEnabled` 及音频文件状态（`ready`、`durationMs` 等） |
+
+> 引擎在连接时通过 `assistant_id` 从后端读取该助手的 `sessionStartMetadata` 作为默认运行配置。
+
+### 哪些配置可以在会话中覆盖
+
+客户端可在 `session.start.metadata.overrides` 中覆盖以下白名单字段（仅当前会话有效）：
+
+- `systemPrompt`
+- `greeting`
+- `firstTurnMode`
+- `generatedOpenerEnabled`
+- `output`
+- `bargeIn`
+- `knowledgeBaseId`
+- `knowledge`
+- `tools`
+- `openerAudio`
+
+以下字段不能由客户端覆盖：
+
+- `services`（模型 provider / apiKey / baseUrl 等）
+- `assistantId` / `appId` / `configVersionId`（及下划线变体）
+- 包含密钥语义的字段（如 `apiKey`、`token`、`secret`、`password`、`authorization`）
+
+### 覆盖示例（代码）
+
+下面示例展示「数据库基线配置 + 会话 overrides」的最终效果。
+
+```json
+// 1) 数据库存储的基线配置（示意）
+// GET /api/v1/assistants/asst_demo/config -> sessionStartMetadata
+{
+  "systemPrompt": "你是电商客服助手，回答要简洁。",
+  "greeting": "你好，我是你的客服助手。",
+  "firstTurnMode": "bot_first",
+  "output": { "mode": "audio" },
+  "knowledgeBaseId": "kb_orders",
+  "tools": [
+    { "type": "function", "function": { "name": "query_order" } }
+  ]
+}
+```
+
+```json
+// 2) 客户端发起会话时的覆盖
+{
+  "type": "session.start",
+  "metadata": {
+    "channel": "web",
+    "history": { "userId": 1001 },
+    "overrides": {
+      "greeting": "你好，我来帮你查订单进度。",
+      "output": { "mode": "text" },
+      "knowledgeBaseId": "kb_vip_orders",
+      "tools": [
+        { "type": "function", "function": { "name": "query_vip_order" } }
+      ]
+    }
+  }
+}
+```
+
+```json
+// 3) 引擎合并后的有效配置（示意）
+{
+  "assistantId": "asst_demo",
+  "systemPrompt": "你是电商客服助手，回答要简洁。",
+  "greeting": "你好，我来帮你查订单进度。",
+  "firstTurnMode": "bot_first",
+  "output": { "mode": "text" },
+  "knowledgeBaseId": "kb_vip_orders",
+  "tools": [
+    { "type": "function", "function": { "name": "query_vip_order" } }
+  ],
+  "channel": "web",
+  "history": { "userId": 1001 }
+}
+```
+
+合并规则可简化为：
+
+```python
+effective = {**db_session_start_metadata, **metadata.overrides}
+```
+
+当 `WS_EMIT_CONFIG_RESOLVED=true` 时，服务端会返回 `config.resolved`（公开、安全裁剪后的快照）用于前端调试当前生效配置。
+
 ## 配置导入导出
 
 ### 导出配置
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 3912233..160adc2 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -30,17 +30,17 @@ nav:
       - 配置选项: assistants/configuration.md
       - 提示词指南: assistants/prompts.md
       - 测试调试: assistants/testing.md
-  - 功能定制:
-      - 知识库: customization/knowledge-base.md
-      - 工具集成: customization/tools.md
-      - 语音配置: customization/voices.md
-      - 模型配置: customization/models.md
-      - 工作流: customization/workflows.md
-  - 数据分析:
-      - 仪表盘: analysis/dashboard.md
-      - 历史记录: analysis/history.md
-      - 效果评估: analysis/evaluation.md
-      - 自动化测试: analysis/autotest.md
+      - 功能定制:
+          - 知识库: customization/knowledge-base.md
+          - 工具集成: customization/tools.md
+          - 语音配置: customization/voices.md
+          - 模型配置: customization/models.md
+          - 工作流: customization/workflows.md
+      - 数据分析:
+          - 仪表盘: analysis/dashboard.md
+          - 历史记录: analysis/history.md
+          - 效果评估: analysis/evaluation.md
+          - 自动化测试: analysis/autotest.md
   - API 参考:
       - 概述: api-reference/index.md
       - WebSocket 协议: api-reference/websocket.md