ARTICLE DETAIL

资讯详情

深耕编程入门与网站建设的一线实战洞察。

通过SSH端口转发,把CC Switch的Codex接入远程服务器

通过SSH端口转发,把CC Switch的Codex接入远程服务器 1. 本地 CC Switch 管 Codex 时远程服务器请求为什么总打不通先说清楚这篇要解决的具体问题。CC Switch 是一个本地模型路由工具它能在你本机起一个转发服务把 Codex、Claude Code 这类命令行工具的请求统一收口再按你配置的渠道分发出去。很多人本地用得好好的一旦把 Codex 装到远程开发机上请求就发不出去了——因为远程服务器上的 Codex 默认会去连127.0.0.1的某个端口而那个端口在服务器上根本没人监听真正在跑路由的是你本地电脑上的 CC Switch。这就是典型的「本地有服务、远程要调用」场景。你有一台远程开发机云主机、公司内网跳板机、实验室服务器都算日常在服务器上跑代码、跑 Agent但模型入口想统一走本地 CC Switch 管理好处是 Key 只存在本地、渠道切换只改一处、用量和日志都集中。问题在于远程服务器和你的本地电脑之间没有直接可达的端口通道Codex 发出的请求到不了 CC Switch。SSH 端口转发就是补这条通道的工具。它不需要你改动服务器防火墙也不需要把 CC Switch 暴露到公网而是借助你已经建立的 SSH 连接把远程服务器上的某个本地端口「反向」映射回你本机的服务端口。这样服务器上访问127.0.0.1:15721实际流量会顺着 SSH 隧道回到你电脑的127.0.0.1:15721也就是 CC Switch 的路由地址。适合谁看手上有远程开发机、已经在本地用 CC Switch 管 Codex、希望远程也能复用同一套模型入口的开发者。整篇按「先打通隧道 → 再配 CC Switch → 再填 Codex → 最后验证」的顺序走每一步都给可复制的命令和配置。核心检索词就是 SSH 端口转发、CC Switch、Codex、远程服务器下面所有操作都围绕这几个点展开。需要提前说明一点SSH 端口转发走的是你自己已有的 SSH 登录链路属于标准的远程开发手段和任何网络规避工具无关。你只是把本机服务通过加密连接共享给远程机器流量始终在你自己的两台设备之间。2. 前置准备CC Switch 路由地址、TaoToken Key 与远程环境确认动手之前先把三样东西确认好不然后面配到一半发现缺东西会很烦。第一样是 CC Switch 的本地路由地址。打开 CC Switch进入设置里的路由本地路由页面默认服务地址是127.0.0.1:15721。这个端口号要记牢后面 SSH 隧道命令和 Codex 配置都要用它。如果你的 CC Switch 改过端口以实际显示为准。确认这个服务处于运行状态本地浏览器或 curl 能访问到它。第二样是模型渠道的 Key 和 Base URL。CC Switch 本身是路由层真正提供模型能力的是你导入的渠道。如果你还没有可用的渠道可以到 TaoToken 控制台创建一个 API Key地址是 https://taotoken.net/api-keys 创建后复制保存。对应的接入文档在 https://taotoken.net/doc 里面有 Base URL 和模型 ID 的说明。TaoToken 的 API 入口是 https://taotoken.net/api 配置时 Base URL 填这个即可。想先验证模型是否通可以用模型对话页面 https://taotoken.net/models 发一条测试消息确认 Key 有效再往下走。第三样是远程服务器的环境。你需要能 SSH 登录上去并且服务器上已经装了 Codex 相关插件或 CLI。如果还没装先在服务器上把 Codex 装好装完先别急着配因为默认配置连不上我们要先把隧道打通。这里有个概念要理清CC Switch 跑在你本地Codex 跑在远程。两者之间靠 SSH 反向转发连接。所谓「反向」是指转发方向由远程指向本地——在 SSH 连接建立时由远程服务器主动把它的某个端口映射到本地端口。这正好符合我们的需求远程的 Codex 访问自己的127.0.0.1:15721流量被 SSH 带回本地 CC Switch。把这三样准备好就可以进入配置环节了。下面先给 SSH 隧道命令再给 CC Switch 和 Codex 的填写位置。3. 可复制配置SSH RemoteForward 隧道 CC Switch 与 Codex 填写这一步是全文的核心配置对了后面就顺。分三小块SSH 隧道、CC Switch 侧、Codex 侧。3.1 SSH 隧道RemoteForward 反向转发最直接的方式是在 SSH 命令里加-R参数。假设你的远程服务器在 SSH config 里叫devbox本地 CC Switch 监听127.0.0.1:15721那么登录命令写成ssh -R 127.0.0.1:15721:127.0.0.1:15721 devbox-R的格式是远程监听地址:远程端口:本地目标地址:本地目标端口。这条命令的意思是在远程服务器上监听127.0.0.1:15721把收到的流量转发到本地的127.0.0.1:15721。登录成功后隧道就建立了。但每次手动敲参数容易忘更好的做法是写进 SSH config 文件。打开你本地的~/.ssh/config找到对应 Host 段落加上 RemoteForward 配置Host devbox HostName 192.0.2.10 User simon RemoteForward 127.0.0.1:15721 127.0.0.1:15721 ExitOnForwardFailure yes这里HostName和User换成你自己的服务器地址和用户名。ExitOnForwardFailure yes很关键如果端口转发失败比如远程端口被占用SSH 会直接退出而不是静默继续这样你能立刻发现问题而不是登录成功却发现隧道没通。配好之后直接ssh devbox就会自动带上转发。注意如果远程服务器上15721端口已经被别的进程占用SSH 会报remote port forwarding failed。这时要么换一个远程端口比如-R 127.0.0.1:25721:127.0.0.1:15721要么先查清占用进程。换端口的话Codex 侧填的端口也要跟着改。3.2 CC Switch 侧确认路由与渠道CC Switch 这边主要是确认路由服务在跑、渠道已导入。进入设置 → 路由 → 本地路由确认服务地址是127.0.0.1:15721状态为运行中。然后在渠道管理里把你从 TaoToken 拿到的 Key 导入进去Base URL 填https://taotoken.net/api模型 ID 按文档填你需要的那个。如果你用的是配置文件方式管理渠道CC Switch 的渠道配置大致是 JSON 结构形如{ name: taotoken, base_url: https://taotoken.net/api, api_key: sk-你的Key, models: [你的模型ID] }具体字段名以你本地 CC Switch 版本为准路径一般在应用配置目录下。导入后CC Switch 会把所有渠道统一暴露在127.0.0.1:15721这个路由地址上Codex 只需要连这个地址不用关心背后是哪个渠道。3.3 Codex 侧Base URL、Key、Model ID 三件套远程服务器上的 Codex 需要指向本地路由。Codex 的配置通常在~/.codex/config.toml或类似路径核心是三个值Base URL、API Key、Model ID。Base URL 填http://127.0.0.1:15721注意是远程服务器视角的本地地址因为隧道已经在服务器上监听了这个端口Key 填 CC Switch 路由要求的 Key如果 CC Switch 路由不校验 Key可填任意占位符但建议按 CC Switch 文档填Model ID 填你在 CC Switch 里配置的模型。一个 TOML 配置示例model 你的模型ID model_provider ccswitch [model_providers.ccswitch] name CC Switch Local Route base_url http://127.0.0.1:15721 api_key sk-你的Key如果你用的是 Codex 的auth.json方式管理凭据那对应写{ base_url: http://127.0.0.1:15721, api_key: sk-你的Key, model: 你的模型ID }三件套缺一不可Base URL 决定请求发到哪Key 决定能不能过鉴权Model ID 决定用哪个模型。任何一项填错验证阶段都会报错。填完保存准备验证。4. 验证请求从远程服务器发一次对话确认链路通配置写完不代表通了必须实测。验证分两步先确认隧道端口在远程服务器上确实被监听再从远程发一次真实请求。第一步在远程服务器上执行ss -tlnp | grep 15721如果看到类似LISTEN 0 128 127.0.0.1:15721的输出说明 SSH 反向转发已经生效服务器上有人在监听这个端口。如果没有输出说明隧道没建起来回到第 3.1 节检查 RemoteForward 配置和 SSH 登录日志。第二步在远程服务器上直接 curl 本地路由确认能拿到响应curl -s http://127.0.0.1:15721/v1/models \ -H Authorization: Bearer sk-你的Key如果返回模型列表 JSON说明从远程到本地 CC Switch 的链路是通的。如果返回连接拒绝说明隧道断了或 CC Switch 没运行如果返回 401说明 Key 不对检查 CC Switch 路由的鉴权配置。第三步用 Codex 本身发一次对话。在远程服务器上启动 Codex输入一句简单的话比如「用一句话解释什么是端口转发」。观察返回如果正常输出内容说明整条链路——远程 Codex → 远程 15721 → SSH 隧道 → 本地 CC Switch → TaoToken → 模型——全部打通。如果卡住或报错看 Codex 的输出日志通常会指出是连接问题还是鉴权问题。实测下来最容易出问题的是端口号和 Key 这两处。端口号在 SSH 命令、CC Switch、Codex 三处必须一致Key 在 CC Switch 渠道和 Codex 配置两处必须匹配。验证通过后你以后每次ssh devbox登录隧道会自动建立Codex 直接可用不用重复配置。5. 本篇常见错排查401、remote port forwarding failed 与 reading choices配置过程中会碰到几类典型报错这里逐个对照排查。401 Unauthorized请求到了 CC Switch 但鉴权没过。原因通常是 Codex 里填的 Key 和 CC Switch 路由要求的 Key 不一致。检查两处CC Switch 路由设置里的鉴权 Key以及 Codex 配置里的api_key。如果 CC Switch 路由不校验 Key也要确认渠道本身的 Key 是有效的——渠道 Key 无效时CC Switch 转发到上游会拿到 401最终透传给 Codex。这时去 TaoToken 控制台确认 Key 状态必要时重新创建一个。remote port forwarding failed for listen port 15721SSH 登录时报这个说明远程服务器上 15721 已被占用或者之前一条 SSH 连接的转发没释放。先ssh devbox登录后执行ss -tlnp | grep 15721看谁占着如果是残留的 sshd 转发进程断开旧连接再重连。实在冲突就换远程端口比如-R 127.0.0.1:25721:127.0.0.1:15721同时 Codex 的 Base URL 改成http://127.0.0.1:25721。local proxy failed / connection refusedCodex 报连接本地代理失败。这通常是隧道没建立或者 CC Switch 没运行。先在远程ss -tlnp | grep 15721确认监听存在再在本地确认 CC Switch 路由服务在跑。两者缺一请求都到不了。reading choices 相关报错这类错误一般出现在响应解析阶段说明请求已经到达上游并返回了数据但格式不符合 Codex 预期。常见原因是 Model ID 填错或者 CC Switch 渠道配置的模型和 Codex 请求的模型不匹配。检查 Codex 配置里的model字段确保它在 CC Switch 渠道支持的模型列表里。如果 CC Switch 做了模型映射确认映射关系正确。OAuth 相关报错如果你用的是需要 OAuth 的渠道而 Codex 走的是 API Key 模式会报 OAuth 失败。这种情况要么在 CC Switch 侧把渠道切成 API Key 模式要么在 Codex 侧按 OAuth 流程配置。多数本地路由场景用 API Key 就够了不建议混用。排查顺序建议固定先看隧道ss命令→ 再看 CC Switch本地 curl→ 再看 Key401 类→ 最后看模型 ID解析类。按这个顺序走基本能定位到具体环节。6. 长期编码与 Agent 场景把这条链路固定下来隧道打通、验证通过之后接下来是让它稳定服务于日常开发。几个实用建议。第一把 SSH config 里的 RemoteForward 和 ExitOnForwardFailure 保留这样每次登录自动建隧道不用记命令。如果你经常开多个终端连同一台服务器注意 SSH 复用ControlMaster场景下转发只建一次重复登录不会重复监听这是正常的。第二CC Switch 的渠道配置建议固定一个主渠道加一个备用渠道主渠道出问题时快速切换Codex 侧不用改任何配置因为 Base URL 始终指向本地路由。这就是统一入口的价值远程机器上的工具配置一次之后渠道变更都在本地完成。第三如果你在远程跑的是长期编码任务或 Agent建议把 Codex 配置和 SSH 隧道做成启动脚本登录后自动检查端口监听状态异常时给出提示。这样即使隧道偶发断开也能快速发现。第四Key 管理上本地 CC Switch 集中持有渠道 Key远程 Codex 只持有路由 Key这样远程服务器上不落敏感凭据安全性更好。需要新增渠道时只改本地 CC Switch远程无感。对于需要长期跑 Agent、频繁调用模型的场景可以了解下 Coding Plan 这类方案地址是 https://taotoken.net/coding-plan 适合把编码类请求集中管理。日常验证模型连通性用模型对话页面 https://taotoken.net/models 接入文档在 https://taotoken.net/doc 控制台和 API Key 管理在 https://taotoken.net/console 和 https://taotoken.net/api-keys 。把这些入口理顺本地 CC Switch 加 SSH 端口转发的组合就能稳定支撑远程开发机的模型调用需求。
返回列表