配置参考

opencodex 使用 ~/.opencodex/config.json 配置。ocx init 和仪表盘会写入该文件，你也可以直接 编辑；代理会在启动时重新加载。服务运行期间请优先停止代理或改用仪表盘/管理 API 再手改：进程会把配置放在内存里，中途保存可能用内存快照覆盖磁盘。自 v2.7.41 起，手改的 claudeCode 子树在这些保存中会被保留；其他键（例如 providers）仍可能被覆盖。如果文件无法解析（例如被截断或不是有效 JSON），opencodex 会将 其备份为 config.json.invalid-<timestamp>，在 console 中警告，再以默认值启动。文件缺失时也会 回退到默认配置（单个 openai forward provider）。

保留的 OpenAI providers

openai 和 openai-apikey 是固定保留 id。openai.codexAccountMode 默认为 "pool"，会在主账户和 添加账户中选择；"direct" 只使用当前 Codex caller/主登录。API 只使用配置的 API key/key pool。 通过 bare 模型或 openai-apikey/<model> 选择，凭证路径间没有 fallback。API GPT-5.6 元数据为 1,050,000 context / 922,000 max input，Pro virtual id 在线上 改写为 base 模型加 reasoning.mode: "pro"。

openaiProviderTierVersion: 2 标记当前单一 provider projection。迁移 shipped v1 配置之前，会以 no-replace 方式创建 config.json.pre-openai-tiers-v2.bak，并把已知旧 namespaced selected id 改为 bare id。

顶层（OcxConfig）

