---

title: “从零开始：Codex App 通过 SSH 连接云服务器”
date: 2026-08-15
tags: [Codex, SSH, 云服务器, Ubuntu, Windows]
categories: [开发工具]

从零开始：Codex App 通过 SSH 连接云服务器

本文记录如何让 Codex App 直接通过 SSH 连接 Linux 云服务器：从创建云服务器、配置 SSH 密钥、安装服务器端 Codex CLI，到在 Codex App 中添加连接。

文中的连接信息均为占位符，请自行替换：

占位符	含义
<server-host>	云服务器公网 IP 或域名
<server-user>	服务器登录用户
<ssh-port>	SSH 监听端口
<server-alias>	本机设置的 SSH 别名

1. 准备工作

需要准备：一台有公网 IP 的 Ubuntu 22.04 或其他兼容 Linux 云服务器、云平台控制台权限、Windows 本机的 Codex App，以及本机的 OpenSSH 客户端。

整体链路如下：

Codex App（Windows） ── SSH 密钥 ──> Linux 云服务器
                                      └── Codex CLI / app-server

注意：SSH 登录成功只说明可以进入服务器。Codex App 建连时还要在服务器启动 Codex CLI 的 app-server，所以服务器端必须完成 CLI 安装和登录。

2. 创建并初始化云服务器

在云平台创建 Ubuntu 22.04 LTS 实例后，记录公网地址、初始用户和 SSH 端口。在安全组/防火墙中放行 SSH 的 TCP 端口。生产环境建议仅允许自己的公网 IP 访问，避免长期对所有地址开放。

通过云控制台或初始登录方式进入服务器，更新基础软件：

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl wget ca-certificates

3. 服务器端安装并登录 Codex CLI

3.1 安装 Node.js

服务器已有合适的 Node.js 可跳过。本例使用 Miniconda 管理 Node.js 环境：

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh
# 初始化 conda 时选择 yes
source ~/.bashrc
conda create -n codex python=3.10 -y
conda activate codex
conda install nodejs -c conda-forge -y
node -v
npm -v

Codex CLI 不依赖 Python；Conda 在这里仅用于管理 Node.js，也可以使用 nvm 或系统包管理器。

3.2 安装并认证 Codex CLI

npm install -g @openai/codex
codex --version
# 1. 先登录
codex login --device-auth
# 2. 再验证 app-server
codex app-server daemon bootstrap

app-server 是 Codex 在远程主机上运行的核心服务，用于处理本地 Codex App 发来的连接请求。因此，后文执行 codex app-server daemon bootstrap 的目的，是在 App 连接前确认这项远程服务能够正常启动。

3.3 配置 Conda Wrapper，确保 codex 全局可用

上一步中的 codex 安装在 Conda 环境内。如果新开终端时没有执行 conda activate codex，系统可能找不到 codex 命令，Codex App 通过 SSH 启动远程服务时也会失败。

解决方法是在当前服务器用户的 ~/.local/bin 创建一个同名 Wrapper。Wrapper 每次运行时自动进入 Conda 环境，再调用其中真正的 Codex CLI。

先创建目录和脚本：

mkdir -p ~/.local/bin
nano ~/.local/bin/codex

粘贴以下内容；CONDA_ROOT 应改为实际的 Miniconda 安装目录，默认通常是 $HOME/miniconda3：

#!/usr/bin/env bash
set -euo pipefail

CONDA_ROOT="$HOME/miniconda3"
CONDA_ENV="codex"

if [ ! -f "$CONDA_ROOT/etc/profile.d/conda.sh" ]; then
  echo "Conda initialization script not found: $CONDA_ROOT" >&2
  exit 1
fi

source "$CONDA_ROOT/etc/profile.d/conda.sh"
conda activate "$CONDA_ENV"

CODEX_BIN="$CONDA_PREFIX/bin/codex"
if [ ! -x "$CODEX_BIN" ]; then
  echo "Codex CLI not found in Conda environment: $CONDA_ENV" >&2
  exit 1
fi

exec "$CODEX_BIN" "$@"

保存后赋予执行权限，并让新终端能找到该目录：

chmod 755 ~/.local/bin/codex
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

打开一个新的 SSH 终端（不要执行 conda activate codex），验证 Wrapper 是否生效：

which codex
codex --version

预期 which codex 输出 $HOME/.local/bin/codex，且版本命令正常返回。若 Miniconda 安装在其他目录，只需修改 Wrapper 中的 CONDA_ROOT。

3.4 开启远程功能并完成登录

创建服务器端配置：

mkdir -p ~/.codex

编辑 ~/.codex/config.toml。若已有 [features]，只添加键值，不要重复创建配置段：

[features]
remote_connections = true

然后执行设备授权登录：

codex login --device-auth

终端会显示授权网页与验证码。用本机浏览器完成授权后，在服务器验证：

codex whoami
codex app-server daemon bootstrap

这两条命令都应能正常执行。前者验证服务器登录态，后者验证 Codex App 连接所需的远程服务能够启动。

