# codex-ssh-mcp

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

## 为什么需要这个项目

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

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

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

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

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

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

```text
让远端 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 的同步边界。

推荐流程：

```text
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：

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

再确认 VPS 上 Codex 可用：

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

## 安装

```bash
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`：

```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 需要显式写：

```toml
shell = "powershell"
```

示例：

```toml
[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：

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

检查是否连接成功：

```bash
claude mcp get codex-ssh
```

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

## 在 Claude Code 里怎么用

可以这样说：

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

或者：

```text
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 修改文件，需要配置：

```toml
allow_write = true
```

然后在调用时使用：

```text
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 密码放进配置文件。

## 开发

```bash
npm test
npm run typecheck
npm run build
```