Field	Type	Default	含义
port	number	10100	代理监听端口。
hostname?	string	"127.0.0.1"	绑定地址。设为 "0.0.0.0" 可暴露到 LAN（需要 OPENCODEX_API_AUTH_TOKEN；见下文 远程访问）。
proxy?	string	—	出站 HTTP(S) proxy URL 或 ${ENV_VAR} 引用。对应 env 未设置时应用到 HTTP_PROXY / HTTPS_PROXY；loopback 会保留在 NO_PROXY 中。
providers	Record<string, OcxProviderConfig>	—	provider 名称 → 配置的映射。
openaiProviderTierVersion?	2	migration 设置	单一选项式 OpenAI projection 完成标记。
defaultProvider	string	"openai"	路由找不到更优匹配时使用的 provider。
subagentModels?	string[]	gpt-5.5、三款 GPT-5.6、gpt-5.4-mini	最多 5 个原生 slug 或 provider/model id，优先显示在 Codex subagent picker 中。v2 指引清单是已配置模型与 Codex 中 picker 可见、兼容 v2、按 priority 排序后前五项的交集，并使用规范目录 slug 与可用 effort 档位；被排除的条目仍保留在配置中。显式空数组会被保留。
injectionModel?	string	—	首选原生或路由子代理模型。它用于由独立 multiAgentGuidanceEnabled 控制、OpenCodex 编写的 v2 委派指引；选择 syncCodexSubagentDefaults 后，也可将其用作新任务的 Codex 原生默认值。
injectionEffort?	string	—	首选子代理 reasoning effort（low 到 ultra）。只有与 injectionModel 一起使用才有意义；它用于委派指引，并可在选择同步后作为 Codex 原生默认值。
syncCodexSubagentDefaults?	boolean	false	当 OpenCodex 管理当前 Codex 路由时，选择是否在下一次同步或重启把已选的 injectionModel / injectionEffort 应用为 Codex 原生 [agents] 子代理默认值。外部用户管理的 provider 配置不会被修改。这些默认值只影响新建 Codex 任务，本身不会触发委派。已有的用户自有目标条目会作为冲突保留而不会被覆盖。此字段要求 injectionModel；清除模型会同时关闭该选项。它作为 GET/PUT /api/injection-model 的部分更新字段提供。
effortCap?	string	—	reasoning effort 的逐请求硬上限。这是多代理 V2 专属功能：适用于工具列表带有 V2 协作表面的主轮次，以及标记精确匹配 x-openai-subagent: collab_spawn 或 x-codex-turn-metadata 中 "subagent_kind": "thread_spawn" 的派生子轮次（带标记的子轮次无论自身工具表面如何都会被覆盖）。普通主轮次与 V1 表面主轮次不受影响，压缩（compaction）轮次始终绕过上限，multiAgentMode: "v1" 会完全禁用上限功能（仪表盘同时隐藏该面板）。接受 low 到 ultra；只会降低 effort，绝不会提高。会降至不高于上限的最高受支持档位。若模型不提供 effort 控制，或上限之下没有可用档位，则移除 effort 字段并采用 provider 默认值。max 和 ultra 均可使用，但不会形成更低的等级上限（客户端会将 ultra 转换为 max，因此请求以 low 到 max 的范围到达）；不过，已知的模型 effort 阶梯仍可能触发降档或移除字段。仪表盘选择器提供 low 到 xhigh。通过 GET /api/effort-caps 和 PUT /api/effort-caps 管理。
subagentEffortCap?	string	—	同样的硬上限，但只用于 codex-rs 标记精确匹配的派生子轮次：x-openai-subagent: collab_spawn，或 x-codex-turn-metadata 中的 "subagent_kind": "thread_spawn"。其他内部子代理类别（评审、压缩、记忆整理）不会触发此上限，multiAgentMode: "v1" 会完全禁用该功能。接受 low 到 ultra；两个上限同时设置时取较低者，且只会降低 effort，绝不会提高。会降至不高于上限的最高受支持档位。若模型不提供 effort 控制，或上限之下没有可用档位，则移除 effort 字段并采用 provider 默认值。max 和 ultra 均可使用，但不会形成更低的等级上限（客户端会将 ultra 转换为 max，因此请求以 low 到 max 的范围到达）；不过，已知的模型 effort 阶梯仍可能触发降档或移除字段。仪表盘选择器提供 low 到 xhigh。通过 GET /api/effort-caps 和 PUT /api/effort-caps 管理。
injectionPrompt?	string	—	整体替换注入的 v2 指南正文的自定义文本。{{model}}、{{effort}}、{{roster}} 占位符会被替换，触发条件保持不变。也可通过 PUT /api/injection-model 的 prompt 键设置。
multiAgentGuidanceEnabled?	boolean	true	仅控制由 OpenCodex 添加的 multi-agent developer 指引。未设置/true 保持 v1/v2 指引；false 会同时禁止两者，但不改变 Codex 原生 [agents] 默认值、协作界面、subagentModels、路由或 effort 上限。GET/PUT /api/injection-model 返回有效值，PUT 为部分更新。
disabledModels?	string[]	—	从 Codex 隐藏的模型。路由 provider/model id 会从目录和 /v1/models 排除；bare 原生 GPT slug（如 gpt-5.4）的目录条目会改成 visibility: "hide"，并从 bare /v1/models 列表移除。可在仪表盘 Models 页面按模型切换。
multiAgentMode?	"v1" | "default" | "v2"	"default"	三态 multi-agent surface override。"v1" 覆盖 upstream pin，强制全部模型使用 v1；"default" 遵循 upstream model pin（sol/terra=v2，luna=v1）；"v2" 强制全部模型使用 v2。可在仪表盘 Models 页面或 ocx v2 mode 中设置。
providerContextCaps?	Record<string,number>	{}	provider 级 Codex 可见 context cap。只会降低已知 context window。
contextCapValue?	number	350000	仪表盘 context-cap 控件使用的值；修改后会更新 providerContextCaps 中所有已启用条目。
stallTimeoutSec?	number	600	上游无数据后 bridge 中止并发出 response.incomplete 前等待的秒数。最小值 1。
connectTimeoutMs?	number	200000	每次尝试仅等待 DNS/TCP/TLS 和最终响应 header 的 deadline；在响应 body 生成前结束。
shutdownTimeoutMs?	number	5000	中止活跃 turn 前的 graceful drain deadline。
websockets?	boolean	false	公布 supports_websockets，让 Codex 使用 Responses WebSocket 路径。省略或设为 false 会保持 HTTP/SSE。
apiKeys?	OcxApiKey[]	[]	非 loopback 绑定下额外接受的生成式 ocx_… data-plane credential。它不是 ADMIN credential。由仪表盘管理；条目字段见下文。
codexAutoStart?	boolean	true	允许 Codex shim 在启动 Codex 前运行 ocx ensure。false 会让 ocx ensure 不执行任何操作。
codexShimAutoRestore?	boolean	true	已完成的外部 Codex 更新替换此前安装的 shim 时自动恢复。若要关闭，请设为 false，或为进程设置 OPENCODEX_CODEX_SHIM_AUTO_RESTORE=0。
syncResumeHistory?	boolean	true	可逆的 Codex App 历史兼容模式。opencodex 会备份原始 Codex thread metadata，把旧 OpenAI interactive row 重映射到 opencodex，并暂时把 opencodex 创建的 exec row 提升成 App 可见 source。ocx stop / ocx restore 会恢复已备份的 OpenAI row，并把剩余 opencodex user thread 转回 OpenAI，使原生 Codex 在从 config.toml 移除代理后仍能继续这些 thread。设为 false 可退出该模式。
codexAccounts?	CodexAccount[]	[]	Codex Auth 仪表盘管理的 ChatGPT/Codex pool account metadata。secret 单独存放在 codex-accounts.json。
pausedCodexAccountIds?	string[]	[]	在 Codex Auth 中恢复前，不参与任何后续 Pool 选择的账号 ID。暂停主账号时也包含 __main__。
codexAccountNamespaces?	Record<string,string>	—	可选的公开 model selector namespace 到已保存 Codex account target 的映射。此 foundation layer 只验证并持久化该映射，不会添加 picker row 或改变 routing。
activeCodexAccountId?	string	—	手动选择的 pool account。选择时清除已有 thread affinity，并从下一次请求开始生效；进行中的请求保留原账号。
autoSwitchThreshold?	number	80	新 session 自动切换的 usage 百分比 threshold。分数取已知 5 小时、周或 30 天 quota window 中最高的一项。设为 0 可禁用 quota 自动切换。quota 策略和 fill-first 的耗尽 threshold 都会用到。
accountPoolStrategy?	"quota" | "round-robin" | "fill-first"	"quota"	Codex pool 的新 session 轮换策略。仅适用于新 session；已有 thread id 保留 affinity。quota（默认）：活跃账号超过 autoSwitchThreshold 时选已知 usage 最低者。round-robin：在合格账号间平滑加权均分。fill-first：持续使用活跃账号，直到 cooldown、不可用或（如已设置）超过 autoSwitchThreshold（未知 usage 不会强制切换），再按稳定排序进入下一个合格账号。
accountPoolStickyLimit?	number	1	一次 round-robin 选择在推进前保留的成功新 session 绑定数。范围 1–100；仅当 accountPoolStrategy 为 round-robin 时生效。
upstreamFailoverThreshold?	number	3	连续发生多少次临时上游失败后，让后续新 session failover 到其他合格 pool account。设为 0 可禁用失败切换。
modelCacheTtlMs?	number	300000	每个 provider 的 /models 缓存新鲜度窗口（5 分钟）。
cacheRetention?	"none" | "short" | "long"	"short"	Anthropic prompt-cache 策略：禁用、5 分钟 ephemeral 或 1 小时 extended。
webSearchSidecar?	OcxWebSearchSidecarConfig	开启	网络搜索 sidecar 选项（见下文）。
visionSidecar?	OcxVisionSidecarConfig	开启	视觉 sidecar 选项（见下文）。
tokenGuardian?	OcxTokenGuardianConfig	关闭	可选的 proactive OAuth 刷新和 Codex account warmup 策略；字段见下文。
corsAllowOrigins?	string[]	[]	CORS 额外允许的精确 origin。loopback origin 始终允许。

