Codex Desktop App 支持SSH远程连接了,附操作指南

大家好，我是王胖纸，Atlasnote的独立开发者。

今天想要和大家分享的是Codex desktop app的新功能，SSH远程连接开发。

如果你的代码、依赖、数据库、测试环境不在当前电脑上，而是在 Mac mini、Linux 服务器、VPS 或公司开发机上，那么新版 Codex Desktop App 的 Remote Connections / 远程连接 功能很值得关注。

它可以让你在本地 Codex Desktop App 里，通过 SSH 连接到远程机器，然后让 Codex 在远程机器上读代码、改代码、跑命令、执行测试。

这对多设备开发、远程服务器开发、本地长期运行项目的人非常实用。

它依赖两个前提

在配置 Codex App 之前，先搞清楚一件事：

Codex 远程连接不是单独存在的，它依赖 SSH 和远程 Codex CLI。

你至少要满足两个条件：

第一，本地电脑能通过 SSH 登录远程机器；
第二，远程机器上已经安装并能运行 Codex CLI。

也就是说，在打开 Codex App 填表之前，最好先在终端里确认两件事：

1. 你能通过 SSH 登录远程机器；
2. 登录远程机器后，能正常运行 codex 命令。

更稳妥的操作顺序是：

1. 在远程 Mac 上开启 SSH 远程登录
2. 在本地 Mac 终端里测试能否 SSH 登录远程机器
3. 确认远程机器上能运行 Codex CLI
4. 开启 Codex Desktop App 的远程连接功能
5. 在 Codex App 里添加远程连接

其中第五步有两种填写方式：

方式 A：直接填写 用户名@远程机器地址，适合快速测试
方式 B：通过 ~/.ssh/config 配置 SSH 别名，适合长期使用和多机器管理

下面我们按这个顺序来给出实际操作指南。

第一步：在远程 Mac 上开启 SSH 远程登录

在连接 Codex App 之前，先要确认远程机器允许被 SSH 登录。

如果你的远程机器是 Mac mini，需要在 Mac mini 本机 上打开：

系统设置 → 通用 → 共享 → 远程登录

把 远程登录 打开。

打开后，系统通常会显示一行提示，类似：

若要远程登录这台电脑，请键入：ssh 用户名@这台电脑的地址

这里的 用户名，就是后面 SSH 命令里 @ 前面的部分。

如果不确定用户名是什么，可以在 Mac mini 本机终端里执行：

whoami

输出什么，SSH 命令里的用户名通常就写什么。

如果你通过 Tailscale 连接远程 Mac，可以在 Tailscale 里找到这台 Mac 的地址。文章里统一用下面这种脱敏写法表示IP地址：

100.84.xxx.xxx

真正操作时，把它替换成你自己的 Tailscale IP 或 MagicDNS 地址即可。

第二步：在本地 Mac 终端里测试 SSH 登录

这一步是在你的 本地 MacBook / MacBook Air 的终端 里操作，不是在 Codex App 里操作。

打开终端后，输入：

ssh 用户名@远程机器地址

例如：

ssh Selena@100.84.xxx.xxx

第一次连接时，终端可能会提示是否信任这台主机。输入：

yes

然后回车。

接着会提示输入密码：

Password:

这里输入的是 远程 Mac mini 上这个用户的登录密码，不是 Apple ID 密码。输入时终端不会显示任何字符，直接输入密码后回车即可。

登录成功后，你当前这个终端窗口就已经进入远程 Mac 的命令行环境。可以执行：

whoami
hostname
pwd

如果 hostname 显示的是远程 Mac 的名字，说明 SSH 已经连通。

第三步：确认远程机器上能运行 Codex CLI

接下来要确认远程机器上已经安装 Codex CLI。

先 SSH 登录远程机器。如果你已经配置过 SSH 别名，可以这样登录：

ssh macmini

如果还没有配置别名，也可以直接用用户名和地址登录，例如：

ssh Selena@100.84.xxx.xxx

登录成功后，在远程机器上执行：

which codex
codex --version

