让 Open WebUI 接上本地编码代理

变化是什么

Open Terminal 0.17.0 在 2026 年 11 月 6 日加入通过 Open WebUI 使用 Codex、Claude Code、Cursor、Grok、OpenCode、Cline、Gemini CLI 和 Pi 的能力；Open WebUI 0.13.0 则在 11 月 3 日发布带终端、文件、浏览器和 Git 面板的标签工作区。组合起来，用户可以从聊天界面选择终端里已经安装的代理，在当前项目目录里继续工作，同时查看代理回复、工具活动并处理代理发出的批准请求。这不是把代理模型变成 Open WebUI 的内置模型，也不是只填一个兼容 API 地址：代理 CLI 和它的认证仍属于运行 Open Terminal 的那台机器。

这个边界决定了接入时要分别检查三件事：Open WebUI 能否连接终端；终端进程能否找到并运行代理 CLI；该 CLI 是否已在终端用户环境中登录。任何一项失败，聊天界面都可能看不到代理模型，或在发送任务后无法启动会话。本文的步骤针对 Open WebUI 0.13.0 与 Open Terminal 0.17.x 的官方说明；实际部署时应核对你安装的构建是否包含 agent support，不要只凭版本号推断功能已启用。

先把执行位置想清楚

Open WebUI 在这里主要是交互和会话界面。Open Terminal 负责持有项目目录、启动命令和连接代理 CLI。官方 README 说明，聊天中选择终端后，终端已发现的代理模型会以 <agent>/<model> 形式出现在模型选择器里；对话工作目录是该终端当前目录。文件附件、流式输出、停止操作和后续消息都围绕这个终端代理会话进行。

因此，“本地代理”里的本地，指的是 Open Terminal 进程所在的环境，不必然是打开浏览器的电脑。如果 Open WebUI 和 Open Terminal 都在一台开发机上，执行路径较直接；如果 Open WebUI 在服务器、终端在开发者电脑上，就要让两者通过受控连接沟通。Tether 可以提供已保存连接的转发路径，使托管的 Open WebUI 访问个人电脑上的代理，而不要求把个人电脑地址公开到互联网。即使采用这种方式，代理登录凭据仍留在终端环境，不会因为从 WebUI 发起聊天就迁移到 WebUI。

这和把 Open WebUI 配成某个云模型的 OpenAI 兼容端点不同。后者发送的是模型 API 请求；这里启动的是运行在终端主机上的 CLI 代理，由 CLI 自己管理模型、工具和认证。若问题是“如何给聊天服务加一个模型供应商”，应检查模型连接配置；若问题是“如何让 Codex 或 Gemini CLI 操作某个工作树”，才是终端代理集成的范围。也可以先浏览平台目录了解不同 API 平台的接入方式，避免把模型 API 与代理执行环境混为一谈。

部署终端并配置连接

Open Terminal 官方 README 给出了 Docker 启动方式。持久卷保存终端文件，API Key 用于连接鉴权；:agents 镜像在完整工具环境上附带 Codex 和 Claude Code CLI。以下是文档形式的示例，部署时请替换密钥，并按实际网络拓扑限制端口访问：

docker run -d --name open-terminal --restart unless-stopped \
  -p 8000:8000 \
  -v open-terminal:/home/user \
  -e OPEN_TERMINAL_API_KEY="$OPEN_TERMINAL_API_KEY" \
  ghcr.io/open-webui/open-terminal:agents

如果你选择 latest，README 列出的基础工具包含 Python、Node.js、构建工具、浏览器、桌面和文档工具，但不会因此自动安装全部代理 CLI。其他 CLI 需要按其官方安装方式加入终端环境。生产环境还应固定镜像版本，而不是长期依赖可变的 latest 或 agents 标签；升级前先记录当前镜像、持久卷和代理 CLI 版本，便于复现问题或回退。

接着在 Open WebUI 的 Settings → Admin → Integrations → Open Terminal 中新增连接。URL 必须能从 Open WebUI 服务端到达，填写对应 API Key，启用连接。然后进入聊天，选择这个终端，再从模型选择器选择已发现的代理。容器之间不要把 localhost 当成另一个容器的地址；在 Compose 或 Kubernetes 中，应使用服务名、集群地址或明确配置的受控入口。若终端在个人电脑上，使用官方支持的 Tether 连接路径，而不是为方便测试就把带有命令执行能力的服务暴露到公网。

