HA_Codex_Bridge

<div align="center"> <img src="brand/logo.png" alt="Codex Bridge - 私有代码，家庭控制" width="720"> # 首页助手 Codex Bridge 在家庭助手（Home Assistant）上保留浏览器流量，同时私有 HAOS 应用连接到您家网络中的 Codex/OpenAI。 [](https://my.home-assistant.io/redirect/hacs_repository/?owner=Herbertmt978&repository=ha-codex-bridge&category=integration) [](https://github.com/Herbertmt978/HA_Codex_Bridge/releases/latest) [](https://github.com/Herbertmt978/HA_Codex_Bridge/actions/workflows/ci.yml) [](https://github.com/Herbertmt978/HA_Codex_Bridge/actions/workflows/release.yml) [](codex_bridge_app/README.md) [](LICENSE) [安装](docs/installation.md) | [功能](##%E5%8A%83%E5%90%8C%E5%92%8C%20Codex%20%E5%8A%83%E5%90%8C%E5%8A%83) | [更新](#%E6%9B%B4%E6%96%B0%E5%92%8C%E6%89%8B%E5%90%8A) | [远程访问](docs/remote-access.md) | [备份和恢复](docs/backup-restore.md) | [安全](SECURITY.md) | [支持](SUPPORT.md) </div> ## 它是什么 Codex Bridge 将 Home Assistant 作为面向用户的控制平面。管理员在 Home Assistant 面板中工作；私有 Bridge 协调 Codex 和一个有意授予的工作空间。 ```text 浏览器 -> Home Assistant -> Codex Bridge 集成 -> 私有应用或外部 Bridge -> Codex / OpenAI ``` 浏览器不直接连接到 Bridge、应用或 Codex。相反，通过其正常的 LAN 或 HTTPS 远程访问路由发布 Home Assistant；应用和 Bridge 对 Home Assistant 保持私有。 ## 两个组件，两个安装路径 - **HACS 集成：** `codex_bridge` 自定义集成提供管理员面板，并通过 HACS 安装。上面的 HACS 链接打开了一个自定义仓库流程；这并不是声明该项目已在 HACS 或 Home Assistant 中列出、审查、认可或支持。 - **Supervisor 应用：** 私有运行时，旨在与 Home Assistant 一起运行 Bridge 和 Codex。将此仓库添加到 Home Assistant 应用商店中，以安装其发布的不可变镜像。 <details> <summary><b>当前版本和验证详细信息</b></summary> - **历史完全目标-HA 接受版本：** 应用、集成和面板 `0.7.5`，Bridge `0.6.3`，Codex `0.144.5` 在目标 Home Assistant `192.168.50.20` 上安装并运行，时间为 2026-07-16。ChatGPT Pro 保持连接。一个全新的直接聊天默认设置为 `gpt-5.6-sol`，具有 `low` 思维；目录公开了 Sol、Terra 和 Luna，具有 Low、Medium、High、XHigh、Max 和 Ultra 等级，广告中可见。紧凑型作曲家渲染了五个小时的 `关闭` 和一周的 `60%`。 - **本地实时搜索：** 自然提示 `今天马耳他天气怎么样` 记录了 `搜索网络` 运行活动，并返回当前实时状况。这是提供者端的搜索，而不是 shell 命令网络。 - **最新签名版本和账户切换接受度：** 应用、集成和面板 `0.8.11`，Bridge `0.7.6`，Codex `0.144.5` 从确切的主提交 `5387a2abcdeac3a5a3c01fe96876634af56542ad` 发布。签名应用发布 [运行 29633146637](https://github.com/Herbertmt978/HA_Codex_Bridge/actions/runs/29633146637) 和配对的 [0.8.11 集成版本](https://github.com/Herbertmt978/HA_Codex_Bridge/releases/tag/0.8.11) 通过。不可变镜像摘要为 `sha256:1e69b2db3b223f3e60bc00ce463ae9c5a941d9492c5149ff95eaa1f890deab85`，具有验证的签名、来源和 SBOM 声明。目标 Home Assistant 保留其现有的 `测试` 聊天、项目、记录、设置和 ChatGPT Pro 会话，在协调升级后；新连接的账户在同一个聊天中完成了确切的账户切换接受提示，而不恢复前一个账户的私有提供者线程。 - **上一次提示路径目标-HA 烟雾测试：** 在 `192.168.50.20` 上，应用和集成 `0.8.3` 报告 Bridge `0.7.2` 和 Codex `0.144.5`；ChatGPT Pro、项目和聊天历史记录被保留。前 `0.8.0 PDF 接受度` 线程从虚假的 **工作中 / 准备响应 / 停止 / 转向** 状态恢复到真实的就绪/运行完成状态。一个全新的 GPT-5.6-Sol 提示完成，Sol/Terra/Luna 和广告的 Max/Ultra 推理级别可见，五个小时的使用情况渲染为 `关闭`，马耳他提示公开了 `搜索网络` 和 `使用网络搜索`，然后返回实时状况。没有错误的全局 **连接问题** 在成功运行后保持。 - **0.8.5 目标结果：** 应用/集成/面板 `0.8.5` 与 Bridge `0.7.3` 和 Codex `0.144.5` 安装在目标 HA 上。ChatGPT Pro、项目和历史记录被保留；**打开预览** 在文件中显示生成的图像；HA 文档保持固定，而记录保持为唯一的滚动端口。实时浏览器下载探针没有收到本地下载事件，因此 `0.8.5` 的下载接受度仍然失败。 - **0.8.7 目标结果：** 协调的签名版本安装干净，并保留了 ChatGPT Pro、历史记录、生成的图像预览和仅记录的滚动。一个浏览器下载在重定向的 Windows 下载文件夹中持续存在，具有预期的 PNG 签名和 SHA-256 `F211434D64D69C2246A600445B9B69DDAB82D6D676D32FD0D215D178DB7D31FF`。Chrome 自动化事件没有浮现这个 blob 下载，因此接受度基于浏览器写入的文件，而不是事件钩。 - **稳定版本 1.0.0：** 应用进入 Home Assistant 的稳定生命周期阶段，并保留在 `0.8.11` 中接受的账户中性聊天合同。作曲家现在在输入提示时立即启用 **发送**，而无需等待不相关的状态刷新。此生命周期推广不会扩大文件系统、网络、身份验证、架构或恢复范围。 - **Codex 奇偶校验和开放边界：** 标题、记录、安全实时操作、交互和作曲家共享一个 840 像素的阅读轨道；紧凑型活动卡公开输出、有界子代理计数、后台活动、浏览器状态和来源。键入的 PDF **文件** `409` 具有本地覆盖的修复程序，隔离选定的工件读取与无关的过时工作区碎片；真正的目标-HA 列表/存档/预览/下载接受度仍然待定。参数化的 LAN/Nabu 形状/Cloudflare 形状的合成代理和编辑的远程证据合同现在通过，而授权的外部 Nabu Casa 和 Cloudflare 路由捕获仍然待定。冷恢复、任意图像回滚和安全的应用拥有浏览器工作线程保持开放。配对的应用/集成版本工作流程完成了其第一个实时自动练习，版本为 `0.8.4`。 - **浏览器自动化：** 安全的应用拥有浏览器工作线程后续跟踪在问题 #43 中；交互式 Chromium 仍然被 [ADR 0006](docs/aegis/adr/0006-preview-and-browser-boundary.md) 延迟。 当前稳定应用仅支持 `amd64` Home Assistant OS。Nabu Casa 和反向代理路由保留相同的浏览器到 HA 的信任边界，但阻止工作区路由、冷恢复和任意以前的图像回滚仍然是能力特定的限制，而不是稳定支持声明的一部分。历史详细信息保留在 [更新日志](codex_bridge_app/CHANGELOG.md) 和签名 [版本](https://github.com/Herbertmt978/HA_Codex_Bridge/releases) 中。 </details> > [!IMPORTANT] > 应用是稳定的，目前仅支持 `amd64` Home Assistant OS。仅安装 HACS 集成提供面板，但不运行 Codex；还必须安装 Supervisor 应用，或显式配置高级私有外部 Bridge。 | 安装前 | 边界 | | --- | --- | | 网络 | 仅发布 Home Assistant；应用和 Bridge 保持私有。 | | 存储 | 应用写入其私有状态和有意放置在 `/config/workspaces` 下的工作空间。 | | 账户 | ChatGPT 设备身份验证保留在应用私有存储中，不使用 OpenAI API 密钥。 | | 撤销 | 停止/删除应用和集成；审查工作空间并注销，然后再删除其数据。 | ## 安装和首次运行 1. 通过 HACS 安装 **Codex Bridge** 集成，然后重启 Home Assistant，以便其 Supervisor 发现处理程序处于活动状态。 2. 在 **设置 -> 应用 -> 应用商店 -> 仓库** 中，添加 <https://github.com/Herbertmt978/HA_Codex_Bridge>。等待商店提供应用 `1.0.0` 或更高版本，然后安装并启动 **Codex Bridge**。不要安装应用 `0.6.1`；它在目标-HAOS 就绪时关闭。 3. 在 **设置 -> 设备和服务** 中，确认已发现 **Codex Bridge** 集成。Supervisor 自动宣传应用的私有 HA 网络 IP 和端口；无需复制主机、端口或持有者令牌。如果应用刚刚启动或重启，发现可能需要几秒钟才能到达。在应用报告就绪后重试；集成在私有端点暂时无法访问时保持有效的发现表单可见，并且不保存未经验证的连接。 4. 作为 Home Assistant 管理员打开面板。选择 **使用 ChatGPT 登录**，然后使用浏览器完成批准的 ChatGPT 设备身份验证页面。**取消** 仅取消进行中的登录；**注销** 删除已建立的 Codex 会话。在批准后，面板每两秒检查授权账户状态，直到 Codex 报告会话就绪。 5. 在应用模式下创建项目并授予 `/config/workspaces` 下的小工作空间。审查更改后再扩展该边界。 Home Assistant 和 ChatGPT 会话是分开的。建立 ChatGPT 会话后，可以在 Home Assistant 来源上保持正常的面板使用。初始登录和重新身份验证仍然需要浏览器访问批准的 ChatGPT 设备身份验证页面。此帐户流程不使用 OpenAI API 密钥。 聊天记录是 Home Assistant/Bridge 记录，而不是每个帐户的副本。注销或登录到另一个 ChatGPT 帐户不会删除、隐藏、复制或移动其本地历史记录。当身份验证的帐户更改时，Bridge 仅删除旧帐户的私有 Codex 线程句柄；在同一聊天中的下一个消息启动一个新的提供者对话，通过现在连接的帐户。早期本地记录和文件仍然可见，但不会被静默地重播到新的提供者对话中。如果授权的 Codex 帐户读取无法提供稳定的身份，Bridge 谨慎地分离提供者连续性，并保持提示和自动化被阻止，直到后续读取验证帐户。本地聊天及其内容在整个过程中保持可用。帐户更改还使已经在途中的帐户检查无效，并停止任何以前排队的提示在可以启动或恢复提供者线程之前。 ## 自动化和 Codex 功能 面板还公开了仅限管理员的功能，限定在所选应用工作空间内： - **自动化/定时任务：** 创建针对项目或现有线程的提示，选择 `观察`、`编辑` 或 `全自动`，并安排一次性、间隔或 RFC 5545 重复。Home Assistant 拥有挂钟；Bridge 保留定义，使用修订检查和幂等声明，记录重叠/容量/错过跳过，并保持运行历史记录有限。暂停自动化，然后再删除它。 - **本地网络搜索和图像：** 在 Supervisor 连接上，默认情况下选择本地网络搜索，并在应用宣传后激活，包括延迟登录。它适用于提示和手动自动化运行，可以在集成选项中禁用。这不会启用 shell 命令网络。图像生成需要签入的 ChatGPT 帐户以及运行时 `imageGeneration` 和 `namespaceTools` 功能。它不使用 OpenAI API 密钥；生成的 PNG、JPEG 和 WebP 工件保持私有和大小限定。 - **Codex 样式运行详细信息和预览：** 实时阶段、允许列出的工具操作、文件/行总数和聚合子代理状态出现在运行芯片中，而不暴露提示、代理 ID、命令、URL 或工作空间路径。文本、栅格图像和签名验证的 PDF 可以通过 Home Assistant 的管理员身份验证的工件路径在面板内查看。PDF 的大小限制为 8 MB，声明和获取的大小均有限制，然后由捆绑的本地 PDF.js 画布渲染器渲染（禁用脚本、求值和 XFA）。不使用 iframe 或原生浏览器 PDF 嵌入。HTML、SVG、无效 PDF、未知大小的文件和超大文件保持安全打开/下载的备用方案。 - **技能：** 在所选工作空间的 `.agents/skills/` 树下列出、启用/禁用、创建和删除工作空间技能。拒绝工作空间以外的路径。 - **说明 (`AGENTS.md`)：** 编辑全局 Codex `AGENTS.md` 或所选项目的 工作空间根 `AGENTS.md`。写入是原子的，保留先前版本的私有有界回滚快照。 - **插件和市场：** 检查运行时报告的市场和插件，安装/卸载插件，并添加/删除/升级市场。市场源必须使用 HTTPS 主机名；拒绝字面/已知非公共地址、凭据和任意配置有效载荷。在历史 `0.7.1` 的实时接受运行中，列表调用返回 `capabilities_unavailable`（HTTP 503）；没有声称 `0.7.1` 插件或市场的列表/突变接受度。`0.7.5` 接受度没有演练插件或市场，因此没有声称当前的插件或市场接受度。 - **MCP 服务器：** 默认情况下，MCP 被禁用。要使用它，请在 Codex Bridge 应用配置中显式启用 **启用 MCP**，保存并重启应用。仅使用 HTTPS 主机名配置出站流式 HTTP 服务器。拒绝字面 IP、本地/内部主机名和已知的非公共 DNS 答案；不公开持有者令牌配置。DNS 检查是尽力而为的，不会形成连接时间 IP 允许列表，因此仅为受信任的提供者启用 MCP。OAuth 是明确的：从面板启动登录，然后将返回的授权 URL 视为一次性敏感数据。MCP 询问请求在单独审查的 UX 存在之前被拒绝。关闭 MCP 会抑制并删除其保存的服务器表，而不会更改技能、插件、市场或说明。添加服务器不会发布应用或 Bridge。 这些界面是运行时派生的，可能在 Codex 忙碌、未身份验证或恢复时不可用。失败的突变会返回有限的错误，而不会泄漏提供者详细信息或机密。 ## 更新和恢复 集成和应用分别更新： 1. 在 HACS 中，更新或重新下载最新的 **Codex Bridge** 集成，然后重启 Home Assistant。在已经打开的任何面板选项卡上重新加载。 2. 阅读匹配的 [发布说明](https://github.com/Herbertmt978/HA_Codex_Bridge/releases/latest)，打开 **上下文 -> 系统**，并确认版本部分显示预期的集成、应用、Bridge 和 Codex 版本。健康的版本芯片在对话界面之外保持不变；运行时警告仍在那里出现。 3. 如果 Home Assistant 提供应用更新，请制作冷备份并从 **设置 -> 应用 -> Codex Bridge** 应用它。自动更新可以在其切换启用后执行此操作；第一个无人值守的设备更新已被证明。已接受的 `0.7.5` 更新保留了自动更新和以前版本的备份。保留冷备份，因为恢复和任意以前的图像回滚仍然未经验证。 应用镜像是不可变的：运行中的容器不会替换 Codex 或其自身。计划更新程序验证上游 Codex 版本和 Sigstore 身份验证，并仅重新生成允许的运行时投影。当专用的、仓库范围的 GitHub 应用配置完成后，它会用该令牌和分支保护门控的拉取请求打开问题。每项所需检查都通过后，它会静默自动合并。它的客户端 ID、私钥和机器人登录都需要：缺少任何一个，工作流程都会发出可行的通知并且不会创建拉取请求。它永远不会回落到 `GITHUB_TOKEN`，因为这样的拉取请求不会启动所需的 CI。 `CODEX_UPDATE_PAUSED` 是维护者的终止开关。成功的主构建然后发布并验证不可变的签名应用镜像，然后 Home Assistant 才能提供它。 Supervisor 应用目前不提供验证的方法来选择任意以前的镜像，因此在应用更改之前请制作 Home Assistant 的冷备份。在已经存在外部 Bridge 的地方保留一个冷备份，直到可以进行冷恢复；参见 [备份和恢复](docs/backup-restore.md)。 ## 安全边界 | 边界 | 责任 | | --- | --- | | 远程访问 | 发布 Home Assistant，而不是应用或 Bridge。 | | Home Assistant | 面板仅限管理员；管理员可以要求 Codex 在授予的工作空间中操作。 | | 应用/Bridge | 私有运行时状态和 Codex 会话在浏览器访问路径之外保持。 | | 工作空间 | Codex 只能检查和更改您授予的文件；从小开始并审查更改。 | | 凭证 | 不要分享设备代码、Bridge 令牌、会话材料或工作空间机密。 | 应用在无法验证其沙盒身份验证时关闭。不要放松沙盒以继续；检查应用日志并使用受支持的版本。参见 [应用文档](codex_bridge_app/DOCS.md) 和 [SECURITY.md](SECURITY.md)。 ## 卸载 停止应用或外部 Bridge，删除集成，并审查 `/config/workspaces` 然后删除项目数据。在通过正常的帐户控制使用 **注销** 和撤销 ChatGPT 会话之前，请不要重复使用设备。[外部 Bridge 迁移指南](docs/migration-from-windows.md) 提供了安全过渡和恢复指导。 ## 开发和贡献 参见 [开发](docs/development.md) 和 [CONTRIBUTING.md](CONTRIBUTING.md)。源代码在 [MIT 许可证](LICENSE) 下可用；第三方归属在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 中。