Codex / Claude Code · 高级

Codex++ 是什么:给 Codex Desktop 加插件的小白教程

Codex++ 是给 Codex 桌面版加插件的第三方 tweak 系统,可以加入 /goal、快捷键、Better Terminal、Better Browser 等能力,但会修改本地 Codex App,安装前必须理解风险。

  • Codex++
  • Codex Desktop
  • Tweak
  • 插件
  • Goal
  • 安全
更新于 2026-05-24

一句话结论

Codex++ 很像给 Codex Desktop 加浏览器扩展:能力很强,但它会改本地 App,本质上是进阶玩家工具,不建议小白无脑安装。

适用场景

  • 你已经重度使用 Codex Desktop,想要 /goal、快捷键、Better Terminal、Better Browser、Tab Switcher 等增强功能
  • 你想理解 Codex++ Tweak Store 里的插件都在做什么,哪些适合装,哪些要谨慎
  • 你遇到 Codex Desktop 缺某个小功能,想知道能不能用本地 tweak 补上
  • 你愿意承担第三方补丁、App 重新签名、Codex 更新后 repair 的维护成本

常见现象

  • Codex Desktop 没有你想要的 /goal 或增强设置入口
  • 想改快捷键、隐藏干扰项、增强终端或浏览器面板,但官方设置里没有
  • 看到别人说安装 Codex++ 后 Settings 里多了 Tweaks / Tweak Store,不知道是否安全
  • Codex 更新后 Codex++ 失效,或者出现 failed to patch Codex after update / Codex is damaged 之类提示

原因解释

  • Codex++ 不是官方插件系统,而是会 patch 本地 Codex.app 或 Windows Store 版 Codex 的可写副本。
  • 它通过 loader + runtime 的方式启动:loader 被注入到 app.asar,runtime 放在用户目录,tweaks 放在 tweaks 目录。
  • tweak 本质是本地代码,可以改 Codex UI,部分还能运行 main process、访问文件或同步 MCP,所以必须只装可信来源。
  • Codex Desktop 更新会覆盖本地 patch,Codex++ 需要 watcher 或手动 repair 重新打补丁。

解决步骤

  1. 先判断是否真的需要:如果你只是偶尔用 Codex 聊天和改小文件,不建议安装;如果你每天用 Codex Desktop 做长任务,才值得研究。
  2. 安装前备份重要工作,关闭 Codex,确认你知道如何卸载和进入 safe mode。
  3. 优先使用 Homebrew 或 Bun 的 release 安装方式,不建议一上来执行 curl 管道脚本,除非你能看懂脚本做了什么。
  4. 安装后先运行 codexplusplus status 和 codexplusplus doctor,确认 patch、签名、watcher、runtime 状态正常。
  5. 第一批只装低风险 tweak:Keyboard Shortcuts、UI Improvements、Goal。涉及文件编辑、MCP、主进程、网络权限的 tweak 先不要装。
  6. 每次 Codex 官方更新后,如果 Codex++ 消失或 Tweaks 不见,先跑 codexplusplus repair;严重异常就 safe-mode 或 uninstall。
  7. 长期使用时,把 Codex++ 当成可撤回的增强层,不要把关键生产流程完全依赖在某个未审查 tweak 上。

可复制命令

# macOS 推荐安装路径:Homebrew
brew install b-nnett/codex-plusplus/codexplusplus
codexplusplus install
codexplusplus status
codexplusplus doctor
# Bun 安装方式。适合已经在用 Bun 的用户
bun install -g github:b-nnett/codex-plusplus
codexplusplus install
codexplusplus status
# Windows PowerShell 安装方式。注意:安装后要启动 Codex++ 快捷方式,不是原 Microsoft Store Codex 快捷方式
irm https://raw.githubusercontent.com/b-nnett/codex-plusplus/main/install.ps1 | iex
codexplusplus status
codexplusplus doctor
# 日常维护:更新、修复、检查
codexplusplus status
codexplusplus doctor
codexplusplus repair
codexplusplus update
# Codex 官方更新前后。macOS 上 Codex++ 修改过 App,官方 updater 需要先恢复签名版 Codex
codexplusplus update-codex
# Codex 更新完成后,如果 watcher 没自动修复,再手动跑
codexplusplus repair
# 出问题时先进入安全模式,不删除 tweak,只暂停加载
codexplusplus safe-mode
codexplusplus status

# 退出安全模式
codexplusplus safe-mode --off
# 完全卸载并恢复 Codex
codexplusplus uninstall