设置完成后，先用一个无副作用的任务验证端到端链路，例如要求代理列出当前目录的文件，而不是直接让它改写或提交代码。随后检查它是否识别预期项目目录、是否能读取附件、工具调用是否出现、批准请求是否能回到界面。遇到模型选择器没有代理条目时，依次检查 CLI 是否安装、Open Terminal 进程的 PATH 是否包含该命令、CLI 登录用户是否与运行终端进程的用户一致，以及 WebUI 连接是否成功。单独能在自己 shell 里执行 CLI，不足以证明容器内的服务进程也能执行它。

登录、权限与会话恢复

每个代理需要先在运行 Open Terminal 的环境中安装并登录。集成不会替代理完成交互式登录流程。容器部署时，这意味着你需要以与服务相同的用户和持久化配置完成认证，并确认更新容器后登录状态仍按预期保存。不要将 CLI 凭据写进项目仓库、镜像构建参数或聊天消息。终端 API Key 本身也不是只读令牌：官方 README 明确指出，它授予命令和文件访问能力；裸机运行时，命令继承启动该服务的操作系统用户权限。因此应只让可信用户访问终端连接，并用专门的低权限账户运行，尽量把可访问目录缩小到实际工作区。

批准机制也有边界。Open Terminal 0.17.0 的发布说明说，用户可以在聊天中回应代理的批准请求，但具体哪些操作会弹出请求取决于各个代理。不能把 WebUI 中存在批准对话框理解成统一沙箱或逐工具策略。不同 CLI 原生权限模式仍然重要；在共享终端或团队部署里，应该先验证所用代理对文件读写、命令执行和网络访问的实际限制，再开放给其他用户。

断开浏览器或网络连接也不等于代理进程立刻停止。官方发布说明指出，短暂中断后连接可以恢复并补上未读输出，避免重复发送同一输入；断开后会话不会立即终止，超过一小时仍断开的会话会在清理过程中关闭。运行长任务时，用户应区分“界面断开”和“代理已停止”。结束敏感任务时，回到会话显式停止并确认状态，而不要把关闭标签页当作取消操作。

聊天历史的恢复能力还受代理协议支持影响。当前 README 说明，集成通过代理原生接口运行；对于不提供原生恢复能力的代理，下一轮会把已保存的对话文本交给代理，而不是恢复其内部完整执行状态。分支或重新生成代理会话需要新聊天。因此，重要的执行状态、修改内容和验证结果应落在工作树、提交或测试记录中，不要只把聊天记录当作可恢复的任务状态。

浏览器与版本配合

Open WebUI 0.13.0 的工作区可把聊天、文件、终端和预览放在同一处；其浏览器标签还允许并排打开网站和本地开发服务器。官方发布说明区分了 Proxy 与 Chrome 模式：Chrome 模式可以让模型和用户共享浏览器会话，用于浏览器自动化和测试网页；这需要兼容的 Open Terminal、终端侧浏览器支持，以及供 browser-use 工具使用的 Chrome。仅仅看得到浏览器预览，不表示代理已经能操作这个浏览器。上线前要实际检查所用连接和代理是否具备对应能力。

版本升级要当成一组组件来验证，而不是只更新 Open Terminal。agent support 要求 Open WebUI 具备相应支持；Tether 方式也要求 Tether 和 WebUI 都包含相关支持。Open WebUI 0.13.0 还包含数据库结构变更，发布说明建议生产升级前备份数据库及相关数据，并明确指出多 worker、多服务器或负载均衡部署必须同时更新所有实例，不支持滚动升级，否则会发生 schema 不兼容导致的应用故障。部署前应安排维护窗口、备份并验证恢复路径，再同步更新实例和兼容组件。

如果终端里已能运行 CLI，但聊天端看不到模型，先确认 WebUI 与终端版本是否都具备 agent support；如果能选模型却无法启动，检查 CLI 命令路径、登录状态和当前目录权限；如果出现断线，先判断进程是否仍在运行，再决定恢复还是显式停止。这样分层排查，比一开始更换模型 API Key 更能定位问题，因为这条链路的关键凭据和执行过程都在终端环境。

将编码代理接入聊天工作区，真正改变的是操作入口和执行环境的组合，而不是把所有风险转交给界面。评估部署时，重点确认谁能访问终端、代理以什么操作系统身份运行、它能触及哪些目录、工具批准具体由谁处理，以及数据库升级是否可整体完成。若你在比较不同模型 API 或服务商，可以先查看OpenAI 平台详情中的 API 接入信息；API 目录不能替代对本地代理权限与运行环境的审查。若关心另一种会话宿主设计，可参阅VS Code Agent Host 的会话与客户端边界。