diff --git a/docs/design/13-toolchain-and-dev-workflow.md b/docs/design/13-toolchain-and-dev-workflow.md
index b32a221..b2af4f2 100644
--- a/docs/design/13-toolchain-and-dev-workflow.md
+++ b/docs/design/13-toolchain-and-dev-workflow.md
@@ -468,7 +468,32 @@ CI 临时测试环境（每次 CI 自动创建）
 
 **效果**：E2E 可以在每次 PR 到 main 时自动跑，无需担心污染生产数据或影响生产服务。
 
-**环境总结**：
+#### 隔离边界：程序逻辑 vs Agent 交互
+
+| 层面 | 隔离方式 | 说明 |
+|------|---------|------|
+| **程序逻辑**（FastAPI + Daemon + SQLite） | ✅ 完全隔离 | 独立 venv + 临时数据库 + 临时端口 |
+| **Agent spawn**（openclaw agent） | ❌ 走生产 openclaw | openclaw 是全局单例，无法隔离 |
+
+Agent spawn 走生产 openclaw 的决策理由：
+1. openclaw 是全局单例（`~/.openclaw/` 只有一份），Agent 配置和 workspace 全局共享
+2. 测试 case 会标识测试上下文，Agent 记忆混淆风险低
+3. 完全隔离需要在 Docker 中跑独立 openclaw，维护成本不值得
+4. Agent 的 API 回写地址由 spawn message 传入，指向 CI 临时服务的端口 8084
+
+#### 路径硬编码修复清单
+
+当前代码有 6 处硬编码绝对路径，需改为环境变量可配置（P1 必须完成）：
+
+| 位置 | 硬编码路径 | 改法 | 现状 |
+|------|-----------|------|------|
+| `utils.py` | 数据根目录 | `BLACKBOARD_ROOT` 环境变量 | ✅ 已支持 |
+| `bootstrap.py:42` | Skill 加载路径 | `MOZI_SKILL_PATH` 环境变量 | ✅ 已支持 |
+| `registry.py:264` | 项目扫描目录 `~/.openclaw/sanguo_projects` | 加 `SANGUO_PROJECTS_DIR` | ❌ 硬编码 |
+| `spawner.py:1177,1261` | `~/.openclaw/agents/<id>/sessions.json` | 加 `OPENCLAW_HOME` | ❌ 硬编码 |
+| `blackboard_routes.py:161` | `~/.openclaw/openclaw.json` | 从 `OPENCLAW_HOME` 读 | ❌ 硬编码 |
+
+#### 环境总结
 
 | 环境 | 位置 | 用途 | 生命周期 |
 |------|------|------|---------|