diff --git a/docs/content/docs/overview/local-codex-canvas.mdx b/docs/content/docs/overview/local-codex-canvas.mdx
new file mode 100644
index 0000000..0cdf2eb
--- /dev/null
+++ b/docs/content/docs/overview/local-codex-canvas.mdx
@@ -0,0 +1,173 @@
+---
+title: 本地 Codex 连接画布原理
+description: 说明 Canvas Agent、MCP、SSE 和浏览器画布之间如何交互
+---
+
+# 本地 Codex 连接画布原理
+
+本地 Codex 连接画布的核心不是让 Codex 直接控制浏览器，也不是模拟鼠标点击或操作 DOM，而是在用户电脑上运行一个 `Canvas Agent` 作为桥接服务。
+
+```txt
+Codex / 浏览器侧边栏
+        |
+        v
+本机 Canvas Agent
+        |
+        v
+浏览器画布 React 状态
+```
+
+真正的画布数据仍然在浏览器里，节点、连线、选区和视口都由前端 React 状态维护。Codex 只能通过 `Canvas Agent` 暴露的工具协议发出“读取画布”或“执行画布操作”的请求。
+
+## 两个使用方向
+
+### 1. 本地 Codex 主动连接画布
+
+这个方向的入口在 Codex。
+
+```txt
+本地 Codex
+  -> infinite-canvas MCP 工具
+  -> 本机 Canvas Agent
+  -> 浏览器画布
+```
+
+用户在本地 Codex 里发起请求，例如读取画布、创建文本节点、连接节点或触发生成。Codex 调用 `infinite-canvas` MCP 工具，MCP 工具再请求本机 `Canvas Agent` 的 `/api/tools` 接口。
+
+常见工具包括：
+
+- `canvas_get_state`：读取当前画布摘要。
+- `canvas_get_selection`：读取当前选区。
+- `canvas_apply_ops`：批量执行画布操作。
+- `canvas_create_text_node`：创建文本节点。
+- `canvas_generate_image` / `canvas_generate_text`：创建生成流程并触发生成。
+- `canvas_update_node` / `canvas_connect_nodes`：更新节点或连接节点。
+
+这条链路适合在 Codex 对话里直接让 Codex 操作当前打开的画布。
+
+### 2. 浏览器右侧面板主动打开 Codex
+
+这个方向的入口在浏览器。
+
+```txt
+浏览器右侧 Codex 面板
+  -> 本机 Canvas Agent
+  -> Codex app-server --stdio
+  -> infinite-canvas MCP 工具
+  -> 本机 Canvas Agent
+  -> 浏览器画布
+```
+
+用户在网页右侧面板输入提示词后，浏览器把请求发送到 `Canvas Agent` 的 `/agent/codex/turn` 接口。`Canvas Agent` 会在本机启动或复用 `codex app-server --stdio`，并给这个 Codex 会话注入同一套 `infinite-canvas` MCP 工具。
+
+所以即使入口在浏览器右侧面板，真正改动画布时仍然会回到同一条工具链路：
+
+```txt
+Codex -> MCP -> Canvas Agent -> 浏览器画布
+```
+
+右侧面板只是把“打开 Codex 会话、发送 prompt、展示流式事件”这件事搬到了网页里。
+
+## 浏览器和 Canvas Agent 如何连接
+
+`Canvas Agent` 默认监听本机地址：
+
+```txt
+http://127.0.0.1:17371
+```
+
+启动后会生成 `Connect token`，网页连接时必须携带 token。浏览器连接后会建立一条 SSE 长连接：
+
+```txt
+GET /events?token=xxx&clientId=xxx
+```
+
+连接成功后，`Canvas Agent` 会发送 `hello` 事件，浏览器把状态更新为已连接。
+
+## 画布状态如何同步给 Codex
+
+浏览器会把当前画布快照主动同步给 `Canvas Agent`：
+
+```txt
+POST /canvas/state?token=xxx&clientId=xxx
+```
+
+快照包含：
+
+- 当前画布 ID 和标题；
+- 节点列表；
+- 连线列表；
+- 当前选中的节点 ID；
+- 当前视口位置和缩放。
+
+`Canvas Agent` 把最近一次快照保存在内存里。Codex 调用 `canvas_get_state` 时，读取的是这份由浏览器同步过来的最新快照，而不是直接读取浏览器 DOM。
+
+## Codex 如何操作画布
+
+以创建文本节点为例，流程如下：
+
+```txt
+Codex 调 canvas_create_text_node
+  -> MCP POST /api/tools
+  -> Canvas Agent 转成 canvas_apply_ops
+  -> Canvas Agent 通过 SSE 发送 tool_call
+  -> 浏览器执行 add_node
+  -> 浏览器 POST /canvas/result
+  -> Canvas Agent 返回结果给 Codex
+```
+
+`Canvas Agent` 会把一些高级工具转换成统一的画布操作：
+
+```json
+{
+  "ops": [
+    {
+      "type": "add_node",
+      "nodeType": "text",
+      "metadata": {
+        "content": "文本内容",
+        "status": "success"
+      }
+    }
+  ]
+}
+```
+
+浏览器收到 `tool_call` 后，调用前端的 `applyCanvasAgentOps`，在 React 状态中执行 `add_node`、`update_node`、`delete_node`、`connect_nodes`、`set_viewport`、`select_nodes` 等操作。执行完成后再把结果通过 `/canvas/result` 回传给 `Canvas Agent`。
+
+## 工具确认和撤销
+
+为了避免 Codex 直接改动画布，浏览器侧对 `canvas_apply_ops` 默认有二次确认机制。收到写操作后，右侧面板会先展示待执行工具调用，用户确认后才真正应用到画布。
+
+执行后，前端会保存最近一次操作前的画布快照，用于撤销上一轮 Agent 工具操作。
+
+如果关闭工具确认，本地 Codex 可以直接执行画布工具调用，但仍然是通过同一套 `Canvas Agent -> SSE -> 浏览器执行` 的链路。
+
+## 安全边界
+
+- `Canvas Agent` 默认只监听 `127.0.0.1`。
+- 网页连接必须携带本机生成的 `Connect token`。
+- 第一次带正确 token 连接后，`Canvas Agent` 会记录网页 Origin，避免其他来源复用当前本机 Agent。
+- Codex 不直接访问浏览器 DOM，也不直接持有画布内部状态。
+- 线上网页不保存本机 Codex 登录态、API Key 或本地文件权限。
+- 画布写操作最终由浏览器前端执行，因此可以在前端做确认、撤销和权限控制。
+
+## 一句话总结
+
+本地 Codex 连接画布的本质是：
+
+```txt
+Codex 调 MCP 工具，Canvas Agent 做本机桥接，浏览器通过 SSE 接收工具调用并在 React 状态中真正修改画布。
+```
+
+读状态是：
+
+```txt
+浏览器快照 -> Canvas Agent 内存 -> MCP 工具 -> Codex
+```
+
+写操作是：
+
+```txt
+Codex -> MCP 工具 -> Canvas Agent -> SSE tool_call -> 浏览器 applyOps -> /canvas/result -> Codex
+```
diff --git a/docs/content/docs/overview/meta.json b/docs/content/docs/overview/meta.json
index bbaf606..19367fe 100644
--- a/docs/content/docs/overview/meta.json
+++ b/docs/content/docs/overview/meta.json
@@ -9,6 +9,7 @@
     "render",
     "docker",
     "third-party-prompt-repositories",
