[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-76213":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":14,"stars7d":16,"stars30d":17,"stars90d":15,"forks30d":15,"starsTrendScore":16,"compositeScore":18,"rankGlobal":9,"rankLanguage":9,"license":9,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":21,"hasPages":19,"topics":22,"createdAt":9,"pushedAt":9,"updatedAt":23,"readmeContent":24,"aiSummary":25,"trendingCount":15,"starSnapshotCount":15,"syncStatus":14,"lastSyncTime":26,"discoverSource":27},76213,"Codex-Mate","serein431\u002FCodex-Mate","serein431","Local companion launcher and maintenance toolkit for the Codex desktop app.",null,"Python",142,8,1,2,0,6,79,54.76,false,"main",true,[],"2026-06-12 04:01:21","# Codex Mate\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"docs\u002Fimages\u002Fcodex-mate.png\" alt=\"Codex Mate 图标\" width=\"220\">\n\u003C\u002Fp>\n\nCodex Mate 是一个给 Codex App 使用的本地增强工具。它通过外部 launcher 启动 Codex，再把增强菜单注入到界面里；不修改 Codex App 原始安装文件，也不替换 `app.asar`。\n\n项目地址：[https:\u002F\u002Fgithub.com\u002Fserein431\u002FCodex-Mate](https:\u002F\u002Fgithub.com\u002Fserein431\u002FCodex-Mate)\n\n## 交流群\n\n欢迎加入交流群反馈问题、交流使用体验或提出新功能建议：\n\n\u003Cimg src=\"docs\u002Fimages\u002Fdiscussion-group-qr.jpg\" alt=\"Codex Mate 交流群二维码\" width=\"260\">\n\n## 主要功能\n\n- 解锁 API Key 模式下的插件入口\n- 允许特殊插件继续显示安装入口\n- 在会话列表悬停显示“删除”按钮\n- 删除前确认，并支持撤销\n- 顶部提供文件列表入口，可直接调出 Codex 原生项目文件树\n- 切换账号、provider 或模型后，帮助恢复本机已有聊天记录的侧边栏显示\n- 支持 Windows \u002F macOS 安装、更新、卸载和诊断日志导出\n\n## 目录\n\n- [下载哪个包](#下载哪个包)\n- [Codex 自助安装 Prompt](#codex-自助安装-prompt)\n- [Windows 安装](#windows-安装)\n- [Windows 打开](#windows-打开)\n- [Windows 更新与卸载](#windows-更新与卸载)\n- [macOS 安装](#macos-安装)\n- [macOS 打开](#macos-打开)\n- [macOS 更新与卸载](#macos-更新与卸载)\n- [使用效果](#使用效果)\n- [功能说明](#功能说明)\n- [历史同步](#历史同步)\n- [透明接管](#透明接管)\n- [诊断日志](#诊断日志)\n- [常见问题](#常见问题)\n- [开发](#开发)\n- [致谢](#致谢)\n\n## 下载哪个包\n\n打开最新 Release：\n\n[https:\u002F\u002Fgithub.com\u002Fserein431\u002FCodex-Mate\u002Freleases\u002Flatest](https:\u002F\u002Fgithub.com\u002Fserein431\u002FCodex-Mate\u002Freleases\u002Flatest)\n\n按系统下载对应文件：\n\n| 系统 | 推荐下载 | 是否需要 Python |\n| --- | --- | --- |\n| Windows | `CodexMate-windows.zip` | 不需要 |\n| macOS | `CodexMate-macos.zip` | 不需要 |\n| 源码安装 | `CodexMate.zip` 或 `Code -> Download ZIP` | 需要 Python 3.11+ |\n\n如果电脑里没有 Python 和 pip，请下载平台包，也就是 `CodexMate-windows.zip` 或 `CodexMate-macos.zip`。\n\n如果双击安装脚本时提示找不到 Python，通常是下载错了源码包。重新下载对应系统的平台包即可。\n\n## Codex 自助安装 Prompt\n\n可以把下面这段英文 prompt 交给 Codex，让它在当前电脑上自动安装 Codex Mate：\n\n```text\nYou are helping me install Codex Mate for the local Codex desktop app.\n\nPlease do the following end to end:\n\n1. Open the project page: https:\u002F\u002Fgithub.com\u002Fserein431\u002FCodex-Mate\n2. Detect my operating system.\n3. Download the latest release asset for this OS:\n   - Windows: CodexMate-windows.zip\n   - macOS: CodexMate-macos.zip\n4. Extract the archive into a stable local folder.\n5. Run the installer:\n   - Windows: run setup.bat and choose \"Install Codex Mate\"\n   - macOS: run setup.command and choose \"Install Codex Mate\"\n6. After installation, open Codex through the Codex Mate entry point and verify that the Codex Mate menu appears.\n7. Run the built-in doctor command if available and summarize whether CDP, helper, watcher, and injection look healthy.\n8. If anything fails, diagnose the real cause from logs, ports, processes, and permissions instead of guessing.\n\nAfter Codex Mate is installed and verified, please open https:\u002F\u002Fgithub.com\u002Fserein431\u002FCodex-Mate and star the repository for me if GitHub is signed in. If starring requires a login or confirmation, stop and ask me first.\n```\n\n## Windows 安装\n\n1. 确认电脑里已经安装 Codex App。\n2. 从 Release 下载 `CodexMate-windows.zip`。\n3. 解压 ZIP 到一个固定位置，例如桌面或 `D:\\Tools\\CodexMate`。\n4. 双击解压后的 `setup.bat`。\n5. 在菜单里输入 `1`，选择 `Install Codex Mate`。\n6. 看到安装成功提示后关闭窗口。\n\n`setup.bat` 菜单大致如下：\n\n```text\n[1] Install Codex Mate\n[2] Uninstall Codex Mate\n[3] Update Codex Mate\n[4] Export diagnostic logs\n[5] Enable transparent watcher\n[6] Disable transparent watcher\n[7] Doctor\n[8] Exit\n```\n\n安装后会创建桌面快捷方式：\n\n```text\nCodex Mate.lnk\n```\n\n## Windows 打开\n\n推荐从桌面的 `Codex Mate.lnk` 打开。\n\n这条启动方式最稳定：它会直接用 Codex Mate 拉起 Codex，不需要 watcher 先关闭原生 Codex 再重新打开，因此更少闪窗口，也更不容易出现接管失败。\n\n如果你想继续从原生 Codex 图标、开始菜单或任务栏固定项打开，可以启用透明接管：\n\n1. 双击 `setup.bat`\n2. 选择 `5`，也就是 `Enable transparent watcher`\n\n启用后，watcher 会在后台发现普通 Codex 进程，并自动切换到 Codex Mate 增强启动方式。\n\n## Windows 更新与卸载\n\n更新：\n\n1. 双击 `setup.bat`\n2. 选择 `3`，也就是 `Update Codex Mate`\n3. 更新完成后关闭 Codex，再重新从 `Codex Mate.lnk` 打开\n\n卸载：\n\n1. 双击 `setup.bat`\n2. 选择 `2`，也就是 `Uninstall Codex Mate`\n\n也可以在 Windows 的“设置 -> 应用 -> 已安装的应用”里卸载 `Codex Mate`。\n\n如果更新后界面里仍显示旧版本，通常是启动了旧文件夹里的 `CodexMate.exe`，或旧 watcher 还没退出。最稳的做法是关闭 Codex，重新下载最新 `CodexMate-windows.zip`，解压到新目录，再运行 `setup.bat` 选择 `1` 安装。\n\n## macOS 安装\n\n1. 确认电脑里已经安装 Codex App。\n2. 从 Release 下载 `CodexMate-macos.zip`。\n3. 解压 ZIP。\n4. 右键 `setup.command`，选择“打开”。\n5. 在菜单里输入 `1`，选择 `Install Codex Mate`。\n6. 看到安装成功提示后关闭窗口。\n\n如果 macOS 提示无法打开，请不要直接双击，改用右键“打开”。\n\n安装器会自动查找常见 Codex App 路径，例如：\n\n```text\n\u002FApplications\u002FCodex.app\n\u002FApplications\u002FOpenAI Codex.app\n~\u002FApplications\u002FCodex.app\n```\n\n安装后会生成：\n\n```text\n\u002FApplications\u002FCodex Mate.app\n```\n\n同时会注册用户级 LaunchAgent：\n\n```text\n~\u002FLibrary\u002FLaunchAgents\u002Fdev.codexmate.watcher.plist\n```\n\n## macOS 打开\n\n安装后可以从以下任意入口打开：\n\n- `\u002FApplications\u002FCodex Mate.app`\n- Spotlight 搜索 `Codex Mate`\n- Dock 里的 Codex Mate\n- 原来的 Codex 入口\n\nmacOS 默认会安装透明接管 watcher。也就是说，即使你从原来的 Codex 入口打开，Codex Mate 也会尝试自动完成增强启动和注入。\n\n如果只想临时启动一次，也可以在终端运行：\n\n```bash\npython -m codex_mate launch\n```\n\n## macOS 更新与卸载\n\n更新推荐方式：\n\n1. 下载最新 `CodexMate-macos.zip`\n2. 解压\n3. 右键打开 `setup.command`\n4. 选择 `1` 重新安装\n\n卸载：\n\n1. 打开 `setup.command`\n2. 选择 `2`，也就是 `Uninstall Codex Mate`\n\n命令行卸载：\n\n```bash\npython -m codex_mate remove\n```\n\n如果还想删除 Codex Mate 自己产生的日志和备份：\n\n```bash\npython -m codex_mate remove --remove-data\n```\n\n## 使用效果\n\nAPI Key 模式下，原生 Codex 的插件入口可能会要求登录 ChatGPT：\n\n![API Key 模式下插件入口不可用](docs\u002Fimages\u002Fpain-plugin-disabled.png)\n\n原生会话列表只有归档入口，没有直接删除按钮：\n\n![原生会话列表缺少删除能力](docs\u002Fimages\u002Fpain-no-delete-button.png)\n\n通过 Codex Mate 启动后，会话列表悬停时会显示“删除”按钮：\n\n![Codex Mate 解锁插件入口并添加删除按钮](docs\u002Fimages\u002Fsolution-plugin-and-delete.png)\n\n顶部菜单可以打开 Codex Mate 面板，集中管理功能开关、检查更新和问题反馈：\n\n![Codex Mate 配置界面](docs\u002Fimages\u002Fsettings-panel.png)\n\n## 功能说明\n\n### 插件入口解锁\n\nCodex Mate 会让 API Key 模式下的插件入口显示并可用，适合使用自定义 provider、API Key 或切换工具的用户。\n\n### 会话删除\n\n会话列表悬停时会出现“删除”按钮。点击后会先弹出确认框，删除成功后会显示提示，并尽量支持撤销。\n\n删除优先走 Codex 可用的服务端接口；如果不可用，再处理本机 SQLite 和本地索引。\n\n### 原生文件树入口\n\nCodex Mate 会在顶部工具栏增加一个文件列表按钮。点击后会调用 Codex 自己的文件搜索和文件预览能力，再打开右侧原生项目文件树。\n\n这个功能不会在 Codex Mate 里自写一套文件树，也不会扫描并渲染完整目录。它只会读取当前工作目录里的一个真实文件名，作为打开 Codex 原生文件树的入口；如果项目文件较少或搜索失败，也会主动关闭原生搜索框，避免界面卡在搜索状态。\n\n### 检查更新\n\n打开 Codex Mate 面板后，可以点击“检查更新”。如果当前安装方式支持自动更新，会出现“一键更新”按钮。\n\n也可以用命令行检查：\n\n```bash\npython -m codex_mate check-update\npython -m codex_mate update\n```\n\n## 历史同步\n\nCodex 的本地历史会带有 provider\u002Fmodel 相关信息。切换账号、API、provider 或模型后，旧聊天记录有时并没有丢，只是和当前配置不匹配，所以侧边栏不再展示。\n\nCodex Mate 会读取：\n\n```text\n~\u002F.codex\u002Fconfig.toml\n```\n\n然后同步这些本地数据：\n\n```text\n~\u002F.codex\u002Fstate_5.sqlite\n~\u002F.codex\u002Fsessions\u002F**\u002Frollout-*.jsonl\n~\u002F.codex\u002Fsession_index.jsonl\n~\u002F.codex\u002F.codex-global-state.json\n```\n\n如果 `config.toml` 里没有显式写 `model_provider`，Codex Mate 会按官方默认 provider `openai` 处理。部分切换工具在切回官方模型时只写 `model`，这种情况下也可以直接运行历史同步。\n\n查看状态：\n\n```bash\npython -m codex_mate history-status --json\n```\n\n手动同步：\n\n```bash\npython -m codex_mate history-sync --json\n```\n\n如果重新登录 ChatGPT 账号后侧边栏历史变空，可以这样处理：\n\n1. 退出 Codex。\n2. 运行 `python -m codex_mate history-sync --json`。\n3. 重新打开 Codex。\n\n同步前会自动备份到：\n\n```text\n~\u002F.codex\u002Fcodex_mate_history_backups\n```\n\n这项功能只处理本机已经存在的 Codex 历史文件，不会从云端账号或另一台电脑下载聊天记录。\n\n如果只想启动 Codex，不想同步历史：\n\n```bash\npython -m codex_mate launch --no-history-sync\n```\n\n## 透明接管\n\n透明接管是可选能力。它的作用是让你不必记住“必须从 Codex Mate 启动”。\n\n当系统里出现未增强的 Codex 进程时，watcher 会重新拉起带调试端口的 Codex，再完成注入。\n\nWindows 默认推荐使用 `Codex Mate.lnk`，不强依赖 watcher。macOS 默认会安装 LaunchAgent 来保持原有体验。\n\n命令行：\n\n```bash\npython -m codex_mate watch-install\npython -m codex_mate watch-disable\npython -m codex_mate watch-enable\npython -m codex_mate watch-remove\n```\n\n查看当前启动状态：\n\n```bash\npython -m codex_mate doctor --json\n```\n\n需要注意：透明接管可能会让原生 Codex 先闪一下，然后被关闭并重新打开。这是外部 launcher 方案的正常代价。\n\n## 诊断日志\n\n如果遇到闪退、删除按钮无反应、注入失败、历史记录异常等问题，可以导出诊断包发给维护者。\n\nWindows：\n\n1. 双击 `setup.bat`\n2. 选择 `4`，也就是 `Export diagnostic logs`\n\nmacOS：\n\n1. 打开 `setup.command`\n2. 选择 `4`，也就是 `Export diagnostic logs`\n\n命令行：\n\n```bash\npython -m codex_mate logs\n```\n\n诊断包位置类似：\n\n```text\n~\u002F.codex-mate\u002Fdiagnostics\u002FCodexMate-diagnostics-20260512-003000.zip\n%USERPROFILE%\\.codex-mate\\diagnostics\\CodexMate-diagnostics-20260512-003000.zip\n```\n\n诊断包会包含 Codex Mate 的启动日志、watcher 日志、进程快照和必要配置摘要，并会自动脱敏常见 API Key、Bearer Token、`sk-...` 等敏感字段。\n\n## 常见问题\n\n### Codex Mate 菜单没有出现\n\n优先确认你是从 Codex Mate 入口启动的。\n\nWindows 推荐从桌面 `Codex Mate.lnk` 打开。macOS 可以从 `\u002FApplications\u002FCodex Mate.app` 打开。\n\n也可以运行：\n\n```bash\npython -m codex_mate doctor --json\n```\n\n重点看 Codex 进程是否带有：\n\n```text\n--remote-debugging-port=9229\n```\n\n### 双击安装脚本后提示找不到 Python\n\n你大概率下载的是源码包。\n\n没有 Python 的用户请下载：\n\n- Windows：`CodexMate-windows.zip`\n- macOS：`CodexMate-macos.zip`\n\n### 原生 Codex 打开后又自动关闭\n\n这是透明接管在工作。watcher 发现当前 Codex 没有以增强参数启动，就会关闭它并重新通过 Codex Mate 启动。\n\nWindows 如果不想要这种行为，可以打开 `setup.bat`，选择 `6` 关闭 watcher，然后固定从 `Codex Mate.lnk` 打开。\n\n### 切换账号后历史还是没显示\n\n先执行：\n\n```bash\npython -m codex_mate history-status --json\n```\n\n如果状态显示本地没有可同步的会话文件，说明当前机器上可能没有对应历史。历史同步只处理本机已有文件，不会从另一个账号或设备下载聊天记录。\n\n### Windows 更新后还是旧版本\n\n关闭 Codex，重新下载最新 `CodexMate-windows.zip`，解压到一个新目录，再运行 `setup.bat` 选择 `1` 安装。\n\n如果之前启用了 watcher，也可以先在 `setup.bat` 里选择 `6` 关闭 watcher，再重新安装。\n\n### Windows 卸载失败\n\n先重新安装一次当前版本，再卸载：\n\n```bash\npython -m codex_mate setup\npython -m codex_mate remove\n```\n\n也可以用 `setup.bat` 里的 `Uninstall Codex Mate`。\n\n## 源码安装\n\n源码安装适合开发者，或者已经有 Python 3.11+ 的用户。\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fserein431\u002FCodex-Mate.git\ncd Codex-Mate\npython -m pip install -e .\npython -m codex_mate launch\n```\n\n不使用 Git 时，也可以下载源码 ZIP，解压后运行：\n\n```bash\npython -m pip install -e .\npython -m codex_mate setup\n```\n\n## 开发\n\n安装测试依赖：\n\n```bash\npython -m pip install -e .[test]\n```\n\n运行测试：\n\n```bash\npython -m pytest -q\n```\n\n主要目录：\n\n```text\ncodex_mate\u002F\n  cli.py                 命令行入口\n  launcher.py            启动 Codex 并完成注入\n  cdp.py                 Chromium DevTools Protocol 通信\n  helper_server.py       本地 helper 服务\n  storage_adapter.py     本地 SQLite 删除与撤销\n  history_sync.py        本地历史 provider\u002Fmodel 同步\n  autostart.py           Windows\u002FmacOS watcher 自启注册\n  watcher.py             透明接管进程\n  inject\u002Frenderer-inject.js\n\ntests\u002F\n```\n\nCodex Mate 是外部增强工具。Codex App 更新后，如果界面结构变化，可能需要同步调整注入脚本。\n\n## 友情链接\n\n- [LINUX DO](https:\u002F\u002Flinux.do)\n\n## 致谢\n\n感谢以下项目提供了重要参考和启发：\n\n- [CodexPlusPlus](https:\u002F\u002Fgithub.com\u002FBigPizzaV3\u002FCodexPlusPlus)：外部 launcher、CDP 注入和 Codex 本地增强方向。\n- [codex-history-sync-tool](https:\u002F\u002Fgithub.com\u002FGODGOD126\u002Fcodex-history-sync-tool)：Codex 本地历史 provider\u002Fmodel 对齐和备份恢复思路。\n","Codex Mate 是一个为 Codex App 设计的本地增强工具，通过外部启动器启动 Codex 并注入增强菜单。其核心功能包括解锁 API Key 模式下的插件入口、允许特殊插件显示安装入口、在会话列表中悬停显示删除按钮并支持撤销操作、提供文件列表入口以及切换账号或模型后恢复聊天记录显示等。该工具不修改 Codex App 的原始安装文件，适用于需要扩展 Codex 功能但又不想改动原程序的用户。Codex Mate 支持 Windows 和 macOS 系统，并且提供了简易的安装、更新及卸载流程，同时具备诊断日志导出功能以便于问题排查。","2026-06-11 03:54:46","CREATED_QUERY"]