OpenCodex安全配置指南回环绑定、Bearer Token与远程访问的正确姿势【免费下载链接】opencodexUniversal provider proxy for OpenAI Codex Claude Code — use any LLM (Claude, Gemini, Grok, DeepSeek, Ollama…) with Codex CLI, App, SDK, and Claude Code项目地址: https://gitcode.com/gh_mirrors/ope/opencodexOpenCodex 是一款面向 OpenAI Codex 与 Claude Code 的通用模型代理Universal provider proxy默认监听127.0.0.1:10100让你用任何 LLM 驱动 Codex 与 Claude Code。默认配置下它是本地免认证的——这很安全因为只有本机能访问。但一旦你把hostname改成0.0.0.0以便在局域网或远程服务器上调用安全边界就变了必须正确配置回环绑定loopback binding与 Bearer Token 鉴权。这篇指南带你 5 分钟搞清楚三件事默认回环绑定如何保护你、远程访问时 Bearer Token 怎么配、数据面与管理面的令牌如何分离。为什么代理比 API Key 更需要防护OpenCodex 是 Claude、Gemini、Grok、DeepSeek、Ollama 等 40 提供商的统一入口。换句话说代理进程掌握着你所有上游模型的密钥和 ChatGPT 账号凭据。如果代理端口暴露在外网且没有鉴权任何扫到该端口的人都能白嫖你的全部额度甚至读取管理 API 中的敏感状态。好消息是OpenCodex 采用了失败即关闭fail-closed的设计默认回环绑定默认hostname为127.0.0.1只有本机流量被放行无需任何令牌非回环绑定强制鉴权把hostname改成0.0.0.0后若没有配置数据面凭据代理会直接拒绝启动。这条硬约束的实现在 assertServerAuthConfig绑定非回环主机名时必须提供 OPENCODEX_API_AUTH_TOKEN 或 config.apiKeys否则启动失败 安全设计核心不是忘了配 Token 也没关系而是没配 Token 就跑不起来。回环绑定Loopback Binding默认安全边界1. 默认只需本机访问ocx start默认监听127.0.0.1或 IPv6 的::1回环判定逻辑见 isLoopbackHostnamelocalhost、127.0.0.1、::1以及带尾部点的localhost.都算回环地址。只要hostname保持回环值isApiAuthRequired 返回false所有请求走loopback 准入不读取任何 Token——本地 Codex CLI、Claude Code、ocx命令和浏览器面板都能零配置直连。2. 远程办公用 SSH 隧道而不是改绑定这是最容易被忽略的正确姿势如果你的笔记本要连家里/服务器上跑着的 OpenCodex保持代理只绑定回环在客户端开 SSH 隧道ssh -L 20100:localhost:10100 useryour-server之后本地localhost:20100就会以回环请求身份进入代理。源码注释里专门解释了这一点回环信任边界只看主机名、不看端口见 isLoopbackRequestHost所以隧道端口20100与真实端口10100不同也完全合法。⚠️ 常见误区为了 SSH 隧道把hostname改成0.0.0.0是过度授权——隧道方案让你既不牺牲便利也不引入额外暴露面。远程访问配置Bearer Token 的三种姿势当客户端和代理不在同一台机器且不走 SSH 隧道时才需要打开非回环绑定。配置文件为~/.opencodex/config.json关键步骤如下姿势一单个共享令牌最简单设置环境变量再修改配置export OPENCODEX_API_AUTH_TOKEN换成足够长的随机字符串{ hostname: 0.0.0.0, port: 10100 }重启代理后每个客户端请求都必须携带令牌支持三种传递头请求头说明x-opencodex-api-key: tokenOpenCodex 专用头推荐语义最明确Authorization: Bearer token标准 Bearer Token 写法x-api-key: token仅部分端点支持见下表Anthropic SDK 客户端常用判定逻辑在 resolveApiAuth专用头优先其次是 Bearer最后是x-api-key。姿势二多 API Key推荐团队协作如果多个同事/设备都要访问建议在config.apiKeys里为每人发一把独立钥匙条目结构见 OcxApiKeyEntry。相比共享单令牌可归因日志能记录每个请求是由哪把 Key 打开的admissionFields 会把 Key 的 id 写进日志行可吊销某人离职或 Key 泄露单独移除一把即可不影响他人。各端点到底接受哪种头不同端点的头接受矩阵并不一致避免踩坑直接看源码中的 AUTH_MATRIX端点Bearerx-opencodex-api-keyx-api-key/v1/responsesCodex CLI 主通道✅✅❌/v1/chat/completions✅✅❌/v1/messages、/v1/models、/v1/catalog✅✅✅也就是说Claude Code 走/v1/messages时三种头都行Codex 走/v1/responses时别用x-api-key。远程客户端只读模型目录时用/v1/catalog的最低权限即可不需要管理令牌。数据面与管理面两把钥匙别混用OpenCodex 把鉴权分成两个平面很多人第一次配置会搞混数据面Data Plane/v1/*模型调用通道用上面讲的OPENCODEX_API_AUTH_TOKEN/apiKeys管理面Management API/api/*管理接口改配置、看日志、管账号池用独立的管理令牌。管理令牌的来源有两种见 initializeManagementAuthState环境变量显式设置OPENCODEX_ADMIN_AUTH_TOKEN自动文件令牌未设置时代理自动生成形如ocx_admin_…32 字节随机数的令牌写入 0600 权限、经过 ACL 加固的密钥文件跨重启保持不变。管理请求通过x-opencodex-api-key或Authorization: Bearer admin-token携带令牌访问。浏览器面板则是另一套短生命周期会话GUI 会话令牌 5 分钟过期、绑定 Origin并在写操作上强制校验 CSRF TokenrequireManagementAuth天然防跨站伪造。两条重要的隔离规则管理令牌 ≠ 数据面令牌管理令牌如果与任一数据面凭据相同会被判为冲突并拒绝加载ready代理自己的令牌永不上游ocx_*前缀及已注册凭据被识别为准入秘密validateForwardAdmissionCredential 会阻止它们被转发给上游模型服务。CORS 与远程面板访问把代理放到远程服务器后浏览器面板的跨域策略由 isAllowedRequestOrigin 控制非回环绑定时只有携带有效数据面凭据、且 Origin 属于回环或你在配置中显式列入corsAllowOrigins的来源才能通过预检。{ hostname: 0.0.0.0, corsAllowOrigins: [https://your-dashboard.example.com] }同时所有响应都附带X-Frame-Options: DENY与frame-ancestors none的 CSPbrowserSecurityHeaders面板无法被第三方页面 iframe 嵌套防点击劫持。上线前安全验收清单配置完成后按这张清单逐项确认健康检查端点/healthz与/readyz本身无需鉴权可用于探活✅ 检查项预期结果本机curl http://127.0.0.1:10100/v1/models正常返回回环免鉴权远程无令牌访问/v1/models401 opencodex API key required携带x-opencodex-api-key远程访问200且日志归因到对应 Key0.0.0.0绑定但未设任何数据面凭据代理拒绝启动用管理令牌访问/api/*200用数据面令牌则401第三方页面 iframe 嵌入面板被X-Frame-Options: DENY拦截安全要点速记️默认回环本地使用保持127.0.0.1不动零配置即安全隧道优先远程办公用ssh -L隧道而不是把代理绑到0.0.0.0强制令牌必须远程暴露时配置OPENCODEX_API_AUTH_TOKEN或apiKeys——否则代理根本不会启动双令牌隔离管理面用OPENCODEX_ADMIN_AUTH_TOKEN或自动生成的ocx_admin_文件令牌与数据面令牌绝不混用一人一钥多人共享时用apiKeys发独立 Key便于归因与吊销定期巡检关注请求日志中的admission字段异常来源及时换钥。更多细节可参考仓库内的 SECURITY.md、structure/04_transports-and-sidecars.md 与 structure/05_gui-and-management-api.md以及构建自 docs-site/ 的完整配置参考文档。【免费下载链接】opencodexUniversal provider proxy for OpenAI Codex Claude Code — use any LLM (Claude, Gemini, Grok, DeepSeek, Ollama…) with Codex CLI, App, SDK, and Claude Code项目地址: https://gitcode.com/gh_mirrors/ope/opencodex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
OpenCodex安全配置指南：回环绑定、Bearer Token与远程访问的正确姿势
OpenCodex安全配置指南回环绑定、Bearer Token与远程访问的正确姿势【免费下载链接】opencodexUniversal provider proxy for OpenAI Codex Claude Code — use any LLM (Claude, Gemini, Grok, DeepSeek, Ollama…) with Codex CLI, App, SDK, and Claude Code项目地址: https://gitcode.com/gh_mirrors/ope/opencodexOpenCodex 是一款面向 OpenAI Codex 与 Claude Code 的通用模型代理Universal provider proxy默认监听127.0.0.1:10100让你用任何 LLM 驱动 Codex 与 Claude Code。默认配置下它是本地免认证的——这很安全因为只有本机能访问。但一旦你把hostname改成0.0.0.0以便在局域网或远程服务器上调用安全边界就变了必须正确配置回环绑定loopback binding与 Bearer Token 鉴权。这篇指南带你 5 分钟搞清楚三件事默认回环绑定如何保护你、远程访问时 Bearer Token 怎么配、数据面与管理面的令牌如何分离。为什么代理比 API Key 更需要防护OpenCodex 是 Claude、Gemini、Grok、DeepSeek、Ollama 等 40 提供商的统一入口。换句话说代理进程掌握着你所有上游模型的密钥和 ChatGPT 账号凭据。如果代理端口暴露在外网且没有鉴权任何扫到该端口的人都能白嫖你的全部额度甚至读取管理 API 中的敏感状态。好消息是OpenCodex 采用了失败即关闭fail-closed的设计默认回环绑定默认hostname为127.0.0.1只有本机流量被放行无需任何令牌非回环绑定强制鉴权把hostname改成0.0.0.0后若没有配置数据面凭据代理会直接拒绝启动。这条硬约束的实现在 assertServerAuthConfig绑定非回环主机名时必须提供 OPENCODEX_API_AUTH_TOKEN 或 config.apiKeys否则启动失败 安全设计核心不是忘了配 Token 也没关系而是没配 Token 就跑不起来。回环绑定Loopback Binding默认安全边界1. 默认只需本机访问ocx start默认监听127.0.0.1或 IPv6 的::1回环判定逻辑见 isLoopbackHostnamelocalhost、127.0.0.1、::1以及带尾部点的localhost.都算回环地址。只要hostname保持回环值isApiAuthRequired 返回false所有请求走loopback 准入不读取任何 Token——本地 Codex CLI、Claude Code、ocx命令和浏览器面板都能零配置直连。2. 远程办公用 SSH 隧道而不是改绑定这是最容易被忽略的正确姿势如果你的笔记本要连家里/服务器上跑着的 OpenCodex保持代理只绑定回环在客户端开 SSH 隧道ssh -L 20100:localhost:10100 useryour-server之后本地localhost:20100就会以回环请求身份进入代理。源码注释里专门解释了这一点回环信任边界只看主机名、不看端口见 isLoopbackRequestHost所以隧道端口20100与真实端口10100不同也完全合法。⚠️ 常见误区为了 SSH 隧道把hostname改成0.0.0.0是过度授权——隧道方案让你既不牺牲便利也不引入额外暴露面。远程访问配置Bearer Token 的三种姿势当客户端和代理不在同一台机器且不走 SSH 隧道时才需要打开非回环绑定。配置文件为~/.opencodex/config.json关键步骤如下姿势一单个共享令牌最简单设置环境变量再修改配置export OPENCODEX_API_AUTH_TOKEN换成足够长的随机字符串{ hostname: 0.0.0.0, port: 10100 }重启代理后每个客户端请求都必须携带令牌支持三种传递头请求头说明x-opencodex-api-key: tokenOpenCodex 专用头推荐语义最明确Authorization: Bearer token标准 Bearer Token 写法x-api-key: token仅部分端点支持见下表Anthropic SDK 客户端常用判定逻辑在 resolveApiAuth专用头优先其次是 Bearer最后是x-api-key。姿势二多 API Key推荐团队协作如果多个同事/设备都要访问建议在config.apiKeys里为每人发一把独立钥匙条目结构见 OcxApiKeyEntry。相比共享单令牌可归因日志能记录每个请求是由哪把 Key 打开的admissionFields 会把 Key 的 id 写进日志行可吊销某人离职或 Key 泄露单独移除一把即可不影响他人。各端点到底接受哪种头不同端点的头接受矩阵并不一致避免踩坑直接看源码中的 AUTH_MATRIX端点Bearerx-opencodex-api-keyx-api-key/v1/responsesCodex CLI 主通道✅✅❌/v1/chat/completions✅✅❌/v1/messages、/v1/models、/v1/catalog✅✅✅也就是说Claude Code 走/v1/messages时三种头都行Codex 走/v1/responses时别用x-api-key。远程客户端只读模型目录时用/v1/catalog的最低权限即可不需要管理令牌。数据面与管理面两把钥匙别混用OpenCodex 把鉴权分成两个平面很多人第一次配置会搞混数据面Data Plane/v1/*模型调用通道用上面讲的OPENCODEX_API_AUTH_TOKEN/apiKeys管理面Management API/api/*管理接口改配置、看日志、管账号池用独立的管理令牌。管理令牌的来源有两种见 initializeManagementAuthState环境变量显式设置OPENCODEX_ADMIN_AUTH_TOKEN自动文件令牌未设置时代理自动生成形如ocx_admin_…32 字节随机数的令牌写入 0600 权限、经过 ACL 加固的密钥文件跨重启保持不变。管理请求通过x-opencodex-api-key或Authorization: Bearer admin-token携带令牌访问。浏览器面板则是另一套短生命周期会话GUI 会话令牌 5 分钟过期、绑定 Origin并在写操作上强制校验 CSRF TokenrequireManagementAuth天然防跨站伪造。两条重要的隔离规则管理令牌 ≠ 数据面令牌管理令牌如果与任一数据面凭据相同会被判为冲突并拒绝加载ready代理自己的令牌永不上游ocx_*前缀及已注册凭据被识别为准入秘密validateForwardAdmissionCredential 会阻止它们被转发给上游模型服务。CORS 与远程面板访问把代理放到远程服务器后浏览器面板的跨域策略由 isAllowedRequestOrigin 控制非回环绑定时只有携带有效数据面凭据、且 Origin 属于回环或你在配置中显式列入corsAllowOrigins的来源才能通过预检。{ hostname: 0.0.0.0, corsAllowOrigins: [https://your-dashboard.example.com] }同时所有响应都附带X-Frame-Options: DENY与frame-ancestors none的 CSPbrowserSecurityHeaders面板无法被第三方页面 iframe 嵌套防点击劫持。上线前安全验收清单配置完成后按这张清单逐项确认健康检查端点/healthz与/readyz本身无需鉴权可用于探活✅ 检查项预期结果本机curl http://127.0.0.1:10100/v1/models正常返回回环免鉴权远程无令牌访问/v1/models401 opencodex API key required携带x-opencodex-api-key远程访问200且日志归因到对应 Key0.0.0.0绑定但未设任何数据面凭据代理拒绝启动用管理令牌访问/api/*200用数据面令牌则401第三方页面 iframe 嵌入面板被X-Frame-Options: DENY拦截安全要点速记️默认回环本地使用保持127.0.0.1不动零配置即安全隧道优先远程办公用ssh -L隧道而不是把代理绑到0.0.0.0强制令牌必须远程暴露时配置OPENCODEX_API_AUTH_TOKEN或apiKeys——否则代理根本不会启动双令牌隔离管理面用OPENCODEX_ADMIN_AUTH_TOKEN或自动生成的ocx_admin_文件令牌与数据面令牌绝不混用一人一钥多人共享时用apiKeys发独立 Key便于归因与吊销定期巡检关注请求日志中的admission字段异常来源及时换钥。更多细节可参考仓库内的 SECURITY.md、structure/04_transports-and-sidecars.md 与 structure/05_gui-and-management-api.md以及构建自 docs-site/ 的完整配置参考文档。【免费下载链接】opencodexUniversal provider proxy for OpenAI Codex Claude Code — use any LLM (Claude, Gemini, Grok, DeepSeek, Ollama…) with Codex CLI, App, SDK, and Claude Code项目地址: https://gitcode.com/gh_mirrors/ope/opencodex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考