-    "[在线体验](https://canvas.best/)"
+    "[在线体验](https://canvas.best/)",
+    "local-codex-canvas"
   ]
 }
diff --git a/docs/content/docs/progress/pending-test.mdx b/docs/content/docs/progress/pending-test.mdx
index 64871aa..e60e63a 100644
--- a/docs/content/docs/progress/pending-test.mdx
+++ b/docs/content/docs/progress/pending-test.mdx
@@ -8,6 +8,7 @@ description: 当前版本已实现但仍需人工验证的变更项
 - GitHub Pages：新增版本 tag 触发的前端静态站点自动发布 workflow，需在仓库 Pages 设置中选择 GitHub Actions 并验证路由刷新回退。
 - 画布图片切图：行数 / 列数会生成可直接拖拽的等分切图线，并支持新增横向 / 纵向线、删除单条线、重置切图线和切片数量预览。
 - Codex App 插件文档：新增插件安装教程，区分 AI 自动安装、手动安装和本仓库开发调试安装；同步优化插件 README 与技能说明。
+- 本地 Codex 连接画布文档：新增 Canvas Agent、MCP、SSE 与浏览器画布交互原理说明，需确认文档导航和描述是否清晰。
 - 顶部导航：缩小桌面顶部导航栏高度，导航项下划线和内容垂直对齐需确认。
 - 配置与用户偏好：新增独立顶部导航页面，并在页面和弹窗中复用同一套配置面板；新增 Codex Tab，展示插件安装和本地 Agent 启动步骤，可配置本地 Agent 地址、Connect token 和工具执行确认开关。
 - Codex 全局连接：配置页可直接连接本地 Canvas Agent，连接状态同步到画布和顶部 OpenAI 状态图标，刷新后会按本地保存的地址和 token 自动尝试重连；需验证已连接、连接中、连接失败、断开和刷新自动重连状态。
diff --git a/docs/index.md b/docs/index.md
index 43a1f25..0b2d178 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -40,3 +40,7 @@
 
 - 当前画布项目和“我的素材”主要保存在浏览器本地，跨设备可自行配置 WebDAV 同步。
 - AI API Key 保存在浏览器本地，并由前端直接请求 OpenAI 兼容接口。
+
+## 原理说明
+
+- [本地 Codex 连接画布原理](/docs/overview/local-codex-canvas)
diff --git a/web/src/components/layout/app-config-modal.tsx b/web/src/components/layout/app-config-modal.tsx
index 36892b7..4e5bc6f 100644
--- a/web/src/components/layout/app-config-modal.tsx
+++ b/web/src/components/layout/app-config-modal.tsx
@@ -467,7 +467,7 @@ export function AppConfigPanel({ showDoneButton = false, initialTab = "channels"
                                             <ShieldCheck className="size-4 text-stone-500" />
                                             <div>
                                                 <div className="text-sm font-medium">执行画布操作前确认</div>
-                                                <div className="mt-0.5 text-xs text-stone-500">关闭后，本地 Codex 可直接执行画布工具调用。</div>
+                                                <div className="mt-0.5 text-xs text-stone-500">关闭后，本地 Codex 可直接执行画布工具调用。不再需要人工确认</div>
                                             </div>
                                         </div>
                                         <Switch checked={agentConfirmTools} onChange={(confirmTools) => setAgentState({ confirmTools })} />