codexAccountNamespaces 的 key 是公开 selector：长度为 1–64 个字符，首尾必须是 ASCII 字母或数字， 中间可使用字母、数字、.、_ 或 -；保留的 JavaScript object 名称会被拒绝。value 必须是有效的 pool account id（不能是内部 __main__），或用 "@main" 表示 Codex Desktop 账号。与 provider 及 保留的 openai / combo 冲突时不区分大小写；带 namespace 的 combo alias 不能把 selector 复用为 其 namespace prefix，已配置的 pool id 和其他 selector target 也不能复用为 selector。raw account id 与 email 应保持私密，selector 才是公开名称。在此 foundation layer 中， 该映射是 inert 的：不会创建 model picker entry、固定 session，也不会改变 Pool / Direct routing。

maxConcurrentThreadsPerSession 是 PUT /api/v2 使用的 camel-case 字段，不是 config.json key。 ocx v2 threads <n> 会把对应的 max_concurrent_threads_per_session 值写入 Codex $CODEX_HOME/config.toml 的 [features.multi_agent_v2] 下；请先启用 v2，确保该 table 存在。

如果旧开发构建在支持备份前已运行 syncResumeHistory，也可用 ocx recover-history --legacy-openai 强制执行相同的 native-provider 恢复。

Codex 账号池

