从 SSH 配置到远程开发：Codex 连接云服务器实战指南

本文以本地 macOS 或 Linux、远端 Linux 云服务器为例，介绍如何配置 SSH、安装 Codex、完成登录，并在桌面应用中使用远程项目。文中的地址、用户名和目录均为示例，执行前需要替换；本文未连接读者的真实服务器。

把 Codex 接到云服务器，关键是让它进入正确的执行环境。代码在服务器上，就应确认读取、修改和测试都发生在那里；服务器拥有项目文件，还不代表它已经具备 Git 凭据、运行依赖和模型服务的访问条件。把这些环节逐项验证，比直接在聊天框里输入“帮我连接服务器”更可靠。

第一步：选择连接方式

官方远程项目流程是在服务器上安装并认证 Codex，再由桌面应用通过 SSH 启动远端服务。本文以前两种方式为主。第三种方式中，本地任务不会自动变成远程项目，必须明确每条命令的执行位置。

连接流程：本地电脑 → SSH → 云服务器上的 Codex → 远程项目文件与依赖。服务器还需要能够访问登录及模型服务；SSH 连通只完成了其中一段。

第二步：准备服务器访问条件

准备服务器公网地址或可达的内网地址、SSH端口、登录用户名、对应私钥和项目路径。云安全组与系统防火墙需要允许来自你所在网络的 SSH 连接。如果服务器只在内网开放，应先连接获授权的 VPN 或堡垒机。无需为普通 SSH 远程项目另行公开一个未鉴权的 Codex 服务端口。

• 可达的服务器地址与实际 SSH 端口。
• 获授权的普通用户及对应私钥。
• 已准备好的远程项目目录。
• 服务器访问登录与模型服务所需的网络条件。

下面使用保留的文档示例地址203.0.113.10、普通用户deploy，以及项目目录 /home/deploy/projects/my-app。它们不指向可供读者直接登录的真实服务器。优先使用有项目访问权限的普通账号，只有确实需要系统管理时再提升权限。

第三步：配置本地 SSH 别名

准备密钥与公钥授权

先确认已有私钥对应的公钥已配置到服务器账号。若云厂商提供了密钥文件，直接使用该文件；若没有密钥，可以在本地生成专用密钥，再通过云控制台或现有登录方式安装公钥。不要覆盖已有密钥，也不要上传私钥。

# 仅在尚未配置密钥且下列文件名未被使用时执行
ssh-keygen -t ed25519 -f ~/.ssh/codex_cloud_ed25519 -C "codex-cloud"

添加主机别名

随后在本地 ~/.ssh/config 中追加下面的主机段，保留其他主机配置。IdentityFile 必须改成实际私钥路径；如果使用不同的 SSH 端口，也一并调整。

Host codex-cloud
    HostName 203.0.113.10
    User deploy
    Port 22
    IdentityFile ~/.ssh/codex_cloud_ed25519
    IdentitiesOnly yes
    ServerAliveInterval 30
    ServerAliveCountMax 3

Codex 会从 SSH 配置中发现明确命名的主机别名，因此要写出 codex-cloud 这样的具体名称，不能仅依靠 Host *。在 macOS 和 Linux 上，将配置与私钥的权限限制为当前用户可读写。

chmod 700 ~/.ssh
chmod 600 ~/.ssh/config
chmod 600 ~/.ssh/codex_cloud_ed25519
ssh codex-cloud

第一次连接时，将主机指纹与云控制台或管理员提供的信息核对后再接受。出现主机密钥变化提示时，先查明服务器是否重建或地址是否改变，不要通过关闭主机验证来绕过提示。

第四步：在服务器安装 Codex

登录后先运行下面的只读命令，确认账号和主机。安装和认证要使用桌面端 SSH 配置里指定的同一个用户，避免把 Codex 安装到另一位用户的环境。

hostname
whoami
pwd

方式一：独立安装脚本