如果能看到 Codex 的路径和版本号，说明远程机器上的 Codex CLI 可以正常使用。

你还可以直接执行：

codex

确认 Codex CLI 能正常启动。

第四步：开启 Codex Desktop App 的远程连接功能

在你已经能通过 SSH 登录远程机器，并确认远程 Codex CLI 可用之后，才轮到配置 Codex Desktop App。

在本地电脑上编辑 Codex 配置文件：

nano ~/.codex/config.toml

加入下面这段：

[features]
remote_connections = true

保存后，彻底退出并重启 Codex Desktop App。

这段配置的作用是打开 Codex App 里的远程连接功能入口。官方文档也说明：如果远程连接入口还没有出现，可以在 ~/.codex/config.toml 里启用这个 alpha feature flag。

注意，这个配置是写在本地电脑上的，不是写在远程机器上。

也就是说，如果你是在 MacBook 上使用 Codex Desktop App，就在 MacBook 的：

~/.codex/config.toml

里添加这段。

第五步：在 Codex App 里添加远程连接

重启 Codex Desktop App 之后，进入：

Codex App → Settings → Connections → Add connection

这里会看到一个添加连接的窗口，通常有四个字段：

Display name
HostName
SSH port
Identity file

这个窗口的作用是：手动添加一个 SSH 远程主机。

假设你要连接的是家里的 Mac mini，并且 Mac mini 的 Tailscale IP 是：

100.84.xxx.xxx

Mac mini 上的用户名是：

Selena

这里有两种填写方式。

方式 A：直接填写用户名和远程地址

这是最直接的方式，适合快速测试。

Display name
macmini

HostName
Selena@100.84.xxx.xxx

SSH port
22

Identity file
先留空

也就是：

字段	填什么	解释
Display name	`macmini`	你自己看的名字，可以随便起
HostName	`Selena@100.84.xxx.xxx`	远程 Mac 的用户名 + 远程机器地址
SSH port	`22`	SSH 默认端口
Identity file	先留空	如果连接失败，再考虑指定私钥路径

如果你只是想先确认 Codex App 能不能连上远程机器，可以先用方式 A。

方式 B：通过 `~/.ssh/config` 配置 SSH 别名

如果你准备长期使用，或者以后要管理多台远程机器，更推荐方式 B。

先在本地 Mac 的终端里打开 SSH 配置文件：

nano ~/.ssh/config

加入类似下面的配置：

Host macmini
  HostName 100.84.xxx.xxx
  User Selena
  Port 22

这里的意思是：

Host macmini = 给这台远程机器起一个别名
HostName 100.84.xxx.xxx = 远程机器的真实地址
User Selena = 登录远程机器使用的用户名
Port 22 = SSH 默认端口

保存后，在终端里测试：

ssh macmini

如果可以正常登录，说明这个 SSH 别名配置成功。

然后回到 Codex App 的连接窗口，这样填：

Display name
macmini

HostName
macmini

SSH port
22

Identity file
留空

也就是：

字段	填什么	解释
Display name	`macmini`	你自己看的名字，可以随便起
HostName	`macmini`	`~/.ssh/config` 里配置的 SSH 别名
SSH port	`22`	SSH 默认端口
Identity file	先留空	如果 `ssh macmini` 已经能正常登录，通常可以先不填

方式 B 的好处是：以后如果远程 IP、用户名、密钥路径变化，只需要改 ~/.ssh/config，不用在每个工具里重新改。

Identity file 要不要填？

这个字段最容易让人困惑，单独解释一下。

一般先不填。

只有当你平时 SSH 需要指定私钥时，才需要填。

例如你的私钥路径是：

/Users/Selena/.ssh/id_ed25519

那可以填这个路径。

对应的 SSH 配置可能长这样：

Host macmini
  HostName 100.84.xxx.xxx
  User Selena
  Port 22
  IdentityFile ~/.ssh/id_ed25519

如果你不确定，就先留空。

判断标准很简单：

ssh macmini

或者：

ssh Selena@100.84.xxx.xxx

如果这两条命令已经能正常登录，Identity file 通常就不用填。

保存后做什么？