请在仪表盘 Codex Auth 页面添加 pool account 并刷新 quota。配置只保存非 secret account metadata；access/refresh token 存放在加固的 Codex account credential store 中。已有 thread id 会 保留 account affinity；新 session 按 accountPoolStrategy、quota、cooldown 和 health 自动路由。 暂停后仍会显示账号及其 quota metadata，但不会参与自动切换、重试/failover 选择、cooldown 恢复探测或手动激活。 暂停还会清除该账号的 thread affinity map：进行中的请求保留已捕获的 credential，但后续 turn 会重新路由，无法再使用已暂停账号。 暂停状态会跨重启保留；如果所有账号均已暂停，Pool 路由会明确失败，而不会暗中选择某个账号。 暂停已达上限账号 会先刷新有 credential 的合格账号，只暂停相关 quota window 本次明确返回 100% 的账号；无 credential、未知额度或刷新失败的账号保持不变。

轮换策略（仅新 session；已绑定 thread 不变）：quota（默认）— 活跃账号 usage 超过 autoSwitchThreshold 时选最低者；round-robin — 均分，accountPoolStickyLimit（默认 1， 1–100）控制一次选择保留多少成功绑定；fill-first — 耗尽活跃账号（cooldown、需重新认证或 threshold；未知 usage 不强制切换）后按稳定排序进入下一个。轮换不能规避 provider enforcement — 多账号使用可能违反服务条款。

受管 record 形状

apiKeys[] 条目包含 id: string、name: string、生成的 key: string 和 ISO 格式的 createdAt: string。codexAccounts[] 条目包含必需的 id、email、isMain，以及可选的 plan、chatgptAccountId 和不含隐私的 logLabel 字符串。这些 record 通常由仪表盘管理。

tokenGuardian（OcxTokenGuardianConfig）

Field	Type	Default	含义
enabled?	boolean	false	proactive refresh 总开关。
tickSeconds?	number	21600	sweep 间隔（6 小时，最少 60 秒）。
jitterSeconds?	number	300	sweep 前增加的随机延迟。
concurrency?	number	3	每次 sweep 最多同时刷新多少项。
leadSeconds?	number	900	在一个 tick 之外额外预留的刷新提前量。
failureBackoffBaseSeconds?	number	300	首次临时失败 backoff。
failureBackoffMaxSeconds?	number	3600	backoff 上限和永久失败延迟。
codexWarmupEnabled?	boolean	false	选择启用合成 Codex pool-account 验证。
codexWarmupMaxAgeSeconds?	number	691200	账号在 8 天后重新验证。
codexWarmupModel?	string	gpt-5.4-mini	可选 warmup 使用的原生模型。

远程访问

opencodex 默认只绑定到 127.0.0.1（loopback）。当 hostname 设置为 0.0.0.0 等非 loopback 地址时，data plane 和 management API 会由不同 credential 分别保护。

启动前设置 OPENCODEX_API_AUTH_TOKEN：

export OPENCODEX_API_AUTH_TOKEN="your-secret-token"
ocx start

非 loopback 绑定缺少该变量或生成的 apiKeys 时，代理会拒绝启动。若要为 LAN 访问安装后台服务， 也应先 export 同一变量，再运行 ocx service install，让 launchd、systemd 或 Task Scheduler 收到 token。data-plane 客户端必须在每个请求的 x-opencodex-api-key header 中提供 credential：

x-opencodex-api-key: your-secret-token

