1. Codex 桌面版 SSH 远程连接到底解决了什么问题Codex 桌面版ChatGPT 桌面客户端里的 Codex 面板和 Codex CLI 是两套不同的使用入口。很多人一开始跟我一样本地 Mac 上开着桌面版服务器上跑着 CLI两边各用各的。结果就是服务器端每次改文件、跑命令都要手动按回车审批人一旦离开终端任务就卡死在那里。我试过用codex --sandbox workspace-write --ask-for-approval never来减少审批本地跑没问题但一旦进到容器里的服务器环境就不灵了——容器本身权限模型和宿主机不一样never审批模式在受限沙箱里会被拦下来。后来同事提醒我Codex 桌面版支持 SSH 连接远程服务器把远程目录挂到桌面端来操作审批策略就可以在桌面端统一设置成「替我审批」服务器端不用再一直盯着回车。这个场景的核心价值有三个第一审批集中到桌面端。远程服务器上的文件改动、命令执行审批弹窗出现在你本地的 Codex 桌面版里而不是散落在各个 SSH 终端。你可以设置自动审批策略让低风险操作直接过。第二认证统一到 TaoToken。Codex 桌面版和 CLI 都读auth.json这个认证文件。如果本地和远程各配一套 Key很容易出现「本地能跑、远程 401」的情况。把auth.json指向 TaoToken 的统一 API 通道本地和远程共用同一个 Key 和 Base URL鉴权失败的问题基本就消掉了。第三适合谁。如果你符合下面任意一条这篇配置就是给你写的在远程服务器或容器里跑 Codex CLI 但不想一直按回车本地用桌面版、远程用 CLI 但两边认证老对不上想把 Codex 的模型调用统一走一个 API 通道方便管理和计费。需要先明确一点Codex 桌面版的 SSH 连接是「远程文件访问 远程命令执行」的通道它不改变 Codex 本身的模型调用逻辑。模型请求仍然从你配置的 API 端点发出。所以auth.json指向哪里请求就从哪里走。这也是为什么把auth.json改到 TaoToken 之后本地和远程的行为能保持一致。TaoToken 在这里的角色是统一 API 通道官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。你拿到一个 Key配置到auth.jsonCodex 桌面版和 CLI 都读这个文件远程 SSH 会话里的 Codex 也读同一份或同步过去的一份认证就统一了。下面从拿到 Key 开始一步步把auth.json配好再走 SSH 远程验证最后把常见报错列清楚。2. 前置准备TaoToken Key 与 auth.json 路径确认在动 SSH 之前先把本地这套跑通。因为远程连接本质上是把本地的认证配置带到远程环境去用本地不通远程一定不通。2.1 拿 TaoToken API Key打开 https://taotoken.net/api-keys 登录后创建一个 API Key。创建时注意两点一是 Key 只在创建时完整显示一次复制下来存好二是如果平台支持设置额度或模型范围按你实际要用的模型勾选。Codex 常用的模型 ID 在控制台或文档里能查到记下来后面配置要用。拿到 Key 之后先别急着写进auth.json用一条 curl 验证一下这个 Key 和端点是否通curl -s https://taotoken.net/api/v1/models \ -H Authorization: Bearer sk-你的TaoTokenKey \ | head -c 500如果返回一串模型列表 JSON说明 Key 和端点都没问题。如果返回 401先检查 Key 有没有复制完整、有没有多余空格。这一步过了再往下走。2.2 找到 Codex 的 auth.json 位置Codex 桌面版和 CLI 读的认证文件默认在用户目录下的.codex文件夹里。不同系统路径不一样系统auth.json 默认路径macOS / Linux~/.codex/auth.jsonWindows%USERPROFILE%\.codex\auth.json你可以先用命令确认文件是否存在ls -la ~/.codex/如果目录不存在手动建一个mkdir -p ~/.codex如果之前登录过官方账号auth.json里可能已经有内容。建议先备份cp ~/.codex/auth.json ~/.codex/auth.json.bak备份这一步别省。改坏了还能退回去。2.3 确认 Codex 版本与配置读取顺序Codex 读取配置的顺序大致是环境变量 auth.json 默认登录态。也就是说如果你在 shell 里设了OPENAI_API_KEY之类的环境变量它会覆盖auth.json里的配置。远程 SSH 会话里尤其容易踩这个坑——服务器上的.bashrc或.zshrc里可能残留了旧的环境变量。先检查一下env | grep -i -E openai|codex|api_key如果有输出记下来后面配置时要么清掉要么确保它和auth.json一致。这一步做完前置准备就齐了一个可用的 TaoToken Key、一个确认过路径的auth.json、一个干净的环境变量环境。3. 可复制配置auth.json 指向 TaoToken 的完整片段这一节是全文的核心。auth.json的字段结构在不同 Codex 版本里略有差异但关键字段就那几个API Key、Base URL、模型 ID。下面给一份可直接复制的配置路径和字段名按 Codex 实际读取的来。3.1 auth.json 完整片段把下面内容写入~/.codex/auth.json{ OPENAI_API_KEY: sk-你的TaoTokenKey, OPENAI_BASE_URL: https://taotoken.net/api, OPENAI_API_BASE: https://taotoken.net/api, model: gpt-5-codex, preferred_auth_method: apikey }几个字段说明OPENAI_API_KEY填你在 TaoToken 创建的 Key。注意前缀sk-要保留不要只填后面那串。OPENAI_BASE_URL和OPENAI_API_BASE都指向https://taotoken.net/api。有些 Codex 版本读前者有些读后者两个都写上最稳。注意这里不要加/v1Codex 内部会自己拼路径。如果你写成了https://taotoken.net/api/v1可能会出现路径重复导致 404。model填你要用的模型 ID。Codex 场景常用的是代码类模型具体 ID 以 TaoToken 控制台或文档里列出的为准。填错模型 ID 会报model not found。preferred_auth_method设为apikey避免 Codex 尝试走 OAuth 登录流程。远程 SSH 环境里没有浏览器OAuth 会直接卡住。3.2 用 TOML 补充配置可选但推荐除了auth.jsonCodex 还读~/.codex/config.toml。把模型和审批策略写在这里桌面版和 CLI 都能生效model gpt-5-codex approval_policy on-request sandbox_mode workspace-write [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key OPENAI_API_KEYapproval_policy设成on-request表示由 Codex 自己判断哪些操作需要审批低风险的直接过。这就是桌面版「替我审批」模式对应的配置项。sandbox_mode设成workspace-write允许在工作目录内写文件但不越界到系统目录。[model_providers.taotoken]这段定义了一个自定义 providerenv_key指向OPENAI_API_KEY也就是从auth.json或环境变量里读 Key。这样配置的好处是以后要换端点只改这一处。3.3 权限收紧auth.json里有明文 Key权限要收紧chmod 600 ~/.codex/auth.json chmod 700 ~/.codex远程服务器上尤其要注意多用户环境下权限没设好别人能读到你的 Key。3.4 把配置同步到远程服务器SSH 远程连接时Codex 桌面版会通过 SSH 通道在远程执行命令。远程环境里的 Codex CLI 也需要读到同样的auth.json。有两种做法做法一在远程服务器上也建一份~/.codex/auth.json内容同上。适合远程是长期使用的开发机。做法二用 SSH 的RemoteForward或直接 scp 同步scp ~/.codex/auth.json userremote-host:~/.codex/auth.json ssh userremote-host chmod 600 ~/.codex/auth.json同步完在远程验证一下文件内容对不对ssh userremote-host cat ~/.codex/auth.json | head -c 200确认 Key 和 Base URL 都正确。这一步做完本地和远程的认证就统一到 TaoToken 了。4. SSH 远程验证从连接建立到请求成功配置写好了接下来验证整条链路。分三步先确认 SSH 本身通再确认远程 Codex 能读到配置最后发一个真实请求看返回。4.1 确认 SSH 连接与远程环境先用最基础的 SSH 命令确认能连上ssh -o ConnectTimeout10 userremote-host echo connected uname -a返回connected和系统信息说明 SSH 通道没问题。如果这里就卡住或报Connection refused先解决 SSH 本身的问题跟 Codex 无关。连上之后确认远程有没有装 Codex CLIssh userremote-host which codex codex --version如果没有输出说明远程没装 Codex CLI。Codex 桌面版的 SSH 远程连接依赖远程有可执行的 Codex 环境先装上再继续。4.2 在远程验证 auth.json 被正确读取在远程跑一条命令让 Codex 打印它读到的配置ssh userremote-host codex config get model codex config get base_url如果返回的 model 和 base_url 跟你写的一致说明配置被正确读取。如果返回空或默认值检查~/.codex/auth.json路径对不对、JSON 格式有没有语法错误。JSON 语法错误是高频问题。用这个命令校验ssh userremote-host python3 -m json.tool ~/.codex/auth.json /dev/null echo json-ok返回json-ok说明格式没问题。报错的话根据提示的行号去改。4.3 发一个真实请求最直接的验证是让 Codex 在远程跑一个简单任务ssh userremote-host cd /tmp codex exec print hello from remote codex如果配置正确你会看到 Codex 调用模型并返回结果。返回内容里应该包含hello from remote codex相关的输出。再验证一下文件操作和审批策略ssh userremote-host cd /tmp codex exec create a file named test.txt with content ok ssh userremote-host cat /tmp/test.txt第二条命令返回ok说明 Codex 在远程成功执行了文件写入且审批策略允许了这个操作。如果这里卡在审批上回到config.toml检查approval_policy和sandbox_mode的设置。4.4 桌面版 SSH 连接的实际操作在 Codex 桌面版里SSH 连接的入口通常在设置或连接管理里。填入远程主机地址、用户名、认证方式密钥或密码连接成功后桌面版会列出远程目录树。你在桌面版里打开远程文件、发起修改审批弹窗出现在本地桌面端。连接建立后桌面版会通过 SSH 在远程执行 Codex 命令。此时远程读的是远程那份auth.json。所以第 3.4 步的同步不能省。如果桌面版连上了但请求报 401八成是远程那份auth.json没同步或内容不对。验证成功的标志桌面版里打开一个远程文件让 Codex 改一行审批弹窗出现你点通过远程文件实际被修改。整个过程本地和远程的模型请求都走 TaoToken没有出现鉴权错误。5. 常见报错排查清单这一节按真实报错来。每条给出报错原文、原因、修复命令。5.1 401 Unauthorized报错原文Error: 401 Unauthorized - invalid api key原因通常是三种Key 复制不完整、Key 前后有空格、auth.json里的 Key 和实际创建的不一致。排查# 检查 Key 是否有前后空格 cat ~/.codex/auth.json | python3 -c import json,sys; djson.load(sys.stdin); print(repr(d[OPENAI_API_KEY]))repr会把空格显示出来。如果有 sk-xxx 这种去掉空格。然后重新用 curl 验证 Keycurl -s https://taotoken.net/api/v1/models -H Authorization: Bearer sk-你的Key | head -c 200curl 通但 Codex 不通检查是不是环境变量覆盖了auth.jsonenv | grep -i openai有输出就unset OPENAI_API_KEY再试。5.2 local proxy failed / connection refused报错原文Error: local proxy failed: dial tcp 127.0.0.1:xxxx: connect: connection refused这个报错说明 Codex 尝试连一个本地代理端口但那个端口没有服务在听。常见于之前配过代理、后来代理关了但配置没清。排查env | grep -i -E proxy|http_proxy|https_proxy如果有http_proxy或https_proxy指向本地端口清掉unset http_proxy https_proxy all_proxy然后检查auth.json里有没有残留的代理配置字段。Base URL 应该是https://taotoken.net/api不要写成某个本地地址。5.3 reading choices / unexpected end of JSON报错原文Error: reading choices: unexpected end of JSON input这个报错通常不是认证问题而是响应体为空或不是合法 JSON。原因可能是 Base URL 写错导致请求打到了错误路径返回了 HTML 或空响应。排查 Base URLcat ~/.codex/auth.json | python3 -c import json,sys; djson.load(sys.stdin); print(d.get(OPENAI_BASE_URL), d.get(OPENAI_API_BASE))确认输出是https://taotoken.net/api没有多余的/v1或尾部斜杠。然后手动请求一次看返回curl -s -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d {model:gpt-5-codex,messages:[{role:user,content:hi}]} \ | head -c 300如果返回正常 JSON说明端点没问题问题在 Codex 的配置解析。如果返回 HTML 或空检查 URL 路径。5.4 OAuth 相关报错报错原文Error: OAuth flow failed: no browser available远程 SSH 环境没有浏览器Codex 如果尝试走 OAuth 登录就会报这个。修复方法是强制走 API Key 认证在auth.json里确保有preferred_auth_method: apikey同时清掉可能存在的 OAuth token 字段。如果auth.json里有access_token、refresh_token之类的字段删掉只保留 API Key 相关配置。5.5 model not found报错原文Error: model not found: xxx模型 ID 填错了。去 TaoToken 控制台或文档确认可用的模型 ID然后改auth.json和config.toml里的model字段。改完在远程重新验证ssh userremote-host codex config get model5.6 SSH 连接成功但 Codex 命令找不到报错原文bash: codex: command not foundSSH 非交互式会话的 PATH 和交互式不一样。远程装了 Codex 但非交互 shell 找不到。修复方法是在远程把 Codex 加到系统 PATH或者在 SSH 命令里用绝对路径ssh userremote-host ~/.local/bin/codex --version确认绝对路径后在桌面版的 SSH 配置里指定 Codex 的完整路径。6. 把配置固化下来长期使用的几个建议配置跑通之后有几个习惯能让这套东西长期稳定。第一Key 轮换时只改一处。因为本地和远程都读auth.json换 Key 的时候两边都要更新。写个简单脚本同步#!/bin/bash scp ~/.codex/auth.json userremote-host:~/.codex/auth.json ssh userremote-host chmod 600 ~/.codex/auth.json echo auth.json synced每次换 Key 跑一次避免两边不一致。第二config.toml里的approval_policy按项目风险调。个人项目可以放宽到on-request涉及生产代码的仓库建议保持更严格的审批。这个策略在桌面版和 CLI 都生效改一处两边都变。第三远程服务器的auth.json权限定期检查。多用户环境下chmod 600和chmod 700 ~/.codex是底线。可以用一条命令批量确认ssh userremote-host stat -c %a %n ~/.codex ~/.codex/auth.json输出应该是700和600。第四如果团队多人共用远程开发机建议每人用自己的系统账号和独立的~/.codex/auth.json不要共用 Key。TaoToken 控制台可以按成员创建不同的 Key方便追踪用量。第五遇到鉴权问题时排查顺序固定为curl 验证 Key → 检查环境变量覆盖 → 检查auth.json路径和 JSON 格式 → 检查 Base URL 路径 → 检查远程是否同步。按这个顺序走大部分问题五分钟内能定位。需要长期跑编码任务或 Agent 场景的话可以了解 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 配置字段有疑问可以对照文档核对。模型对话调试入口在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 用来快速验证某个模型 ID 是否可用很方便。控制台在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content Key 管理和用量查看都在这里。