填写完成后，点击：

Save

保存连接。

接下来，会显示连接成功，接着在Codex 远程连接配置界面中选择Creat a remote projects，会让你选择远程机器上的项目目录，例如：

/Users/Selena/Projects/Atlasnote

选好项目目录后，Codex 就可以在这个远程项目里工作。

你可以先让它执行一些低风险任务，例如：

请先查看当前项目结构，不要修改文件。

或者：

运行 git status，并告诉我当前工作区是否干净。

再进一步让它跑测试：

请运行 npm test，检查当前项目是否能通过测试。

不要一上来就让它大规模改代码。先确认它确实进入了正确的远程目录、能读取项目、能运行命令，再交给它更复杂的任务。

如果保存后连接失败，不要直接怀疑 Codex App。先回到终端分别测试：

ssh macmini
ssh macmini "which codex"

这样能快速判断问题到底出在 SSH 连接，还是远程机器上的 Codex CLI。

常见问题排查

1. SSH 连接不上

先不要管 Codex App，先单独解决 SSH。

测试：

ssh 用户名@远程机器地址

如果失败，常见原因包括：

远程机器没有开启 SSH
用户名写错
IP 地址写错
端口不对
当前网络无法访问远程机器
Tailscale 没有连接成功

如果远程机器是 Mac mini，检查：

系统设置 → 通用 → 共享 → 远程登录

2. SSH 直连可以，但 `ssh macmini` 不行

这说明 SSH 别名配置有问题。

检查：

cat ~/.ssh/config

确认格式类似这样：

Host macmini
  HostName 100.84.xxx.xxx
  User Selena
  Port 22

注意：

Host 后面是别名
HostName 后面是真实地址
User 是远程机器用户名
文件路径是本地电脑上的 ~/.ssh/config

3. SSH 能连上，但 Codex App 连接失败

大概率是远程机器上的 codex 命令找不到。

在本地执行：

ssh macmini "which codex"

如果没有输出，说明远程 login shell 找不到 Codex。

这时需要检查远程机器的 shell 配置，比如：

echo $PATH

以及 Codex CLI 的实际安装位置。

4. Codex App 里看不到 Connections

先确认本地配置文件内容：

cat ~/.codex/config.toml

应该能看到：

[features]
remote_connections = true

然后彻底退出并重启 Codex Desktop App。

如果还是没有入口，可能和当前 App 版本、账号状态或功能灰度有关。这个功能目前仍带有实验性质，不一定所有环境都完全一致。

5. 不要把远程 app server 暴露到公网

这一点很重要。

Codex 远程连接适合通过 SSH 使用，不要随便把远程 app server 直接暴露到公网。

OpenAI 关于 Codex app server 的文档也提醒：loopback listener 适合 localhost 和 SSH port forwarding；如果把非本地 WebSocket listener 暴露出去，需要先配置认证，不要把未认证服务暴露在共享或公网环境中。

务实建议：

只通过 SSH 连接，不要手动开放 Codex app server 端口到公网。

尤其是多人共享服务器、公司服务器、云服务器，更要谨慎。

总结

Codex Desktop App 支持 SSH 远程连接之后，它就不只是一个“本地 AI 编程助手”了。

它更像是一个可以连接多个开发现场的控制台：

MacBook 本地项目
Mac mini 项目
Linux 服务器项目
VPS 项目
公司 devbox 项目

最稳妥的第一步，不是打开 Codex App 设置，而是先在终端里确认两件事：

能 SSH 登录远程机器；
远程机器上能运行 codex 命令。

只要这两个条件满足，Codex Desktop App 的远程连接才真正有效。

如果你对Atlasnote 感兴趣，可以到官网：atlasnote.ai 下载免费试用。也可以参考这篇Atlasnote使用指南。

AtlasNote 完整使用指南 v1.0：从零构建你的专属知识地图

如果你是一个AI新手，想要进阶了解更多AI知识，可以了解一下我的AI新手进阶65课：

全网最贴心AI教程：注册、付费、Prompt，使用指南、私藏工具，Agent....你想要的都在这里了