codex-ssh-mcp

把 VPS 上的 Codex 变成本地 Claude Code 可以调用的远程子代理。

为什么需要这个项目

很多人会有这样的工作方式：

• 本地电脑上使用 Claude Code 做主要开发和任务拆解。
• 另一台 VPS 上已经装好了 Codex，并且可以通过 SSH 登录后使用。
• VPS 上可能有更稳定的运行环境、更完整的依赖、更适合跑测试的系统，或者长期保存的项目目录。

问题是：Claude Code 和 VPS 上的 Codex 原本是两个分开的交互式工具。你需要手动 SSH 到 VPS，再复制粘贴任务、结果和 diff。

codex-ssh-mcp 做的事情就是把中间这段接起来：

本地 Claude Code
  -> codex-ssh-mcp
  -> SSH 到 VPS
  -> 在 VPS 仓库里运行 codex exec
  -> 返回 Codex 结果、git status、git diff

这样你可以在本地 Claude Code 里直接说：

让远端 Codex 检查 vps-main/my-app 这个项目的风险点。

Claude Code 会通过 MCP 调用这台 VPS 上的 Codex，而不是让你手动切终端。

适合谁

这个项目适合：

• 已经在本地使用 Claude Code。
• 已经有一台 VPS，并且 VPS 上装好了 Codex。
• 希望把 VPS Codex 当成 Claude Code 的 worker/sub-agent。
• 希望远端 Codex 在 VPS 的真实项目目录里工作。
• 希望用 Git diff 作为本地和远端之间的同步边界。

它不适合：

• 想把本地和 VPS 文件夹做实时双向同步。
• 想远程控制 Codex 的交互式 TUI。
• 不想配置 SSH key，只想用 SSH 密码长期自动化登录。

当前能力

• 通过 SSH 调用远端 codex exec。
• 支持 Linux VPS，默认使用 bash。
• 支持 Windows VPS，手动设置 shell = "powershell"。
• 只允许访问配置白名单里的远端仓库。
• 返回远端 Codex 的最终回复。
• 返回远端仓库的 git status --short。
• 返回远端仓库的 git diff --binary HEAD。
• 写入模式需要每个仓库显式开启。

工作模型

这个项目默认把 Git 当作本地和 VPS 的同步边界。

推荐流程：

1. Claude Code 调用 codex-ssh-mcp。
2. codex-ssh-mcp 通过 SSH 在 VPS 指定仓库运行 Codex。
3. VPS Codex 完成任务。
4. codex-ssh-mcp 返回结果、变更文件列表和 diff。
5. 你或 Claude Code 决定是否应用、提交或丢弃这些变更。

它不会自动覆盖你的本地文件。

前置条件

本地需要：

• Node.js 20+
• Claude Code
• 可以非交互登录 VPS 的 SSH key

VPS 需要：

• 已安装并登录 Codex
• 已安装 Git
• 项目已经是 Git 仓库

先确认本地可以免密码 SSH 到 VPS：

ssh -i ~/.ssh/codex_ssh_mcp_ed25519 -o BatchMode=yes ubuntu@your-vps 'echo ok'

再确认 VPS 上 Codex 可用：

ssh ubuntu@your-vps 'cd /srv/my-app && codex exec "reply with ok"'

安装

git clone https://github.com/jlcbk/codex-ssh-mcp.git
cd codex-ssh-mcp
npm install
npm run build

配置 Linux VPS

创建 ~/.codex-ssh-mcp/config.toml：

[profiles.vps-main]
host = "your-vps-host"
user = "ubuntu"
ssh_options = [
  "-i",
  "/path/to/private_key",
  "-o",
  "BatchMode=yes"
]

[profiles.vps-main.repos.my-app]
path = "/srv/my-app"
default_mode = "read-only"
allow_write = true
timeout_seconds = 1800

Linux 是默认远端类型。不写 shell 时，程序会使用 bash。

配置 Windows VPS

Windows VPS 需要显式写：

shell = "powershell"

示例：

[profiles.windows-vps]
host = "203.0.113.20"
user = "Administrator"
shell = "powershell"
ssh_options = [
  "-i",
  "/path/to/private_key",
  "-o",
  "BatchMode=yes"
]

[profiles.windows-vps.repos.my-app]
path = "C:\\Users\\Administrator\\my-app"
default_mode = "read-only"
allow_write = false
timeout_seconds = 600

接入 Claude Code

在本地注册 MCP server：

claude mcp add codex-ssh -- node /path/to/codex-ssh-mcp/dist/index.js --config ~/.codex-ssh-mcp/config.toml

检查是否连接成功：

claude mcp get codex-ssh

看到 Status: ✔ Connected 就可以用了。

在 Claude Code 里怎么用

可以这样说：

Use codex-ssh to check_remote for profile vps-main and repo my-app.

或者：

Use codex-ssh to run_codex_task on profile vps-main repo my-app in read-only mode. Ask remote Codex to summarize the repo.

如果要允许远端 Codex 修改文件，需要配置：

allow_write = true

然后在调用时使用：

mode workspace-write

MCP 工具

codex-ssh-mcp 暴露三个工具：

• list_profiles：列出可用的 VPS profile 和 repo。
• check_remote：检查 SSH、Codex、Git、远端仓库是否可用。
• run_codex_task：在远端仓库里运行 Codex，并返回结果和 Git diff。

安全边界

• Claude Code 只能访问配置文件里白名单声明的 VPS 和仓库。
• Prompt 通过 stdin 传给远端 Codex，不拼进 shell 命令。
• 默认只读。
• 写入模式必须通过 allow_write = true 显式开启。
• 每次执行后都会返回 Git status 和 diff，方便你审查远端发生了什么。
• 建议使用 SSH key，不建议把 SSH 密码放进配置文件。

开发

npm test
npm run typecheck
npm run build