官方为 macOS 和 Linux 提供独立安装脚本。可先下载和阅读脚本，再执行安装；按安装输出处理 PATH，并重新登录 SSH。以下是要在服务器终端执行的命令，不是在本地电脑安装。

curl -fsSL https://chatgpt.com/codex/install.sh -o codex-install.sh
less codex-install.sh
sh codex-install.sh

方式二：使用 npm 安装

如果服务器已经准备好适用的 Node.js 与 npm 环境，也可改用 npm 安装；两种方式任选一种即可。

npm install -g @openai/codex
codex --version

采用独立安装方式后，同样执行 codex --version。若提示找不到命令，先查看安装位置和 shell 的 PATH，不要立即改用 root 重装。远程桌面连接使用远端用户的登录 shell，该环境也必须能找到 codex。

第五步：完成服务器端身份验证

服务器没有浏览器时，可使用官方提供的设备代码登录。个人账户需要启用相应安全设置；工作空间可能需要管理员开放该功能。

codex login --device-auth

根据服务器终端提示，在自己电脑的浏览器里打开登录页面并输入一次性代码。完成授权后返回服务器，检查身份验证状态。一次性代码和登录缓存都不应粘贴到公共聊天或代码仓库。

codex login status

SSH 密钥用于验证服务器登录身份，Codex 登录用于访问模型服务，两者不能互相替代。如果设备代码登录不可用，先检查账户策略和远端网络，再选择官方支持的其他认证方式。不要把本地已经登录理解成服务器也已自动登录。

第六步：先在服务器终端验证项目

切换到实际项目目录再启动 Codex。下面假设目录已存在；如果项目还未准备好，需要先通过正常的代码管理流程放到服务器。读取私有代码仓库所需的 Git 凭据应另行配置。

cd /home/deploy/projects/my-app
codex

第一次测试可以输入：“仅检查当前项目，告诉我主机名、当前目录、项目使用的语言以及测试入口，暂时不要修改文件。”返回结果应与目标服务器和项目匹配。随后再授权一个小范围任务，检查修改内容并运行对应测试。

如果只需要终端工作，到这里已经可以开始使用。如果还要通过本地桌面应用操作，继续完成下一步。

第七步：在桌面应用添加 SSH 主机与远程项目

返回本地桌面应用，进入设置中的“连接”页面，找到 SSH 连接区域，添加或启用 codex-cloud，然后选择服务器上的项目文件夹。当前官方文档以此流程连接 SSH 主机；界面文字可能随客户端版本有所调整。

1. 打开桌面应用的设置与连接页面。
2. 添加或启用 codex-cloud 对应的 SSH 主机。
3. 选择服务器上的项目文件夹。
4. 在远程项目任务中核对主机名、当前目录和测试入口。

添加后确认所选的是远程主机上的目录，而不是本地同名文件夹。打开远程项目任务，再执行一次只读环境检查。项目依赖、命令行工具和凭据来自服务器环境，本地安装的 Python、Node.js 或其他工具不会自动出现在远端。

验收顺序：SSH 可登录 → 远端可运行 codex → 身份验证有效 → 能读取目标项目 → 桌面任务显示正确主机与目录 → 小范围修改和测试通过。任一环节失败，都先停在该环节排查。

第八步：按层排查连接问题

需要更详细的 SSH 排查信息时，在本地运行 ssh -v codex-cloud。分享日志前应遮盖账号、主机地址和本地敏感路径。不要公开私钥、访问令牌或完整认证缓存。

服务器重启、软件升级或账号切换后，重新核对 CLI 版本、认证状态和项目环境。连接成功并不意味着每个任务都有同样的权限；应根据项目需要开放能力，让修改和测试都能够被检查。

配置完成后，你可以在本地发出任务，在云服务器上使用真实的项目文件、依赖和计算资源。日常使用时，先确认主机与目录，再提出具体任务并检查结果，便能减少“本地操作成功、远端环境不一致”带来的反复排障。