无限画板本地部署：接入 Codex
|本文介绍如何在 Windows 本地启动 Infinite Canvas（无限画板），配置画布中的 AI 接口，并通过 Canvas Agent 和 MCP 接入 Codex，完成画布读取、写入和结果验证。
本文以官方文档为主。桌面快捷方式和后台运行部分属于本机补充方案，命令和界面可能随版本变化，请以当前项目文档和本机输出为准。
一、连接方式
Infinite Canvas 是运行在浏览器中的画布应用。Canvas Agent 运行在本机，负责建立浏览器与 Codex 之间的连接；Codex 通过 MCP 调用画布工具。
浏览器中的 Infinite Canvas
↕
Canvas Agent
↕
Codex + Infinite Canvas MCP
浏览器负责维护画布状态，Canvas Agent 负责本机桥接，Codex 负责调用工具。画布状态包括节点、连线、选区和视口等信息。
需要区分两件事：启动本地网页不等于已经接入 Codex；Codex 发出写入操作，也不等于画布状态已经完成修改。操作后应重新读取画布，确认节点或连线是否真的发生变化。
二、准备工作
开始前需要准备：
- 一台 Windows 电脑；
- Git；
- Bun，或 Node.js/npm；
- 一个可以正常使用的 Codex 环境；
- 如果需要使用画布中的 AI 生图、文本、视频或音频功能，还需要对应的接口地址、模型名称和 API Key。
本文命令以 PowerShell 为例。画布内部的 API Key 配置和 Codex 的 MCP 配置属于两组不同的配置，前者不会自动成为后者的模型配置。真实 API Key 不要写入仓库。
三、启动本地画板
3.1 使用源码启动
先拉取项目并进入网页端目录：
git clone https://github.com/basketikun/infinite-canvas.git
cd infinite-canvas\\web
项目文档使用 Bun 安装依赖并启动开发服务：
bun install
bun run dev
如果本机使用 npm，也可以执行：
npm install
npm run dev
看到终端输出本地地址后，在浏览器打开：
http://localhost:3000
首次打开时，可以先新建一个空白画布。确认页面能够创建画布，并可以正常缩放和移动，再进行后续连接配置。
3.2 使用 Docker 启动
如果不想在本机配置前端依赖，可以使用项目提供的 Docker 配置。在项目根目录执行：
git clone https://github.com/basketikun/infinite-canvas.git
cd infinite-canvas
docker compose up -d
如果希望使用本地源码构建镜像，可以执行：
docker compose -f docker-compose.local.yml up -d --build
然后打开：
http://localhost:3000
Docker 方式主要负责启动本地网页服务。画布中的 AI 请求仍然由浏览器直接请求配置的接口，API Key 需要在画布页面内单独配置。
四、桌面快捷方式
如果需要经常使用，可以在本地项目中额外配置一个 Windows 原生启动器，创建桌面快捷方式。这不是 Infinite Canvas 官方发布包或官方文档提供的功能，而是本机为方便启动开发服务增加的 .NET WinForms 启动器，适合把“启动服务”和“打开画布”合并成一次双击。
这一步需要安装 .NET 8 SDK，并且启动器需要放在 Infinite Canvas 项目目录内。先回到项目根目录，执行：
dotnet build .\desktop\launcher\InfiniteCanvasLauncher.csproj -c Release
构建完成后，运行一次安装快捷方式的参数：
.\desktop\launcher\bin\Release\net8.0-windows\InfiniteCanvasLauncher.exe --install-shortcut
成功后，当前 Windows 用户的桌面会出现“无限画布.lnk”。快捷方式的工作目录需要指向项目根目录，不能单独移动项目目录或启动器文件。
五、后台运行
双击“无限画布”快捷方式后，启动器会先检查 3000 端口：
- 如果 Web 服务没有启动，就启动
web目录中的开发服务，然后打开http://localhost:3000/； - 如果
3000端口已经有服务，就只打开 Web UI，不重复启动一个服务； - 启动器本身不保持一个可见的命令行窗口，而是缩到 Windows 系统托盘中。
托盘图标提供以下操作：
- 双击托盘图标：打开 Web UI；
- 右键查看当前服务状态；
- 右键“启动服务”：服务停止时重新启动；
- 右键“关闭服务并退出”：关闭本次启动器启动的服务，并退出托盘程序。
这里的“后台运行”指隐藏命令行窗口并由托盘管理，不等于 Windows 服务，也不等于开机自动启动。运行日志保存在：
%LOCALAPPDATA%\InfiniteCanvas\web.stdout.log
%LOCALAPPDATA%\InfiniteCanvas\web.stderr.log
如果托盘提示服务启动失败，先查看日志，再检查 web 目录依赖和 3000 端口。当前本机启动器使用 0.0.0.0:3000 监听；如果只希望本机访问，还需要结合 Vite 配置或 Windows 防火墙进行限制。
六、配置画布 API Key
本地网页启动后，如果需要使用画布自身的 AI 生图、文本、视频或音频功能，需要在页面内配置接口和 API Key。这部分配置与 Codex 的 MCP 配置是两条不同的链路。
6.1 打开配置面板
进入画布后，点击右上角的设置图标，打开“配置与用户偏好”面板。
配置面板默认打开“渠道”选项卡。这里的“渠道”可以理解为一组接口配置：每个渠道都有自己的协议、接口地址、API Key 和模型列表，可以配置多个渠道再分别选择模型。
6.2 新增一个接口渠道
如果默认渠道不能直接使用，点击“新增渠道”，然后进入编辑渠道页面，依次填写：
- 渠道名称：用于自己区分不同服务商，例如“本地中转”或“图像接口”；
- 协议：根据服务商接口选择“OpenAI”或“Gemini”；
- 接口地址：填写服务商提供的 Base URL；
- API Key：粘贴自己的密钥，输入框会以密码形式隐藏内容。
接口地址填写服务商提供的 Base URL，不要把具体请求路径当成 Base URL。API Key 只填写密钥本身，接口有特殊要求时，以服务商文档为准。
6.3 选择或增加模型
填写接口地址和 API Key 后，点击“选择模型”。如果上游提供 OpenAI 兼容的 /models 接口，可以点击“拉取模型列表”；如果上游不提供模型列表，则在“输入模型名称”处手动增加模型。
模型加入渠道后，还需要为模型指定能力：生图、视频、文本或音频。能力选错时，模型可能会出现在错误的模型选择器里，或者在真正请求时失败。
确认模型后点击“确定”，再在渠道编辑页面点击“保存”。返回配置面板后，可以在渠道列表中看到接口地址、协议和模型数量。
6.4 设置默认模型
切换到“偏好设置”选项卡，为不同功能选择默认模型：
- 默认生图模型；
- 默认视频模型；
- 默认文本模型；
- 默认音频模型。
最后点击“完成”关闭配置面板。保存后执行一次最小的文本或生图请求，确认接口能够正常返回结果。渠道保存成功不等于 API Key 一定可用，最终仍要以实际请求结果为准。
6.5 这组配置保存在哪里
Infinite Canvas 的 AI 配置默认保存在当前浏览器的本地存储中，AI 请求由浏览器直接发送到配置的接口。更换浏览器或清理站点数据后，可能需要重新配置。导出的 JSON 可能包含 API Key，应按敏感配置保存。
七、启动 Canvas Agent
在任意终端执行：
npx -y @basketikun/canvas-agent
启动成功后，终端会输出一个本地连接地址和一个 Connect Token。回到 Infinite Canvas 页面，打开 Agent 或 Codex 连接面板；如果需要手动填写，就使用本次启动输出的 Local URL 和 Connect Token。
Canvas Agent 默认使用本机地址。端口和 Token 以本次终端输出为准，不要复用旧 Token。
连接成功后，页面会显示本地 Agent 已连接或类似状态。这个状态只能说明网页与 Agent 已经建立连接，Codex 侧的 MCP 还需要单独配置。
八、让 Codex 获得画布工具
Canvas Agent 的网页连接和 Codex 的 MCP 工具属于两个层次。只执行 npx -y @basketikun/canvas-agent，可以启动本地 Agent，但不会自动给终端版 Codex 安装 MCP。
8.1 安装插件
官方仓库提供了 Infinite Canvas 的 Codex 插件。进入项目根目录：
cd infinite-canvas
codex plugin marketplace add "$PWD"
codex plugin add infinite-canvas@infinite-canvas-local
安装完成后，建议新建一个 Codex 任务，让插件和 MCP 工具重新加载。输入：
帮我打开并连接到 Infinite Canvas
按照提示连接当前画布。
8.2 手动注册 MCP
如果不使用插件，也可以把 Infinite Canvas MCP 手动加入 Codex：
codex mcp add infinite-canvas -- npx -y @basketikun/canvas-agent mcp
注册后，可以检查 MCP 配置：
codex mcp list
如果当前 Codex 任务已经打开，建议新建任务或重新启动任务，让新的 MCP 工具列表生效。手动方式下，浏览器端的 Canvas Agent 仍然需要单独运行并连接；MCP 注册不会代替网页连接。
九、最小案例
连接完成后，建议先使用空白画布，按“读取—写入—再次读取”的顺序完成验证。
9.1 读取状态
在 Codex 或网页侧边栏输入：
读取当前画布状态，告诉我当前有多少个节点、多少条连线，以及当前视口信息。
空白画布通常会返回节点数和连线数为 0。这一步只读取数据，不修改画布。
9.2 创建节点
继续输入：
在当前画布创建一个文本节点，标题为“本地 Codex 接入测试”，内容为“连接成功”。
官方文档说明，浏览器侧默认自动执行画布写操作。如果在助手输入框左下方切换为“手动确认”，收到写操作后会展示待执行的工具调用，确认后才会应用到画布。无论使用哪种模式，都应通过下一步读取画布状态验证结果。
9.3 再次读取
最后输入：
再次读取当前画布，确认刚才创建的文本节点是否存在，并简要说明它的位置和内容。
如果 Codex 能读到刚刚创建的节点，且画布中也能看到对应内容，最基本的连接链路就验证完成了：
Codex 调用 MCP → Canvas Agent 转发操作 → 浏览器修改画布 → 再次读取状态
十、常见问题
10.1 Agent 没有连接
确认 npx -y @basketikun/canvas-agent 的终端进程仍在运行，再检查页面填写的 Local URL 和 Token 是否来自本次启动输出。更换浏览器或页面来源后，可能需要重新连接。
10.2 没有画布工具
检查 codex mcp list，确认 infinite-canvas 是否存在。如果没有，按上一节的插件或手动 MCP 方式注册，然后新建或重启 Codex 任务。
10.3 写入没有发生
如果使用了“手动确认”，需要在网页侧确认待执行操作。使用自动确认时，也不能只根据 Codex 回复判断成功，应再次读取画布状态，并确认使用的是当前画布。
10.4 画布 AI 请求失败
这和 Codex 的 MCP 连接是两条链路。检查画布配置中的协议、Base URL、API Key、模型名称和模型能力，并以接口实际返回结果为准。
10.5 端口被占用或连接地址变化
分别查看 Vite 和 Canvas Agent 的终端输出，使用本次实际分配的地址；必要时关闭占用端口的旧进程后再重新启动。
十一、安全与数据说明
只需要注意三点：
- API Key 和 Canvas Agent 的 Connect Token 不要放入公开截图、仓库或文章示例；
- 画布和 AI 配置主要保存在浏览器本地，更换浏览器或清理站点数据前应做好备份；
- 使用本机补充启动器时，确认 Web 服务监听地址符合自己的访问范围。
十二、总结
Infinite Canvas 的本地 Codex 接入，可以拆成四步：
- 启动浏览器里的 Infinite Canvas；
- 在画布内配置需要使用的 API Key 和模型；
- 启动 Canvas Agent，并让网页连接到它；
- 通过插件或 MCP 配置，让 Codex 获得画布工具。
完成后，使用“读取—写入—再次读取”的最小案例验证连接。页面显示已连接只是前置状态，画布实际状态才是最终验证结果。