必须在插件根目录添加settings.json并声明has_settings_page:true,且settings.json需含title、description、schema和handler字段,handler文件须导出handleSettingsUpdate函数处理保存逻辑。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜

要在 Codex 应用中为自定义插件或 Skill 添加设置页面,必须通过修改其配置文件并注册 UI 入口实现,不能仅靠前端 HTML 或弹窗模拟——Codex 不会识别未声明的设置路径。
确认插件已正确加载并具备设置能力
打开 Codex App → 点击左上角「插件」图标 → 查看目标插件是否显示为「已启用」且状态为绿色。若插件名灰显或带「⚠️」,说明它未完成注册或缺少 settings.json 声明,此时添加设置页无效。
插件根目录下必须存在 【settings.json】 文件,且该文件需导出一个合法 JSON 对象,字段包括 title、description、schema(JSON Schema 格式定义表单项)和 handler(指向处理保存逻辑的函数路径)。
编写 settings.json 配置文件
在插件主目录(如 ./my-skill/)中新建或编辑 settings.json:
```json
{"title": "我的数据处理器设置",
"description": "控制API密钥与超时行为",
"schema": {
"type": "object",
"properties": {
"api_key": {"type": "string", "title": "API密钥", "description": "用于认证第三方服务"},
"timeout_ms": {"type": "integer", "title": "请求超时(毫秒)", "default": 5000}
}},
"handler": "./src/handlers/settings-handler.ts"
}```
注意:schema 中每个字段的 type 必须是 JSON Schema 支持的基础类型(string/integer/boolean/object/array),Codex 不支持自定义 widget 类型或 condition 规则;handler 路径必须相对于插件根目录,且对应文件需导出 async function handleSettingsUpdate(settings: Record
注册设置入口到插件 manifest
打开插件的 manifest.json(或 plugin.yaml,取决于插件类型),在顶层添加:
【"has_settings_page": true】
若使用 YAML 格式,则写为:
has_settings_page: true
此字段是 Codex 加载设置页的开关,缺失将导致插件在「插件」列表中不显示「⚙️ 设置」按钮,即使 settings.json 存在也无效。
实现 settings-handler.ts 处理逻辑
创建 ./src/handlers/settings-handler.ts,内容必须包含:
```ts
import { SettingsUpdateEvent } from '@codex/core';
export async function handleSettingsUpdate(event: SettingsUpdateEvent) {
const { settings, previousSettings } = event;
// 保存到本地存储或触发重连逻辑
await window.localStorage.setItem('my-skill:config', JSON.stringify(settings));
}
```
该函数会在用户点击「保存」后立即执行,Codex 会自动注入 SettingsUpdateEvent 参数。不要在此函数中调用 alert() 或直接操作 DOM,Codex 的设置页运行在受限上下文中,仅允许异步持久化或触发事件。
重启插件并访问设置页
方法一:在 Codex App 中按 Ctrl+R(Windows)或 Cmd+R(Mac)强制重载所有插件 → 找到你的插件 → 点击右侧 ⚙️ 图标。
方法二:在插件目录中执行 【codex-plugin reload --force】(需 CLI 已安装并登录)→ 等待终端返回「Reloaded successfully」→ 切回 App 点击设置图标。
首次加载可能延迟 1–2 秒,因 Codex 需解析 schema 并渲染表单;若页面空白,检查控制台是否有「Failed to load settings handler」错误,大概率是 handler 路径拼写错误或导出函数名不符。


