# 如果想连用户目录也清空(会删除本地 Codex++ 配置和 tweaks)
rm -rf ~/Library/Application\ Support/codex-plusplus
# tweak 开发者常用命令
codexplusplus create-tweak ./my-tweak --id com.you.my-tweak --name "My Tweak" --repo you/my-tweak --scope renderer
codexplusplus validate-tweak ./my-tweak
codexplusplus dev ./my-tweak --replace
{
  "id": "com.you.my-tweak",
  "name": "My Tweak",
  "version": "0.1.0",
  "githubRepo": "you/my-tweak",
  "description": "Adds one small UI improvement.",
  "scope": "renderer",
  "main": "index.js"
}
module.exports = {
  start(api) {
    api.settings.register({
      id: "main",
      title: "My Tweak",
      description: "A tiny test section.",
      render(root) {
        root.innerHTML = "<p>hello from Codex++</p>";
      }
    });
  },
  stop() {}
};

仍然不行怎么办

  • Codex 提示 damaged 或打不开:先跑 codexplusplus doctor,再跑 codexplusplus repair --force;macOS 可按项目文档处理 quarantine。
  • Settings 里看不到 Tweaks:先打开 DevTools 看是否有 [codex-plusplus] 日志,再检查 codexplusplus status;可能是 Codex UI 更新后 Settings DOM 变了。
  • Codex 更新后 Codex++ 消失:这是常见情况,先等 watcher 自动 repair;不行就手动 codexplusplus repair。
  • 某个 tweak 装完后 Codex 异常:先 codexplusplus safe-mode,确认是 tweak 问题后再逐个禁用或删除对应 tweak 目录。
  • Windows 上装完没效果:确认启动的是 Codex++ 快捷方式,不是 Microsoft Store 原 Codex 快捷方式。
  • 你只是想稳定写代码,不想维护补丁:不要装 Codex++,优先用官方 Codex Desktop / CLI 和 AGENTS.md。

它到底改了你电脑上的什么

  • macOS 上会定位 /Applications/Codex.app,备份原文件,然后修改 Contents/Resources/app.asar 的入口,让 Codex 启动时先加载 Codex++ loader。
  • 它会重新计算 app.asar 的 integrity hash,写回 Info.plist,并处理 Electron asar integrity 相关设置。
  • macOS 上需要重新签名 Codex.app。项目默认使用 ad-hoc 签名,也可以用 --local 选择稳定本地签名身份。
  • runtime、配置、日志、tweaks 都放在用户目录,macOS 通常是 ~/Library/Application Support/codex-plusplus/。
  • Windows Store 版 Codex 不容易直接写入,所以 Codex++ 会把 Store app 镜像到 %LOCALAPPDATA%/codex-plusplus/ 下的可写副本,并创建 Codex++ 启动器。
  • 这就是为什么它很强,也为什么它比普通 VS Code 插件、npm 包或 AGENTS.md 风险更高。

目录位置小抄

  • macOS 用户数据:~/Library/Application Support/codex-plusplus/
  • Linux 用户数据:~/.local/share/codex-plusplus/,或 $XDG_DATA_HOME/codex-plusplus/
  • Windows 用户数据:%APPDATA%/codex-plusplus/
  • Windows 管理版 Codex 副本:%LOCALAPPDATA%/codex-plusplus/store-apps/
  • runtime:<user-data-dir>/runtime/
  • tweaks:<user-data-dir>/tweaks/
  • 每个 tweak 自己的数据:<user-data-dir>/tweak-data/<tweak-id>/
  • 日志:<user-data-dir>/log/
  • 备份:<user-data-dir>/backup/
  • 配置:<user-data-dir>/config.json

安装前安全清单

  1. 确认你下载的是 b-nnett/codex-plusplus 官方仓库,不是别人复制的同名仓库。
  2. 先读 README、SECURITY.md、Troubleshooting,至少知道 uninstall、repair、safe-mode 三个命令。
  3. 不要在生产机器、公司受管机器、承载关键服务的机器上先试。
  4. 不要一次安装很多 tweak,先装一个、重启、观察一天。
  5. 安装 tweak 前看 manifest.json:scope 是 renderer / main / both;permissions 是否包含 filesystem、network、mcp、codex.windows。
  6. Tweak Store 里的 approvedCommitSha 说明它按固定 commit 审核;但审核不等于零风险,仍然要看源码和 release。
  7. 涉及文件编辑、MCP、主进程、网络访问的 tweak,要比单纯 UI tweak 更谨慎。
  8. 任何时候发现 Codex 异常,先 safe-mode,不要继续叠加新 tweak。

小白最稳的试用路线

  1. 先不安装,读完这篇文章,确认你确实需要 Codex++。
  2. 新建一个测试 macOS 用户或备用 Windows 环境,避免影响主工作环境。
  3. 用 Homebrew / Bun / PowerShell 安装,不要同时混用多种安装方式。
  4. 安装后只运行 status 和 doctor,不急着装新 tweak。
  5. 先试 Custom Keyboard Shortcuts 或 UI Improvements 这类低风险 UI tweak。
  6. 再试 Goal,把 Codex++ Goal tweak 和 Codex 的长任务目标管理场景对上。
  7. 最后才考虑 Better Terminal、File Editor、Windows Computer Use 这类权限更重的 tweak。
  8. 跑一周稳定后,再决定要不要装到主力机器。