也可以使用 Authorization: Bearer … header。启动后，仪表盘生成的 apiKeys 可代替环境 token， 但不会授予 /api/* 权限。

management API 和远程仪表盘需要单独的 ADMIN token。OpenCodex 会在启动时把它创建在受保护的本地 secret file 中，也可使用 OPENCODEX_ADMIN_AUTH_TOKEN。远程仪表盘会提示输入此 ADMIN 值，并拒绝 data-plane key。所有 credential 均以常量时间（timingSafeEqual）比较。

Material 3 仪表盘的 连接到另一台 OpenCodex 可手动输入 IPv4、IPv6 或 DNS 主机名，以及远端的 实际运行端口。它不会 probe 远端、把 token 放入 URL 或保存 token。若自动启动使用了 fallback 端口， 请使用 ocx host status 或 ocx status 的 identity-verified live 值，而不要只看 config.port。

LAN 暴露

绑定到 0.0.0.0 会把代理和所有已配置 provider credential 暴露到本地网络。只应在可信网络中 HTTP 未加密。只应在可信网络中使用，并设置强 data-plane 与 ADMIN credential；不可信链路请优先 使用 SSH port forwarding。

Providers（OcxProviderConfig）

Field	Type	含义
adapter	string	openai-chat、openai-responses、anthropic、google、kiro、cursor、azure-openai（或别名 azure）之一。
baseUrl	string	上游 API base URL。端点固定的内置 provider 会忽略它 —— 见固定的 provider 端点。
responsesPath?	string	key 认证的 openai-responses 请求可选相对 resource path。必须以 / 开头，且不得包含 URL scheme、query 或 fragment。省略时保留原有的 /v1/responses URL 构造。
disabled?	boolean	配置保留在磁盘上，但从路由和模型/目录列表排除。
apiKey?	string	API key，或在请求时解析的 ${ENV_VAR} / $ENV_VAR 引用。
apiKeyTransport?	"x-api-key" | "bearer"	Anthropic API key 的请求头方式。默认使用原生 x-api-key；兼容 gateway 要求 Authorization: Bearer <key> 时设为 "bearer"。仅适用于使用 key 认证的 anthropic provider。
apiKeyPool?	ApiKeyPoolEntry[]	多 key pool。apiKey 映射当前活动条目；每项包含 id、key、可选 label 和可选数字 addedAt。
defaultModel?	string	选中该 provider 但未指定明确模型时使用的模型。
models?	string[]	seed/fallback 模型列表。liveModels 为 false 时，只会发现这些模型。
liveModels?	boolean	启动/同步时获取 provider 的实时 /models 目录（默认 true）。设为 false 时只使用配置的 models。
selectedModels?	string[]	模型发现后应用的目录 allowlist。非空时只向 Codex 暴露这些 id；为空或省略时暴露所有发现的模型。
contextWindow?	number	路由目录条目的 provider 级 Codex 可见 context-window cap。实时 metadata 更小时保留实时值。
modelContextWindows?	Record<string,number>	模型级 context-window cap。匹配模型时优先于 contextWindow，且不会抬高更小的实时 metadata。
modelInputModalities?	Record<string,string[]>	模型级目录 input hint，如 ["text"] 或 ["text", "image"]。
headers?	Record<string,string>	额外上游 header。Authorization、cookie、API-key header、包含换行的值和无效 header 名称会被拒绝。
openRouterRouting?	OpenRouterProviderRouting	默认 OpenRouter provider 路由设置。支持 order、only 和 allowFallbacks；仅适用于 canonical OpenRouter URL 和 openai-chat adapter。
modelOpenRouterRouting?	Record<string,OpenRouterProviderRouting>	按精确模型 id 覆盖 openRouterRouting。
authMode?	"key" | "forward" | "oauth"	认证方式（默认 key）。参见 Providers。
codexAccountMode?	"pool" | "direct"	仅用于 canonical openai。省略时默认 Pool；Direct 会绕过池状态。
refreshPolicy?	"proactive" | "lazy-only" | "disabled"	覆盖该 OAuth provider 的 Token Guardian 策略。
reasoningEfforts?	string[]	provider 级需要公布和发送的 Codex reasoning label（low、medium、high、xhigh、max、ultra）。
modelReasoningEfforts?	Record<string,string[]>	模型级 reasoning label。空数组会隐藏该模型的 effort 控件。
modelSupportsReasoningSummaries?	Record<string,boolean>	模型级 reasoning summary 能力。设为 false 时不再声明 summary 支持，并在 openai-responses 请求前移除 summary-delivery 字段。
modelReasoningSummaryDelivery?	Record<string,"sequential" | "sequential_cutoff" | "concurrent" | "concurrent_cutoff">	模型级 Responses delivery enum。已配置模型保持 summary 能力，适配器只改写现有的 stream_options.reasoning_summary_delivery；同一模型不能同时将 summary 能力设为 false。
reasoningEffortMap?	Record<string,string>	provider 级 reasoning label wire alias。只在上游需要不同值时使用。
modelReasoningEffortMap?	Record<string,Record<string,string>>	模型级 reasoning label wire alias。
noReasoningModels?	string[]	拒绝 reasoning/thinking 参数的模型；adapter 会为它们移除 reasoning_effort。
noTemperatureModels?	string[]	拒绝调用方指定 temperature 的模型。
noTopPModels?	string[]	拒绝调用方指定 top_p 的模型。
noPenaltyModels?	string[]	拒绝 presence/frequency penalty 的模型。
parallelToolCalls?	boolean	启用或禁用并行工具调用。OpenAI Chat 默认开启；非 chat adapter 只有显式为 true 时才公布支持。
autoToolChoiceOnlyModels?	string[]	tool_choice 只接受 auto 或 none 的模型；forced/named 选择会降级。
preserveReasoningContentModels?	string[]	要求在 chat history 中保留先前 assistant reasoning_content 的模型。
thinkingToggleModels?	string[]	使用 vendor thinking.enabled toggle，而不是 effort ladder 的 chat 模型。
thinkingBudgetModels?	string[]	使用整数 thinking_budget 的 chat 模型；effort 会映射成 budget 比例。
noVisionModels?	string[]	纯文本模型；视觉 sidecar 会为它们描述图像。匹配时容忍 Ollama :size 标签。
escapeBuiltinToolNames?	boolean	Umans 等 Anthropic 兼容 gateway 可能要求在 wire 上转义工具名；opencodex 会在把 tool call 返回 Codex 前移除 prefix。
googleMode?	"ai-studio" | "vertex" | "cloud-code-assist"	Google transport/auth mode。默认 ai-studio。
project?	string	Vertex project id 或 Antigravity Cloud Code Assist project id。
location?	string	Vertex location；env fallback 为 GOOGLE_CLOUD_LOCATION。
mcpServers?	Record<string,CursorMcpServerConfig>	仅 Cursor。 通过 stdio 启动或 Streamable HTTP 连接的 MCP server；字段见下文。
desktopExecutor?	DesktopExecutorConfig	仅 Cursor。 外部 computer-use/record-screen 命令；字段见下文。
unsafeAllowNativeLocalExec?	boolean	仅 Cursor adapter。 允许 Cursor server 驱动本地 read / write / delete / ls / grep / shell / fetch 的 opt-in escape hatch。默认 false，防止远程 Cursor message 绕过 Codex 审批与 sandbox。见下文 Cursor provider。

固定的 provider 端点

路由会在任何 adapter 介入之前解析 provider 的端点；对大多数内置 provider 而言，registry 自带的端点 优先于你在配置里写的 baseUrl。在这一步保留配置 URL 的只有三类：

• 显式开启覆盖的 provider —— ollama、vllm、lm-studio、litellm、qwen-cloud 和 alibaba-token-plan-intl；
• registry 端点本身是待填模板的 provider，例如 azure-openai 和 cloudflare-ai-gateway；
• 你自己定义的 provider，它们根本不在 registry 中。

之后 adapter 仍可能调整已解析的 URL。例如 kiro adapter 在 host 为标准 runtime.{region}.kiro.dev 时，会改用导入凭据所属的 API region。逐个 adapter 的规则见 Adapters。

当路由丢弃配置的 baseUrl 时，opencodex 会打印一条警告：registry 端点会完整列出，而你配置的那个 只列出 origin —— 原本带路径时显示为 https://host/…。配置的路径本身可能就是凭据，因此一段都不会记录。 此时要么删掉 baseUrl（路由本来就只会使用 registry 端点），要么改用端点与目标 URL 相符的 provider。 当同一产品分区域运营时，选对条目尤其重要：alibaba-token-plan 固定指向北京，而 alibaba-token-plan-intl 覆盖国际端点，为其中一个签发的 key 在另一个上会被拒绝。

Cursor provider（adapter: "cursor"）

Cursor bridge 仍属实验功能。运行 ocx login cursor 后，在 ~/.opencodex/config.json（Windows：%USERPROFILE%\.opencodex\config.json）的 providers 下 添加或编辑 cursor 条目。

Cursor server 驱动的原生本地工具默认保持禁用。Codex 继续按自身审批和 sandbox policy 使用 apply_patch、exec_command 等工具。只有在可信本地实验中，且你接受 Cursor 绕过 Codex 审批 读取、写入、删除、列出、grep、shell 或 fetch 本机内容时，才设置 unsafeAllowNativeLocalExec。

{
  "providers": {
    "cursor": {
      "adapter": "cursor",
      "baseUrl": "https://api2.cursor.sh",
      "authMode": "oauth",
      "defaultModel": "auto",
      "unsafeAllowNativeLocalExec": true
    }
  }
}

该 flag 应放在 provider 对象（providers.cursor）上，而不是 config.json 顶层。

也可在 Web 仪表盘 中设置：进入 Providers → Cursor → Edit JSON，添加 "unsafeAllowNativeLocalExec": true，保存后重启代理 （ocx restart 或 ocx stop + ocx start）。

MCP、屏幕录制和 computer-use 使用独立的 mcpServers / desktopExecutor 配置，不受该 flag 控制。

Cursor 集成 record

每个 mcpServers.<name> 值接受 command（stdio）或 url（Streamable HTTP）之一。stdio 条目还 接受 args?: string[]、env?: Record<string,string>、cwd?: string；HTTP 条目接受 headers?: Record<string,string>。两种形式都支持 enabled?: boolean（默认 true）和 toolPrefix?: string。

desktopExecutor 接受 computerUseCommand?、recordScreenCommand?、cwd?、 env?: Record<string,string> 和 timeoutMs?（默认 30000）。命令经 sh -c 运行，从 stdin 读取一个 JSON 请求，并必须向 stdout 写出一个 JSON 结果。

安全

除非你明确需要绕过 Codex 审批与 sandbox 语义的 Cursor 原生本地执行，否则请省略 unsafeAllowNativeLocalExec 或保持为 false。

OpenRouter provider 路由

同一模型的不同 OpenRouter endpoint 在 prompt cache 支持、命中率、保留时间和价格方面可能存在显著差异。 使用 openRouterRouting 指定默认 provider，使用 modelOpenRouterRouting 为精确模型 id 覆盖设置。 这些设置会转换为 OpenRouter 请求中的 order、only 和 allow_fallbacks 字段。 当 allowFallbacks: false 时，指定 provider 不可用会使请求失败，而不会切换到其他 endpoint。

{
  "openRouterRouting": { "order": ["deepseek"], "allowFallbacks": false },
  "modelOpenRouterRouting": {
    "anthropic/claude-sonnet-5": { "only": ["anthropic"], "allowFallbacks": false }
  }
}

静态模型 allowlist

部分 provider 的实时模型目录非常大或很慢。若只想让 Codex 看到 models 中固定的模型，请把 liveModels 设为 false。

当 liveModels 为 false 且 models 为空或省略时，opencodex 不会为该 provider 暴露任何 路由模型。

selectedModels 的用途不同：模型发现仍会运行，但只有选中的 id 会发布到 Codex 目录和 /v1/models。仪表盘仍保留完整模型列表，因此之后可以修改 allowlist。

Preview GPT-5.6 fallback 条目采用相同机制。OpenAI API-key preset 会以 context 1050000、 max input 922000 seed base 和 Pro id；OpenRouter preset 会以 context 1050000 seed openai/gpt-5.6-sol、terra、luna。Pool/Direct 的 Codex 目录契约为 372000；同步后的 Codex 目录会公布 max reasoning，同时与 xhigh 保持 区分。保持 liveModels 开启可把实时 provider 结果与这些显式条目合并；设为 false 则只暴露 models。

{
  "providers": {
    "openrouter": {
      "adapter": "openai-chat",
      "baseUrl": "https://openrouter.ai/api/v1",
      "apiKey": "${OPENROUTER_API_KEY}",
      "liveModels": false,
      "models": ["deepseek/deepseek-v4-flash", "qwen/qwen3-coder-plus"]
    }
  }
}

Sidecars

webSearchSidecar（OcxWebSearchSidecarConfig）

Field	Type	Default	含义
enabled?	boolean	所选后端可用时开启	总开关。设为 false 可禁用 Web Search sidecar。
backend?	"openai" | "anthropic"	自动	执行后端。显式配置优先；省略时，有可用的 Anthropic OAuth 活动账户则选 anthropic，否则选 openai。
model?	string	因后端而异	搜索模型：openai 默认 gpt-5.6-luna，anthropic 默认 claude-sonnet-5。显式保留的旧 gpt-5.4-mini 值会在启动时迁移。
reasoning?	string	low	sidecar reasoning effort（网络搜索会拒绝 minimal）。
maxSearchesPerTurn?	number	3	每个主模型 turn 的真实搜索总次数（loop guard）。
routedModelStallTimeoutMs?	number	200000	仅可在配置文件中设置的路由模型迭代原始响应 byte 连续无活动 deadline。必须是 1 到 2147483647 的整数；每个非空响应 body chunk 都会重置该计时器。
timeoutMs?	number	60000	单次托管 web-search 请求的独立 deadline。已从 200000 下调，使不可用/额度耗尽的搜索后端在约 1 分钟内降级为无结果回答，而不会拖住整轮请求（#398）。

openai 后端通过已启用的 ChatGPT forward provider 执行托管搜索，因此同时需要 ChatGPT 登录 和该 provider。Claude 入站的路由重放会把主 ChatGPT 认证注入内部 sidecar 请求，使该路径仍可 访问。anthropic 后端使用已启用 Anthropic OAuth provider 的活动存储凭据，并运行 Claude 的 web_search_20250305 工具。若显式设置 backend: "anthropic"，但没有可用活动账户（包括 needsReauth 状态），sidecar 会关闭失败，而不会回退到 OpenAI。

Web-search 路径有四个时钟：基础 bridge event-stall 预算（stallTimeoutSec）、DNS/TCP/TLS/最终 header 预算（connectTimeoutMs）、路由模型原始 byte 无活动期限 （routedModelStallTimeoutMs），以及单次托管搜索期限（timeoutMs）。实际 bridge watchdog 为 max(基础 stall, connect timeout, 路由模型 stall, sidecar timeout) + 30 秒。路由模型 stall 是 无活动保护，并非总生成 timeout。

visionSidecar（OcxVisionSidecarConfig）

Field	Type	Default	含义
enabled?	boolean	所选后端可用时开启	总开关。设为 false 可禁用图像描述。
backend?	"openai" | "anthropic"	自动	执行后端。使用与 Web Search 相同的显式优先、Anthropic 凭据感知解析规则。
model?	string	因后端而异	图像描述模型：openai 默认 gpt-5.4-mini，anthropic 默认 claude-sonnet-5。
maxDescriptionsPerTurn?	number	8	一个主模型 turn 中允许新增的描述缓存 miss 数。0 禁用描述调用；无效值使用默认值。
timeoutMs?	number	45000	sidecar fetch timeout。

Vision sidecar 仅在图像发送给 provider 的 noVisionModels 列表所匹配模型时启用。OpenAI 后端与 Web Search 一样，需要 ChatGPT 登录和 forward provider；Anthropic 后端使用已存储 OAuth，显式 选择但没有可用凭据时会关闭失败。成功的 data: 图像描述会存入有界进程级缓存，缓存键包含后端、 模型、detail、图像字节和规范化消息上下文。缓存命中和同一 turn 的重复请求不会消耗 maxDescriptionsPerTurn。远程 https: 图像以及失败或空的描述不会缓存。

Anthropic OAuth 搜索和图像描述请求沿用 opencodex 已有的 Claude Code OAuth fingerprint。它处于 仓库既有 OAuth 先例范围内，但仍应使用目标账户和实际负载进行充分 soak test。

完整示例

{
  "port": 10100,
  "defaultProvider": "openai",
  "providers": {
    "openai": {
      "adapter": "openai-responses",
      "baseUrl": "https://chatgpt.com/backend-api/codex",
      "authMode": "forward"
    },
    "anthropic": {
      "adapter": "anthropic",
      "baseUrl": "https://api.anthropic.com",
      "authMode": "oauth",
      "defaultModel": "claude-sonnet-4-6"
    },
    "ollama-cloud": {
      "adapter": "openai-chat",
      "baseUrl": "https://ollama.com/v1",
      "apiKey": "${OLLAMA_API_KEY}",
      "defaultModel": "glm-5.2",
      "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-pro"]
    }
  },
  "subagentModels": ["anthropic/claude-opus-5", "ollama-cloud/glm-5.2"],
  "disabledModels": [],
  "websockets": false,
  "webSearchSidecar": {
    "maxSearchesPerTurn": 3,
    "routedModelStallTimeoutMs": 200000,
    "timeoutMs": 60000
  },
  "visionSidecar": { "enabled": true }
}

密钥

建议为 key 使用 ${ENV_VAR} 引用，避免 config.json 包含 secret。OAuth 和 forward provider 完全不存储 key。

原子写入

所有配置和目录文件（config.toml、opencodex-catalog.json）都会经 atomicWriteFile（临时文件 + 重命名）原子写入。这样即使多个 writer（例如 ocx stop 与代理自身的 shutdown handler）同时 恢复 Codex，也不会留下只写了一半的文件。