codex-proxy-rs/docs/plugins.md

插件使用

插件“制品”是按 SHA-256 固定的代码与版本；“配置”是运行实例，保存普通设置、敏感设置和功能范围。 日常使用只维护一个当前配置，同一插件最多启用一个实例

安装 · 完整信任 · 配置与启用 · 使用 · 更新与卸载

flowchart LR
  A[选择来源] --> B[校验包并确认来源]
  B --> C[确认安装并接受制品]
  C --> D[生成默认配置]
  D -->|配置完整且兼容| E[启用并发布]
  D -->|缺少必填项或版本不匹配| F[补充配置或确认风险后启用]

安装包须通过结构、目标平台和进程协议校验；宿主版本范围或能力版本不匹配时提示兼容风险，处理方式见故障处理

安装

在“插件管理”点击安装图标，选择来源：

• 上传包：选择发布者提供的 tar.gz 或 tgz 包
• URL：填写固定下载地址；支持 HTTPS，本机回环地址可使用 HTTP
• GitHub：填写仓库地址或 owner/repo；标签留空查询最新稳定版，预发行版须指定标签

公开来源无需认证。私有来源可选择或创建独立下载认证；认证按来源和用途限制，不会交给插件进程。 下载代理独立选择，默认直连，代理失败不会回退直连。SHA-256 用于固定内容，不证明发布者身份

“下一步”只解析和校验包，不保存制品。检查名称、发布者、版本、平台和摘要后确认安装。随宿主发行物导入的官方制品会显示为“待接受”，也必须先确认信任来源， 未接受的制品不能创建或编辑配置。相同摘要的确认可安全重试

确认安装后，若该插件还没有任何配置，宿主会：

1. 从 schema 填入普通配置默认值，不把敏感字段的默认值写入普通配置
2. 为需要实例范围的贡献项生成默认绑定；模型目录、管理页面、命令行和自动维护按声明注册，入口认证不自动绑定
3. 配置完整且版本兼容时直接启用并发布；缺少必填项或版本不匹配时保存为停用，补充配置或确认风险后再启用

类型错误、非法 schema 或把敏感值混入普通配置会直接拒绝，不会伪装成“待配置”。更新已有插件时不会创建另一套配置， 管理端在包安装完成后提示确认切换，检查通过后应用目标版本，不兼容时保留原版本并打开待调整的设置

完整信任

插件以网关的系统身份访问数据、凭据、配置和网络，宿主不提供安全沙箱或权限清单隔离。 安装即信任全部代码与行为，安全由安装者承担；包格式、摘要和兼容性校验不证明安全。只安装可信来源，升级前确认目标版本

配置与启用

在插件详情中直接启用或停用，设置会保留，无需重新填写。插件没有可设置的参数或认证映射时不显示设置入口

“设置”按当前包的 schema 显示参数，敏感字段单独保存且不回显。每项显示保存状态，留空保留现有值，填写新值替换该项； “清除”只删除对应字段，保存前可撤销。首次补齐必填项后“保存并启用”；其他设置修改保持 原有启停状态。请求处理能力随包自动注册，无需在安装时逐项勾选；可在“高级设置”中调整各挂载阶段的启停、顺序和失败处理。 模型请求阶段支持 Key、分组、模型等作用范围；HTTP、WebSocket 消息和服务调用全局生效，具体匹配由插件处理。 客户端 Key、账号分组、Provider 和模型等范围同时满足才生效，同一范围内任一值匹配即可

“事件观察”分别设置“请求完成与用量”和“上游 WebSocket 事件”；关闭其中一类不影响另一类。 观察用于接收事实；请求、响应或消息改写使用对应的中间件

范围数组为空表示不限制该维度。自动创建的默认绑定不预先绑定 Client Key；普通网关请求仍使用实际请求的 Key。 管理页面和命令行调用模型时另行选择 Client Key，沿用该 Key 的启用状态、范围和预算，计入普通请求用量

frontend_authentication 不会随安装自动接管入口。启用它时必须明确配置外部 principal 到既有 Client Key 的映射； 已停用或删除的 Key 不会因此恢复访问

存在多套配置时，可在“历史配置”中选择并确认替换当前配置，管理端只维护一个当前配置，不提供新增配置入口

若同一插件已有多个启用实例，需先整理为一套才能继续启用或更新，宿主不会自动停用实例或删除配置、密钥与私有数据

声明自动维护的插件可自行准备分组和 Key，无需提供管理员密码。停用会停止维护，但保留这些资源及其原生启用状态； 删除插件配置也不自动删除资源。需要撤销 Key 访问时，在 Key 管理中停用或删除相应 Key

“已启用”表示配置匹配且宿主观察到会话就绪，不是插件业务或外部服务的健康证明。“等待生效”表示候选仍在准备或等待发布；“需要处理”会显示发布或运行失败原因。 “运行状态未知”表示暂时没有运行诊断，启用配置保持不变。详情中的“运行负载”展示当前发布会话的在途调用、执行、排队、恢复等待、驻留回调和活动流；计数可能重叠，不包含其他正在排空的旧版本 并发编辑冲突时应重新加载最新配置后确认，不能覆盖另一窗口的修改

使用

