如何写出你的第一个Codex++ Tweak：10分钟从manifest.json到设置页（附完整示例代码）

如何写出你的第一个Codex++ Tweak：10分钟从manifest.json到设置页（附完整示例代码）

【免费下载链接】codex-plusplusCodex++ tweak system for the Codex desktop app项目地址: https://gitcode.com/gh_mirrors/co/codex-plusplus

Codex++ 是一个为 Codex 桌面应用提供的tweak 系统，无需重新打包应用就能注入自定义功能。本文将手把手教你写出第一个 Codex++ Tweak：从manifest.json到设置页 UI，10 分钟完成，附完整可运行示例代码。

商店里的 Goal 插件就是一个标准的 Codex++ Tweak

1. Tweak 是什么？

一个 Codex++ Tweak 就是一个文件夹，里面只需要两个文件：

my-tweak/ ├── manifest.json # 描述元信息（必须） └── index.js # 入口脚本（必须，也可以是 .mjs / .cjs）

把它放进你的 tweaks 目录即可生效：

放入后按Cmd/Ctrl+R刷新 Codex（或重启应用），设置页的Tweaks标签里就会出现你的插件。

💡 不想手写？直接运行codexplusplus create-tweak my-tweak，CLI 会生成一套完整的骨架（模板代码见 create-tweak.ts）。

2. 编写 manifest.json：10个核心字段速查

manifest.json是 Codex++ 识别插件的"身份证"，完整字段定义见 WRITING-TWEAKS.md 和 tweaks/AGENTS.md：

最小可用 manifest：

{ "id": "com.you.my-tweak", "name": "My First Tweak", "version": "0.1.0", "githubRepo": "you/my-tweak", "description": "我写的第一个 Codex++ Tweak", "scope": "renderer" }

⚠️ 注意：id只能包含字母、数字、点、下划线和短横线；githubRepo必须是owner/repo格式，否则校验会失败。这些规则实现在 packages/sdk/src/index.ts 的validateTweakManifest()中。

3. 编写 index.js：注册你的第一个设置页

入口脚本默认导出{ start(api), stop() }。对于 renderer 插件，最常用的 API 是api.settings.registerPage()——它会给你的 Tweak 注册一个独立的设置页，侧边栏出现专属入口：

module.exports = { start(api) { api.settings.registerPage({ id: "main", title: "My First Tweak", description: "我的第一个设置页", render(root) { root.innerHTML = ""; const count = api.storage.get("count", 0) + 1; api.storage.set("count", count); const btn = document.createElement("button"); btn.textContent = `你打开了设置页 ${count} 次`; btn.className = "h-token-button-composer rounded-md px-3 text-sm font-medium " + "bg-token-charts-red/10 text-token-charts-red hover:bg-token-charts-red/20 cursor-interaction"; btn.onclick = () => api.log.info("按钮被点击了"); const tip = document.createElement("p"); tip.textContent = "这是来自 Codex++ Tweak 的自定义 UI。"; root.append(btn, tip); }, }); api.log.info("tweak started"); }, stop() { // 清理定时器、事件监听器等（热重载时 stop() 会被调用，保持幂等） }, };

常用api能力一览（完整类型见 packages/sdk/src/index.ts）：

• 📝api.log.info(...)— 输出到日志文件和 DevTools 控制台
• 💾api.storage.get/set/delete— 按插件 ID 隔离的持久化 KV 存储
• ⚙️api.settings.register()— 注册设置行（小功能用），registerPage()— 注册独立设置页（大功能用）
• 🧲api.react.waitForElement(selector)— 等待 Codex 页面元素出现，适合做 UI 注入
• 📡api.ipc.invoke/handle— renderer 与 main 进程通信（需要scope: "both"）

UI 风格小贴士：不要硬编码颜色和尺寸，使用 Codex 自带的 Tailwind token（如text-token-text-primary、bg-token-foreground/5），让插件 UI 与原生气质保持一致。现成的组件片段（开关、卡片、行布局）都写在 tweaks/AGENTS.md 里，直接复制即可。

4. 验证、加载与调试

第 1 步：本地校验 manifest

codexplusplus validate-tweak ~/tweaks/my-tweak

第 2 步：放入目录并热重载

Codex++ 会监视你的 tweak 文件夹，保存即热重载，start()会被重新调用——所以不用自己写文件监视逻辑。

第 3 步：调试

• 打开 DevTools（View 菜单或 Codex 命令面板），控制台过滤[codex-plusplus]
• 主进程报错看<user-data-dir>/log/main.log
• 安装/完整性问题运行codexplusplus doctor
• 想直接探测 Codex 的 DOM？开发时设置环境变量CODEXPP_REMOTE_DEBUG=1启动 Codex，即可通过 Chrome DevTools Protocol 从外部执行 JS（开关在 packages/runtime/src/main.ts）

5. 进阶：用 TypeScript + SDK 编写

想要类型提示？安装官方 SDK 后导入defineTweak：

import { defineTweak } from "@codex-plusplus/sdk"; export default defineTweak({ start(api) { // api 有完整类型提示 }, stop() {}, });

注意：runtime 不会转译 TS，需自行打包成 JS 后再放入 tweaks 目录。SDK 源码在 packages/sdk/，包含TweakManifest、TweakApi、SettingsPage等全部类型定义。

常见问题清单

📚 更多参考：docs/WRITING-TWEAKS.md（API 全解）、docs/ARCHITECTURE.md（架构细节）、docs/TROUBLESHOOTING.md（排错指南）、store/index.json（官方商店插件清单）。

现在，打开编辑器，10 分钟后你就拥有自己的第一个 Codex++ Tweak 了！

【免费下载链接】codex-plusplusCodex++ tweak system for the Codex desktop app项目地址: https://gitcode.com/gh_mirrors/co/codex-plusplus