1. 为什么要在 Codex 里接上 SSH 这条链路Codex 这类命令行 AI 编程助手默认跑在本地终端里读写的是本机文件系统。可现实里很多人的代码根本不在本机——要么在局域网里的一台 Ubuntu 开发机上要么在云上的测试服务器里要么在树莓派、NAS 这类小机器上。你坐在 Windows 笔记本前想用 Codex 直接改远程机器上的项目第一反应就是能不能让 Codex 通过 SSH 连过去干活答案是可以的但这条路不是点一下开关就完事。Codex 本身并不内置一个完整的 SSH 客户端它更多是依赖系统层面的 SSH 能力或者通过配置把远程环境映射成本地可操作的样子。所以真正要解决的问题其实是三件事第一本机和远程机器之间的 SSH 通道要通第二Codex 要能在这个通道上正确执行命令、读写文件第三身份认证、主机指纹、权限这些细节不能出岔子否则就是各种Permission denied、Host key verification failed、Bad owner or permissions轮番上阵。这篇内容适合两类人看。一类是刚装好 Codex想把它用到远程开发场景里的新手你可能连known_hosts和authorized_keys谁是谁都还没分清另一类是用过 SSH 但被 Codex 的报错卡住的老手比如遇到codex auth token is unavailable、cc switch local proxy failed while handling codex endpoint这种看着就头大的提示。我会把整条链路从原理到实操拆开讲包括密钥怎么生成、配置文件怎么写、Windows 和 macOS 上的差异、以及我实际踩过的坑和排查思路。核心关键词 Codex、SSH、身份文件、known_hosts、authorized_keys 会贯穿全文你跟着走一遍基本能把这套流程跑通。先说清楚一个前提Codex 通过 SSH 操作远程机器本质上是本地发起 SSH 连接远程执行命令。它不是一个常驻的远程代理而是每次操作时建立连接、执行、返回结果。理解这一点很关键因为它决定了后面所有配置都是围绕让这条 SSH 连接稳定、免密、可信任来做的。2. 整体设计思路把远程机器变成 Codex 的第二工作区2.1 核心思路与方案选型要让 Codex 用上 SSH市面上大致有三条路可走我逐一分析下为什么最终推荐某一种。第一条路是让 Codex 直接调用系统 ssh 命令。Codex 在执行 shell 命令时如果配置里允许它运行ssh userhost command这种形式那它就能操作远程。这条路最轻量不需要额外装东西缺点是每次都要拼命令交互式操作比如进到远程的交互式 shell 里比较别扭。第二条路是用 SSH 隧道或端口转发把远程服务映射到本地。比如远程跑着一个语言服务器、一个数据库、一个 Web 服务你通过ssh -L把端口转到本地Codex 在本地就能访问。这条路适合远程服务、本地消费的场景但它不解决远程文件系统操作的问题。第三条路是借助编辑器或工具的远程开发能力。比如 VS Code 的 Remote-SSH它会在远程机器上跑一个 server 进程本地编辑器通过 SSH 通道和它通信文件读写、终端执行全都在远程。Codex 如果作为这类环境的补充工具就能间接获得远程能力。我实际用下来最稳的组合是系统 SSH 打通免密登录 Codex 配置允许执行远程命令 必要时用 VS Code Remote-SSH 做文件层面的操作。为什么这么选因为 Codex 的强项是理解代码、生成命令、执行命令它不需要自己实现一套 SSH 协议栈把认证和传输交给成熟的 OpenSSH 就好。你只要保证ssh userhost这条命令在终端里能免密跑通Codex 调用它就不会有额外障碍。这里有个关键判断不要试图让 Codex 去管理 SSH 密钥和密码。密钥的生成、分发、权限设置全部在系统层面用标准工具做完Codex 只负责用这个已经配好的连接。这样职责清晰出问题也好排查——终端里ssh能通Codex 就大概率能通终端里ssh不通先修 SSH别去折腾 Codex。2.2 身份文件、known_hosts、authorized_keys 三者的关系这三个词是热搜里高频出现的很多人搞混。我用一个生活化的类比讲清楚。把 SSH 登录想象成你去一个小区找朋友。authorized_keys是朋友家门口的钥匙孔清单——朋友远程服务器把允许开门的钥匙形状登记在这个文件里只有匹配的钥匙才能进。这个文件在远程机器的~/.ssh/authorized_keys。你的私钥比如id_ed25519就是你自己手里那把钥匙绝对不能给别人。对应的公钥id_ed25519.pub就是钥匙的形状你要把它交给朋友登记。公钥可以随便传私钥泄露等于家门失守。known_hosts则是你手机里存的小区门禁指纹。第一次去朋友家门禁系统会告诉你这个小区指纹是 XXXX你确认后存下来。下次再去门禁指纹对不上系统就报警Host key verification failed防止有人冒充朋友家骗你开门。这个文件在你本机的~/.ssh/known_hosts。所以流程是本机生成密钥对 → 公钥追加到远程的authorized_keys→ 首次连接时确认远程指纹写入本机known_hosts→ 之后免密直连。Codex 要用的就是这条已经打通的链路。注意authorized_keys在远程known_hosts在本地方向别搞反。很多人排查半天结果是往本机的authorized_keys里加公钥那当然没用。2.3 权限问题为什么是重灾区SSH 对文件权限极其敏感这是设计上的安全考量不是 bug。私钥如果权限太开放比如 Windows 上继承了一堆用户权限或者 Linux 上设成 644SSH 会直接拒绝使用报Bad owner or permissions。远程的~/.ssh目录和authorized_keys也一样权限不对就拒绝登录。热搜里那条bad owner or permissions on c:\users\thinkpad/.ssh/config就是典型的 Windows 权限问题。Windows 的权限模型和 Linux 不同OpenSSH for Windows 会检查文件的所有者和 ACL如果配置文件被其他用户或组可写就会报这个错。解决办法后面实操部分会详细讲。3. 核心细节解析与实操要点3.1 密钥生成选对算法一次到位第一步永远是生成密钥对。现在推荐用 Ed25519比 RSA 更短、更快、更安全。命令如下ssh-keygen -t ed25519 -C your_emailexample.com -f ~/.ssh/id_ed25519_codex几个参数解释下。-t ed25519指定算法-C是注释一般写邮箱或用途标识方便你以后知道这把钥匙是干嘛的-f指定文件名我特意加了_codex后缀是为了和默认的id_ed25519区分开——不同用途用不同密钥这是好习惯万一某把钥匙要作废不影响其他连接。执行后会提示你输入 passphrase。这里有个取舍设了 passphrase 更安全但每次用都要输Codex 自动化调用时会卡住。我的建议是如果这台机器只有你自己用、物理安全有保障可以不设直接回车如果是在共享环境或笔记本容易丢就设一个然后配合 ssh-agent 做缓存。ssh-agent 的用法后面讲。生成完你会得到两个文件id_ed25519_codex私钥和id_ed25519_codex.pub公钥。用cat看下公钥内容一长串以ssh-ed25519开头、以你的注释结尾的文本这就是要交给远程机器的东西。实操心得私钥文件生成后Linux/macOS 上立刻chmod 600 ~/.ssh/id_ed25519_codex。Windows 上如果放在C:\Users\你的用户名\.ssh\下通常权限是对的但如果报权限错就得手动修 ACL方法见 3.4 节。3.2 公钥分发authorized_keys 的正确写法把公钥弄到远程机器上有几种方式。最省事的是ssh-copy-idssh-copy-id -i ~/.ssh/id_ed25519_codex.pub userremote_host这条命令会自动把公钥追加到远程的~/.ssh/authorized_keys并且帮你设好目录和文件权限。Linux 和 macOS 上一般都有这个工具。Windows 上如果没有就手动来# 先看下公钥内容 cat ~/.ssh/id_ed25519_codex.pub # 然后登录远程机器手动追加 ssh userremote_host mkdir -p ~/.ssh chmod 700 ~/.ssh echo 粘贴刚才的公钥内容 ~/.ssh/authorized_keys chmod 600 ~/.ssh/authorized_keys这里权限设置是硬性要求~/.ssh必须是 700只有所有者可读写执行authorized_keys必须是 600只有所有者可读写。设错了 SSH 会拒绝读取表现为明明公钥加进去了还是让输密码。注意追加公钥用而不是。用会把原有内容覆盖掉如果这台机器上已经有别人的公钥你就把人家的访问权限删了这在团队共享服务器上是事故。3.3 配置文件让连接变简单每次敲ssh -i ~/.ssh/id_ed25519_codex user192.168.1.100 -p 2222太累而且 Codex 调用时也容易写错。用~/.ssh/config给连接起个别名Host codex-dev HostName 192.168.1.100 User devuser Port 2222 IdentityFile ~/.ssh/id_ed25519_codex IdentitiesOnly yes ServerAliveInterval 60 ServerAliveCountMax 3逐行解释。Host codex-dev是你自定义的别名以后ssh codex-dev就等于连这台机器。HostName是真实地址可以是 IP 也可以是域名。User是远程用户名。Port非 22 时必填。IdentityFile指定用哪把私钥。IdentitiesOnly yes很关键——它强制只用指定的这把钥匙避免 SSH 把 agent 里其他钥匙挨个试一遍既慢又可能触发远程的登录失败锁定。ServerAliveInterval和ServerAliveCountMax是保活设置每 60 秒发一次心跳连续 3 次没响应就断开防止连接被中间设备静默掐断。配好之后ssh codex-dev应该直接进去不再问密码。这一步通了Codex 那边基本就顺了。3.4 Windows 权限修复Bad owner or permissions 的根治Windows 上这个报错太常见了。原因是 OpenSSH for Windows 检查~/.ssh/config或私钥文件时发现除了当前用户之外还有其他主体比如Users组、Authenticated Users有写权限就判定不安全。修复方法是用icacls重置权限。以管理员身份打开 PowerShell执行# 先移除继承 icacls C:\Users\你的用户名\.ssh\config /inheritance:r # 只给当前用户完全控制 icacls C:\Users\你的用户名\.ssh\config /grant:r %USERNAME%:F # 私钥文件同样处理 icacls C:\Users\你的用户名\.ssh\id_ed25519_codex /inheritance:r icacls C:\Users\你的用户名\.ssh\id_ed25519_codex /grant:r %USERNAME%:F/inheritance:r是移除从父目录继承的权限/grant:r是替换式授予。做完之后再用icacls 文件名检查应该只剩当前用户一条记录。这个坑我踩过不止一次尤其是把.ssh目录从别的地方拷贝过来、或者用某些同步工具同步过之后权限就乱了。实操心得如果你在 Windows 上同时用 Git Bash、PowerShell、WSL 三套环境注意它们的~/.ssh可能指向不同位置。Git Bash 的~通常是C:\Users\用户名WSL 的~是 Linux 子系统里的家目录。别在一套里配好了跑到另一套里发现不生效。4. 实操过程与核心环节实现4.1 完整流程走一遍假设场景Windows 笔记本上的 Codex要连局域网里一台 Ubuntu 开发机IP 是 192.168.1.100用户名 devuserSSH 端口默认 22。第一步本机生成密钥。打开 PowerShell 或 Git Bashssh-keygen -t ed25519 -C codex-remote-dev -f ~/.ssh/id_ed25519_codex一路回车不设 passphrase个人开发机场景。第二步分发公钥。如果 Windows 上没有ssh-copy-id用这条一行命令搞定cat ~/.ssh/id_ed25519_codex.pub | ssh devuser192.168.1.100 mkdir -p ~/.ssh chmod 700 ~/.ssh cat ~/.ssh/authorized_keys chmod 600 ~/.ssh/authorized_keys这条命令把本地公钥通过管道传给远程远程执行创建目录、设权限、追加内容。第一次会问远程密码输一次就行。第三步配置别名。编辑~/.ssh/config加入 3.3 节那段配置把 Host 改成codex-dev。第四步验证免密登录ssh codex-dev echo connected hostname whoami如果直接输出connected、主机名和用户名说明链路通了。这一步是分水岭通了再往下走 Codex 配置。第五步配置 Codex。具体配置项取决于你用的 Codex 版本和形态。核心是让它知道可以执行远程命令并且允许访问~/.ssh/config里定义的别名。有些版本需要在配置里显式声明允许的 host 白名单有些则直接继承系统 SSH 配置。如果你遇到codex auth token is unavailable那通常是 Codex 自身的认证问题和 SSH 无关需要先解决 Codex 的登录态。第六步实测。让 Codex 执行一个远程命令比如列出远程机器上 /home/devuser/project 目录的内容。观察它是否能正确调用ssh codex-dev ls -la /home/devuser/project并返回结果。4.2 参数选择背后的计算与考量为什么ServerAliveInterval设 60 秒这是经验和网络环境的平衡。设太短比如 10 秒心跳包太频繁浪费带宽移动网络下还费电设太长比如 300 秒中间的路由器、防火墙可能 120 秒就清理空闲连接了你还没发心跳连接已经断了。60 秒是大多数 NAT 设备超时时间通常 120-300 秒的一半留足余量。ServerAliveCountMax 3意味着连续 3 次心跳无响应才断开总共容忍 180 秒的网络抖动。如果你的网络特别不稳定可以调到 5如果追求快速失败调到 2。Ed25519 密钥长度固定 256 位安全性相当于 RSA 3072 位但签名和验证速度快得多密钥文件也小。这就是为什么现在新配的密钥都推荐 Ed25519除非远程是老旧的 SSH 服务不支持极少见。4.3 实操现场记录一次典型的连接失败排查有次我配好之后ssh codex-dev报 WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY! ... Offending ECDSA key in /Users/me/.ssh/known_hosts:12这是known_hosts里存的指纹和远程当前指纹对不上。常见原因远程机器重装了系统、换了 SSH 主机密钥、或者 IP 被重新分配给了另一台机器。排查思路是先确认远程机器确实是你预期的那台比如通过带外方式登录确认确认无误后删掉known_hosts里对应的旧记录ssh-keygen -R 192.168.1.100这条命令会精确删除该主机在known_hosts里的所有记录下次连接重新确认指纹。千万别图省事直接rm ~/.ssh/known_hosts那会把你所有主机的记录都清掉下次连每台机器都要重新确认。5. 常见问题与排查技巧实录5.1 高频报错速查表报错信息根本原因解决方向Permission denied (publickey)公钥没加到远程 authorized_keys或权限不对检查远程~/.ssh/authorized_keys内容和权限Host key verification failedknown_hosts 指纹不匹配ssh-keygen -R host后重连确认Bad owner or permissions on .../.ssh/config文件权限过开放Windows 常见用 icacls 重置权限只留当前用户Connection timed out网络不通、端口被挡、IP 错误ping 测试、telnet 测端口、检查防火墙Connection refusedSSH 服务没启动或端口不对远程systemctl status sshd确认端口codex auth token is unavailableCodex 自身认证失效重新登录 Codex与 SSH 无关cc switch local proxy failed while handling codex endpointCodex 代理配置问题检查 Codex 的网络/代理设置5.2 独家避坑技巧技巧一用ssh -v看全过程。连接出问题时加-v参数verboseSSH 会打印每一步的详细日志用了哪把密钥、尝试了哪些认证方式、卡在哪一步。-vvv更详细。这是排查 SSH 问题最有效的工具没有之一。日志里看到Offering public key之后没有Server accepts key基本就是公钥没配对或权限问题。技巧二远程 sshd 日志要看。如果本机日志看不出问题去远程机器看/var/log/auth.logDebian/Ubuntu或/var/log/secureRHEL/CentOS。远程会记录为什么拒绝你的登录比如Authentication refused: bad ownership or modes for directory /home/devuser/.ssh直接告诉你权限问题。技巧三多密钥环境用 IdentitiesOnly。如果你~/.ssh下有好几把密钥SSH 默认会挨个尝试远程可能因为尝试次数过多触发MaxAuthTries限制而拒绝。在 config 里加IdentitiesOnly yes强制只用指定的钥匙干净利落。技巧四ssh-agent 管理 passphrase。如果你设了 passphrase 又不想每次输用 ssh-agenteval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519_codex这样在当前会话里agent 帮你记住了解锁的密钥。macOS 上可以加--apple-use-keychain参数把 passphrase 存进钥匙串重启后也不用重输。技巧五Codex 调用远程命令时注意引号转义。Codex 生成的命令如果包含引号、变量、管道经过 SSH 传输时可能被本地 shell 和远程 shell 各解析一次导致行为不符预期。稳妥做法是把远程要执行的命令用单引号包起来或者写成脚本传过去执行。比如ssh codex-dev cd /project git status单引号保证本地不解析远程原样执行。5.3 关于 Codex 与 SSH 配合的边界需要明确一点Codex 通过 SSH 操作远程能力边界取决于 SSH 本身。它能执行远程命令、读写远程文件通过命令但它不是一个实时的远程文件系统挂载。如果你需要 Codex 像操作本地文件一样操作远程文件更顺滑的方案是配合 VS Code Remote-SSH 或类似的远程开发环境让远程目录在编辑器里呈现为工作区Codex 在这个工作区里工作体验会好很多。另外Codex 的某些功能比如代码索引、语言服务在纯 SSH 命令模式下可能受限因为这些功能需要持续的文件系统访问而不是一次性的命令执行。这种场景下远程开发环境 Codex 的组合比纯 SSH 命令更合适。6. 让这套流程长期稳定的几个习惯配通只是开始长期用下来有几个习惯能帮你少踩坑。第一密钥分用途。工作用一把、个人项目用一把、CI/CD 用一把别一把钥匙走天下。哪把泄露了只作废那一把authorized_keys里删掉对应行即可不影响其他。第二定期清理 known_hosts。机器下线、IP 变更后旧记录留着只会带来Host key verification failed。用ssh-keygen -R精确清理别整个删。第三config 文件加注释。~/.ssh/config里每个 Host 块上面写一行注释说明用途几个月后回来看你还知道codex-dev是哪台机器。第四远程 sshd 配置加固。如果这台机器长期给 Codex 用建议在远程/etc/ssh/sshd_config里关掉密码登录PasswordAuthentication no只留密钥登录安全性提升一大截。改完记得systemctl restart sshd而且重启前确保你的密钥登录已经验证通过否则可能把自己锁在外面。第五网络不稳定时用 mosh 或 autossh。如果连接经常断纯 SSH 的保活机制可能不够。mosh 对移动网络和断线重连支持更好autossh 能在断线后自动重连。不过这两个是额外工具Codex 调用时未必兼容看你的具体场景取舍。我个人在实际操作中的体会是SSH 这条链路的问题90% 出在权限和指纹这两件事上。把~/.ssh目录、私钥、远程authorized_keys的权限设对把known_hosts维护干净剩下的基本就是网络和服务端配置问题按速查表逐个排就行。Codex 本身在这条链路里是个使用者它不制造 SSH 问题只是把 SSH 的问题暴露得更明显——因为自动化调用不会像人一样重试一下就好了它一失败就报错反而帮你更快定位到根因。