4. 本机配置 SSH 密钥

4.1 生成 ed25519 密钥

在本地 Windows PowerShell 执行：

ssh-keygen -t ed25519 -C "codex-remote"

默认会在当前 Windows 用户目录的 .ssh 文件夹中生成私钥 id_ed25519 和公钥 id_ed25519.pub。私钥只留在本机，上传的是公钥。

4.2 将公钥添加到服务器

通过服务器云控制台或现有 SSH 会话进入服务器：

mkdir -p ~/.ssh
chmod 700 ~/.ssh
echo "粘贴 id_ed25519.pub 的完整内容" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

不要把私钥写入 authorized_keys。公钥必须是完整的一行。

5. 配置本机 SSH 别名

创建本机用户目录下的 .ssh\config 文件（没有 .txt 后缀）：

Host <server-alias>
    HostName <server-host>
    Port <ssh-port>
    User <server-user>
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes

IdentitiesOnly yes 强制 SSH 使用指定私钥，避免其他密钥干扰。后两行用于定期发送保活请求，降低网络短暂抖动导致连接被断开的概率。

在 PowerShell 中测试：

ssh <server-alias> "echo ok"

输出 ok 表示基础 SSH 已成功。首次连接时要核对服务器指纹并输入 yes。

6. 在 Codex App 中添加连接

编辑本机用户目录下的 .codex\config.toml；已有 [features] 时合并下面两项：

[features]
remote_control = true
remote_connections = true

从系统托盘选择 Quit，完全退出 Codex App 并重新启动。然后在 App 中依次打开：

Settings → Connections → Add Connection → SSH

推荐填写：

配置项	内容
显示名称	任意，例如 My Cloud Server
主机名	<server-alias>
SSH 端口	留空
用户名	留空
认证方式	使用 SSH config / 无身份验证（以界面实际选项为准）

只填写 SSH 别名，不要在 App 中重复填写 IP、端口和私钥；这些信息已经集中在 SSH config 中。保存后点击连接，出现 Connected 即表示成功。

7. 遇到的问题与解决方式

7.1 连接延迟较高

报错信息：

SSH: app-server bootstrap timed out after 60000ms

原因：本机到云服务器距离较远、本地网络不稳定或带宽被占用，都会使 SSH 输入和命令响应变慢。若只有 Codex 回复慢，通常是服务器侧网络出口或服务响应较慢。

解决方法：

1. 优先选择距离自己更近的云服务器地域；
2. 停止或限速本机占用带宽的下载、同步任务；
3. 使用稳定网络，并在 SSH config 中保留：

ServerAliveInterval 30
ServerAliveCountMax 3

4. 若 SSH 正常但 Codex 仍慢，在服务器执行：

codex whoami
codex app-server daemon bootstrap

确认服务器端登录和网络正常。

7.2 修改 SSH 端口

报错信息：

ssh: connect to host <server-host> port <ssh-port>: Connection timed out

原因：云安全组、服务器 SSH 服务和本机连接配置使用的端口不一致，导致 SSH 连接失败或超时。

解决方法：

1. 先在云平台安全组中放行 <ssh-port>，并保留当前 SSH 会话；
2. 编辑服务器 SSH 配置：

sudoedit /etc/ssh/sshd_config

3. 将配置设为：

Port <ssh-port>

4. 重启 SSH 服务：

sudo systemctl restart ssh

CentOS/RHEL 可使用 sudo systemctl restart sshd。

5. 新开 PowerShell 窗口测试：

ssh -p <ssh-port> <server-user>@<server-host> "echo ok"

6. 返回 ok 后，将同一端口写入本机 SSH config 的 Port 字段。测试成功前不要关闭旧会话。

7.3 使用 SSH 别名连接

报错信息：

Permission denied (publickey,gssapi-keyex,gssapi-with-mic,password)

原因：连接参数分散在命令行和 App 表单中，容易遗漏 IP、端口、用户名或私钥，导致 PowerShell 与 Codex App 的连接配置不一致。

解决方法：

1. 在本机 .ssh\config 中集中配置：

Host <server-alias>
    HostName <server-host>
    Port <ssh-port>
    User <server-user>
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes

2. PowerShell 中使用别名测试：

ssh <server-alias> "echo ok"

3. 输出 ok 后，在 Codex App 的主机名中也填写 <server-alias>；端口和用户名留空，让 SSH config 提供连接参数。

8. 最终检查清单

• 安全组已放行实际 SSH 端口；
• 服务器已安装 Codex CLI，codex --version 有输出；
• 服务器 codex whoami 已确认登录；
• 服务器 codex app-server daemon bootstrap 可正常运行；
• 公钥已加入服务器 authorized_keys；
• 本机 ssh <server-alias> "echo ok" 返回 ok；
• Codex App 使用 SSH 别名连接；
• 如修改端口，已先通过新终端测试成功。

参考资料

1. OpenAI 官方 Codex 文档
2. BioCloudAI：Codex 配置文档
3. CSDN 参考文章