功能	使用方式
管理页面	从插件详情或左侧插件导航打开；页面在隔离 iframe 中运行
自动维护	启用、重启及账号等配置变化后自动对账；失败重试，周期补漏
页面模型请求	每次选择 Client Key，经固定实例版本的 Responses 桥执行，返回原生 JSON 或 SSE
请求中间件、模型路由、账号调度、重试策略、请求观察	匹配功能范围的正常网关请求自动使用；重试策略故障时交给后续处理
上游适配器	为内置 OpenAI / xAI 的生成请求提供上游实现；沿用宿主选号、代理、租约与结算，命中但不可用时拒绝请求
模型目录	原子发布直接别名或适配模型；别名继承目标能力，适配模型按适配器账号范围和声明能力参与既有路由
基础数据页面	通过宿主数据回调读取账号基础信息与已有额度观测，展示本身不进入请求改写链
入口认证	客户端按插件协议访问，宿主把明确的 principal 映射到 Client Key
命令行	在宿主环境运行 codex-proxy-rs plugin <配置 ID> --help

页面模型桥要求管理会话、当前实例/制品/revision 均有效。停用实例、切换版本或 revision、 目标失效后，宿主会在等待首帧和交付响应期间持续复核并取消请求。页面用 Key 标识选择推理身份； 插件中间件仍可读取完整请求头并改写响应，页面桥不提供额外的插件安全隔离

更新、回退与卸载

版本与设置

• 检查更新：GitHub 按保存的策略查询发布，URL 下载并解析当前地址的包；本地上传不支持查询。检查本身不会安装，GitHub 标签也不等于包内版本
• 更新插件：安装新包，再按下述切换规则确认目标版本；字段改名、类型改变或删除等不兼容情况由用户调整，不猜测或静默清空参数与密钥
• 切换版本：在版本列表中选择已安装版本，确认当前版本与目标版本后执行。若该版本已有恢复设置，使用它上次启用时提交的参数、密钥与功能范围；否则从当前设置生成草稿。切换保持启停状态，目标制品必须已接受。停用的历史配置引用旧版本时显示“历史配置”，不表示该版本正在运行
• 回退版本：只列出同一插件已安装、已接受且保留恢复设置的较早版本，恢复对应设置后重新执行兼容检查

没有目标版本快照时，草稿保留当前显式值并补充缺失的 schema 默认值。停用草稿不覆盖最近启用时的恢复点； 未保存或已丢失的设置无法通过快照恢复

宿主更新的检查与恢复要求见插件兼容与发行目录

修改下载来源会先单独保存，取消后续安装也会保留已保存来源。当前浏览器标签页 记住未提交的安装参数和凭据引用，不保存认证明文或上传文件

设置恢复不等于私有数据恢复。私有数据迁移仍由插件声明的迁移能力处理，不兼容且无迁移路径时不能切换；迁移失败会尝试 恢复原版本，若恢复会覆盖并发修改则保持停用并提示处理。配置检查或候选准备失败不会覆盖当前设置

接口弃用提示展示兼容窗口与作者说明，不改变插件启停状态；规则见 接口弃用

故障处理

宿主启动时检查插件清单、RPC、平台、宿主范围和已声明能力版本。不兼容实例保持未启动，不挂载能力或故障占位，启用配置、绑定、密钥与私有数据保留；这同样适用于 Docker 与手工升级

宿主范围或能力版本不匹配时，页面以黄色三角感叹号标记，悬浮或点击显示“未启动：版本不兼容”及原因。在插件详情点击启动，确认“启动不兼容版本可能导致系统不稳定”后可尝试；确认只适用于当前宿主、插件包和配置版本的本次启动，下次宿主启动重新检查。配置或目标变化后需要重新确认，成功启动后仍保留兼容性提醒

包损坏、清单或 RPC 格式不兼容、平台不符时显示具体原因，不能强行启动，需更换兼容包。未启动插件提供的额外认证、拦截与其他能力不生效，宿主原生认证继续执行。版本要求见 SDK，重启检查见部署说明

通过兼容检查后，RPC 握手失败或运行中进程崩溃、帧边界、调用关联或传输错误会使对应实例未就绪， 显示红色三角感叹号及脱敏错误详情，保留启用配置，可在详情中重新启动或切换版本。连续故障受重启次数限制

能力响应无法解码只使当前调用失败；上游 429、用户请求错误和插件主动拒绝请求等业务结果不会直接停止插件。单个插件故障不撤销整个宿主的运行配置；命中故障插件绑定的请求仍遵循既有拒绝或委托策略，包括全局 HTTP 绑定覆盖的管理请求。已进入执行集合的入口认证插件故障不会降级到其他认证方式

插件中间件达到调用容量或排队上限时，HTTP 响应为 503（middleware_capacity_unavailable），不会跳过插件或重放请求。 应结合插件耗时和并发负载排查；会话预算与作者侧配置见 SDK 并发与期限

停用与删除

操作	删除什么	保留什么
停用	不删除；新请求不再使用	配置、密钥、私有数据和版本
删除配置	该配置及其密钥、私有数据、版本配置快照；无法撤销	已安装版本
删除版本	所选制品、对应配置快照及其已无引用的下载认证；最后一个版本还会清理来源规则；被配置或在途调用引用时不能删除	其他版本与配置、共享下载认证
卸载插件	确认范围内的配置、插件私有数据、版本、来源规则及已无引用的下载认证	其他插件仍使用的下载认证、审计记录

卸载不是跨多个请求的事务；失败时会显示已完成结果，可重试剩余步骤，不会扩大到确认后新增的配置。只想暂时停用时不要卸载。 完整卸载后重新安装可重新选择来源。独立创建但未被删除版本使用的下载认证不会被顺带删除。 通过用量服务写入的明细与聚合统计不会随插件停用、删除配置或卸载而删除。明细遵循宿主请求历史保留策略，聚合由写入方管理清理；删除插件前按需使用其数据清理功能

需要保留数据时，删除前按部署、备份与恢复保存备份

开发插件见 SDK 与 插件 CLI； 完整示例在独立的 codex-proxy-plugins 仓库维护。HTTP 字段与限制见 API 参考