模型网关

用固定地址把 Coskey 模型提供给 Codex 和其它 Agent，并管理 client token、允许模型、局域网访问与独立网关进程。

「模型网关」把 Coskey 已配置的模型开放成一个固定的 OpenAI 兼容入口，供本机或局域网中的 Codex、DeepSeek Harness、IDE 与脚本使用。它和 ChatGPT.app 内部使用的中转各走一条链路：

项目 ChatGPT.app 内部中转 模型网关
谁在用 Coskey 包装器代理的 ChatGPT.app 请求 其它 Agent 或远端 Codex
地址 随机回环端口 固定端口，缺省 15721
鉴权 包装器内部凭据 每个 client 独立的 ckg_… token
生命周期 跟随包装器 独立网关进程，可随 Coskey 启动

两者共用同一份供应商、密钥与模型映射，但监听 socket、token 和运行状态互不影响。模型网关 不依赖 ChatGPT.app 正在运行；使用官方模型时，网关仍需要宿主机上有效的 ChatGPT 登录态。

一个完整的 GUI 接入示例见 DeepSeek Harness 接入 ChatGPT 订阅模型。

普通安装的本机 Base URL 是 http://127.0.0.1:15721/v1。本文截图来自隔离实例，图中的 15906 是实例分配的端口，不要照抄；以你自己网关页显示的地址为准。

1. 首次启用

先在供应商与上游模型和模型映射与上下文窗口 里准备好要开放的模型，然后：

  1. 打开 Coskey → 模型网关，选择「仅本机」或「局域网」；
  2. 确认监听端口，缺省为 15721；
  3. 当前配置中启用且有效的应用模型，以及当前可用的官方模型，会自动进入候选集；网关页 不另做全局模型筛选；
  4. 点击 启用网关。如果还没有 client，Coskey 会创建 default-local，并显示一次 ckg_… token；
  5. 先点 测试连接，确认健康端点、鉴权后的模型列表和一次最小非流式请求都通过。

模型网关初始态

启用后，页面顶部会显示一次 token 与测试入口。截图中的 token 已遮蔽：

启用后的一次性 token 与连接测试

测试会真的发出请求，并消耗所选模型的额度：第三方模型消耗对应供应商的额度，官方模型 消耗宿主机 ChatGPT 账号的订阅额度。下拉框里第三方与官方模型同权，只要当前 client 允许该模型，就可以单独测试。

2. 客户端与 token

每个外部 Agent 应使用独立 client，各自持有独立 token，便于限制模型、轮换凭据和分别撤销。 点 创建客户端，填写 ID、范围与允许模型；范围默认跟随当前网关范围，允许模型是复选 列表：

创建客户端并选择允许模型

client 建好后仍可编辑。增加一个应用模型不需要重建 client 或更换 token；在行内「编辑」 里补选即可。列表中的「允许模型」有两个入口：

  • 点模型数量查看「暴露的模型」，逐个测试；
  • 点「Codex 配置」选择一个允许的模型，生成可复制的 Codex 配置。

token 的保存与状态规则如下：

  • 明文只保存在系统钥匙串；coskey.toml 只保存 SHA-256；
  • GUI 只在启用、创建或轮换时显示一次完整 token，之后通过复制图标由后端写入剪贴板；
  • 旧的 hash-only client 需要先轮换一次，之后才能复制；
  • 轮换 token 会让旧 token 立即失效，并显示新 token 一次；
  • 禁用保留 client 元数据，但停止接受它的请求；
  • 撤销 / 删除 会让下一次请求立即得到 401。

轮换前会要求确认，因为正在使用旧 token 的 Agent 会立刻断开：

轮换 token 前的确认

3. 生成 Codex 配置

在 client 行点「Codex 配置」，选择一个该 client 允许的模型，即可复制配置：

为 client 生成 Codex 配置

生成结果中的 base_url 指向固定网关，模型 id 与 /v1/models、/v1/codex/models 返回的 id 完全一致。model_catalog_url 让 Codex 从网关动态拉取模型目录，因此新增映射 通常不需要修改远端配置。一个典型的本机配置是：

model_provider = "coskey-gateway"
model = "localdev-large"

[model_providers.coskey-gateway]
name = "Coskey Gateway"
base_url = "http://127.0.0.1:15721/v1"
wire_api = "responses"
model_catalog_url = "http://127.0.0.1:15721/v1/codex/models"
env_key = "COSKEY_GATEWAY_TOKEN"

把 client token 放进环境变量，不要写进命令行参数或提交到仓库：

read -rs COSKEY_GATEWAY_TOKEN
export COSKEY_GATEWAY_TOKEN
codex

远端 Codex 使用同一份配置结构，把地址换成该 client 能访问的网关地址。当前桌面界面只 提供「仅本机 / 局域网」入口；如通过 HTTPS 反向代理提供公网入口，需要同时配置 public 范围的 HTTPS 地址和精确来源 CIDR，这属于后端与 CLI 能力，暂不在 GUI 中开放。

目录变化与 client 撤销会在网关实例内热加载。Codex 自身仍会缓存模型目录约 5 分钟；改完 允许模型后，重开 /model 或重启远端 app-server 才能看到新条目。

不想手工写远端配置时，可以在 Coskey Tools 里明确 指定 SSH 主机，让它先返回接入计划；只有你确认主机、模型与影响后，才执行远端写入和隧道配置。

4. 访问范围与官方模型

范围 用途 关键约束
local / 仅本机 同机 Agent 只监听回环地址
lan / 局域网 局域网、Tailscale、WireGuard 等私有网络 监听 0.0.0.0；token 必填；明文 HTTP 默认允许，可手动关闭
public / 公网 自有服务器经 HTTPS 反代访问 Base URL 必须是 https://，client 必须绑定精确来源 CIDR；当前 GUI 不提供入口