tweak 是怎么被加载的

  • 每个 tweak 是一个文件夹,里面至少有 manifest.json 和 index.js / index.mjs / index.cjs。
  • manifest 必须有 id、name、version、githubRepo;githubRepo 用来检查 GitHub release 更新。
  • scope 默认是 renderer;main 或 both 表示它会进入更高权限的主进程侧。
  • runtime 会扫描 tweaks 目录,读取 manifest,再 require 入口文件,调用 start(api)。
  • renderer 侧 api 包括 settings、react、ipc、fs、storage、log;main 侧可注册 IPC handler。
  • Codex++ 不会自动更新 tweak,它只提示有新 release,让用户自己审查后手动替换。

Tweak Store 的审核模型

  • Codex++ 的 Tweak Store 从 https://b-nnett.github.io/codex-plusplus/store/index.json 读取注册表。
  • 每个条目会固定 approvedCommitSha,也就是管理员审核过的精确 commit。
  • 安装时按 commit archive 下载,而不是直接拉默认分支最新代码,这比随时跟 main 安全。
  • 发布新 tweak 的流程是提交 GitHub repo,生成 issue,让管理员按 commit 审核 manifest、源码和图标。
  • 这能降低供应链风险,但不能代替你自己判断:本地插件仍然是可执行代码。

它和 /goal 命令有什么关系

  • Codex++ Store 里有 Goal tweak,描述是给 Codex Desktop 增加 /goal command 和 active goal UI。
  • 如果你的 Codex CLI 已经有 /goal,但桌面版没有,Codex++ Goal 是一种社区增强路线。
  • 如果你只需要理解 Codex 里的 /goal 怎么用,先看 Codex / Codex++ 相关教程,不要把它当成 Claude Code 通用命令。
  • 如果你要在桌面版里长期管理多小时任务,Goal tweak 才值得尝试。
  • 安装 Goal tweak 前,先确认 Codex++ runtime 版本满足 minRuntime;当前 Store 里 Goal 标注 minRuntime 0.1.6。

常见问题怎么判断

  • Codex is damaged and can't be opened:多半是签名或 Gatekeeper 问题,先 doctor,再 repair --force。
  • App 启动但 Settings 没有 Tweaks:可能 loader 没执行,也可能 Settings DOM 变了。先看日志和 DevTools。
  • Codex 自动更新后 patch 没了:这是预期风险,先 repair;Watcher 正常时会自动处理。
  • 某个 tweak 失败:多半是 manifest JSON 不合法、入口文件路径不对、用了错误模块格式,或者 start() 抛错。
  • Windows 安装后还是原版 Codex:检查你打开的是 Codex++ 启动器,不是 Microsoft Store Codex。
  • uninstall 不完整:项目文档建议必要时重新安装官方 Codex,再重新 install / uninstall。

当前版本状态

  • 截至 2026-05-24,GitHub 最新 release 是 Codex++ 0.1.7,发布时间为 2026-05-12。
  • 仓库显示约 2195 stars、92 forks,许可证是 MIT。
  • 项目自称 Beta,README 明确提示 macOS 与 Windows 已确认可用,但自动更新和新 Codex 更新仍可能有 bug。
  • 近期开着的 issue 里,failed to patch Codex after update / update failed 类问题较多,所以这篇教程不建议小白直接生产使用。
  • 0.1.7 重点是兼容当前 Codex Desktop Settings UI、改善 Windows hook、增强失败诊断、改进更新提示和安全日志脱敏。

参考来源

  • Codex++ GitHub:https://github.com/b-nnett/codex-plusplus
  • Codex++ README:https://github.com/b-nnett/codex-plusplus/blob/main/README.md
  • Codex++ Architecture:https://github.com/b-nnett/codex-plusplus/blob/main/docs/ARCHITECTURE.md
  • Writing Tweaks:https://github.com/b-nnett/codex-plusplus/blob/main/docs/WRITING-TWEAKS.md
  • Troubleshooting:https://github.com/b-nnett/codex-plusplus/blob/main/docs/TROUBLESHOOTING.md
  • Security Policy:https://github.com/b-nnett/codex-plusplus/blob/main/SECURITY.md
  • Tweak Store Registry:https://b-nnett.github.io/codex-plusplus/store/index.json
  • Codex++ 0.1.7 Release:https://github.com/b-nnett/codex-plusplus/releases/tag/v0.1.7

相关问题

还卡着?

可以把截图、日志、需求单或当前页面链接发到 zhemuy@gmail.com。