切到「局域网」时，监听地址会自动变为 0.0.0.0，页面会枚举本机 IPv4 网卡，并优先选择 真实私有网段而不是代理 TUN。回环、链路本地、组播和保留网段不会作为候选；多网卡时可以 手动选择，Base URL 与 Codex 配置会跟随所选地址。切回「仅本机」时恢复 127.0.0.1。

局域网模式默认允许明文 HTTP，因此 token 与请求内容不会加密，只应在可信网络中启用； 需要加密时可在前面加 Nginx 等 HTTPS 反向代理。client 的范围也必须匹配请求来源： 「仅本机」client 从局域网地址请求会得到 403。

client 选中的官方模型与第三方模型同权，会共享宿主机 ChatGPT 账号与订阅额度。网关只把 宿主机 CODEX_HOME/auth.json 中的登录态用于上游请求，只读、不刷新，也不会把宿主 OAuth token 返回给 client。API-key 登录不等于 ChatGPT 订阅登录；缺少订阅登录态时，官方模型 请求会失败，第三方模型不受影响。

5. 哪些模型会被暴露

候选集由当前本机配置决定：

  • 当前启用且有效的应用模型；
  • 当前目录中可用的官方模型；
  • 已停用、悬空或无法解析的映射不进入候选集；
  • 每个 client 的 allowed_models 再从候选集中选择子集。

应用模型 id 采用精确匹配。若同一 id 同时被应用模型和官方目录选中，网关不会擅自选择其中 一边，两边都不会暴露；请先改掉其中一个 id。修改 client 的允许模型后，无需更换 token。

6. 运行与生命周期

Coskey 每次启动都会检查网关配置：如果网关已启用但进程未运行，它会在后台启动，已有进程 则不会重复启动。关闭主窗口只会把 Coskey 隐藏到系统托盘，网关继续运行；从托盘右键选择 「退出 Coskey」才会停止网关。图形界面管理的网关不会安装登录级 KeepAlive 服务。

如果希望在没有 Coskey 图形界面时也常驻，可以使用命令行：

coskey gateway enable
coskey gateway status

enable 会安装登录级自启动；disable 只移除自启并停止当前进程，保留配置、client 与 token 哈希，之后随时可以重新启用。

网关页的 安全修复 只处理可以确定的问题：非法监听地址回到回环默认值；公网模式缺少 HTTPS 时降级为本机；删除非法 CIDR；禁用哈希损坏或未绑定精确来源的公网 client；没有 client 时创建 default-local 并显示一次 token。

7. 在本机使用 coskey codex

只在本机使用官方 Codex CLI 时，不需要先启用固定网关：

coskey codex
coskey codex -m localdev-large
coskey codex exec "检查这个项目"
coskey codex resume

启动器会创建随机回环端口和每进程 token，通过环境变量交给 Codex，自身不写 ~/.codex/config.toml。Codex 的 /model 使用动态 model_catalog_url，中转在运行期间 热加载 Coskey 映射；CLI 退出、信号中断或异常退出时中转随之停止。

在 /model 选完模型并进入推理等级页后：

  • 按 Enter 会把模型和推理等级写入 Codex 的 config.toml，影响之后普通 codex；
  • 按 s 只修改当前会话，不写入这两个值；
  • 两条路径都不改变 Coskey 的全局默认模型。

8. 命令行、测试与排障

GUI 上的主要操作都有等价命令：

coskey gateway enable
coskey gateway disable
coskey gateway status [--json]
coskey gateway client add <ID> [--scope local|lan|public] [--model <MODEL_ID>]...
coskey gateway client list
coskey gateway client rotate <ID>
coskey gateway client remove <ID>
coskey gateway test --model <MODEL_ID>

gateway test 只从环境变量 COSKEY_GATEWAY_TOKEN 读取 token，不接受命令行参数，避免写进 shell 历史。它会依次检查 /healthz、鉴权后的模型列表和一次最小非流式请求：

read -rs COSKEY_GATEWAY_TOKEN
export COSKEY_GATEWAY_TOKEN
coskey gateway test --model localdev-large

日常排查还可以先直接检查健康端点，再运行统一体检：

curl -s http://127.0.0.1:15721/healthz
coskey doctor
coskey gateway status
现象 检查项
401 / token 无效 token 是否来自当前 client；轮换后是否已把新 token 填进调用方
403 client 范围是否覆盖请求来源；局域网请求不能使用「仅本机」client
模型列表为空 client「允许模型」是否包含目标 id；保存后调用方是否重新拉取了模型目录
host_login_required 启动网关的进程是否使用预期的 CODEX_HOME；其中是否有 ChatGPT 登录态
第三方模型能测，官方模型不能 宿主机 ChatGPT 订阅登录态是否有效；API-key 登录不能替代它
Codex 看不到新模型 Codex 目录缓存尚未刷新；重开 /model 或重启 app-server
网关异常退出 状态页的网关运行、端口、来源范围、宿主登录与密钥检查项；必要时 disable 后重新 enable

网关日志在 ~/.coskey/logs/gateway.log，不会写 token、上游密钥、prompt 或 completion。 官方 Responses 后端只接受流式请求；非流式的连接测试由网关在内部聚合 SSE 后返回 JSON。

相关：供应商与上游模型、 模型映射与上下文窗口、 Codex 模型选择、 Coskey Tools、 状态与设置。

上一篇Coskey Tools下一篇DeepSeek Harness 接入 ChatGPT 订阅模型