Railway CLI对接桌面端:Claude Code Desktop、Codex与OpenCode一键连接配置指南
Railway CLI对接桌面端:Claude Code Desktop、Codex与OpenCode一键连接配置指南
Railway CLI 是用于管理 Railway 云项目的命令行工具,其 railway ca desktop 命令可以实现桌面端一键连接:把 Claude Code Desktop、Codex、OpenCode Desktop 直接接到云端虚拟机(Cloud Agent)上,让 AI 编程在云端算力中运行。本文带你快速完成 Railway CLI 桌面端对接的全部配置。
什么是 Railway CLI 桌面端对接?
传统 AI 编程工具运行在本机,受本地硬件和环境的限制。完成 Railway CLI 桌面端对接后,架构变成这样:
- 云端虚拟机(Cloud Agent):承载编程后端(Codex App Server、
opencode serve、Claude 等)与项目文件 - 本地桌面应用:只负责交互界面,像普通本地会话一样使用
- Railway CLI:自动完成 SSH 配置、凭据导入、服务器启动与验证等全部连接细节,无需手工配置
✅ 配置完成后,在桌面应用里找到带 Railway: <agent 名称> 标签的项目,即可直接开始云端会话。
三步完成一键连接:最快配置方法
第一步:安装并登录 Railway CLI
bash <(curl -fsSL railway.com/install.sh) -y
railway login
第二步:选择桌面端应用,执行一键连接命令
| 桌面端应用 | Railway CLI 桌面端连接命令 |
|---|---|
| Claude Code Desktop | railway ca desktop --claude |
| Codex Desktop | railway ca desktop --codex |
| OpenCode Desktop | railway ca desktop --opencode |
| 一次配置多个应用 | railway ca desktop --claude --codex |
命令执行后,CLI 会自动:复用或创建云端 VM → 完成对应编程后端的登录 → 写入本地连接配置,并在结尾输出摘要面板(Agent 名称、SSH 别名、打开目录、下一步指引)。
第三步:在桌面应用中打开云端项目
- Claude Code Desktop:重启应用,在环境下拉列表中找到该 Agent 的名称
- Codex Desktop:重启应用,在项目侧边栏找到
Railway: <agent 名称> - OpenCode Desktop:打开 Home → Projects,找到
Railway: <agent 名称>(对应/app目录),点击 New session 开始
⚠️ 桌面应用连接时,云端 VM 必须处于清醒状态——中继服务会拒绝休眠 VM,且桌面应用无法自行唤醒它。可用
railway ca wake <agent 名称>先唤醒。
三大桌面端应用:CLI 分别替你做了什么?
三个应用的连接机制各不相同,Railway CLI 都已封装好细节:
Claude Code Desktop:自动写入 SSH 与 sshConfigs
railway ca desktop --claude 会向 ~/.ssh/config 写入 OpenSSH 配置块(别名 railway-agent-<name>),并在 Claude 本地配置中写入对应的 sshConfigs 条目,全程无需手工敲 SSH 命令。
源码参考:src/commands/cloud_agent/desktop.rs
Codex Desktop:声明式导入远程连接
railway ca desktop --codex 等价于 railway code --codex desktop-only,CLI 依次完成:
- 在云端 VM 上启动(或复用)带认证的 Codex App Server,并验证其公网端点
- 在
~/.ssh/config注册 SSH 主机(别名railway-<name>) - 把连接与远程项目声明式写入
~/.codex/codex-app/config.json,已有配置自动备份为config.json.railway-backup
Codex Desktop 会在下次启动时读取该文件完成导入,因此 CLI 不会主动启动应用——重启 Codex 后,云端项目即出现在侧边栏。
实现位于 codex_config.rs,负责定位并合并 Desktop 配置文件。
OpenCode Desktop:自动启动带密码的远程服务器
OpenCode 走的是 HTTPS 服务器路线:
- CLI 在云端 VM 上后台启动带密码的
opencode serve进程(默认 code 端口 4096) - 检查其公网 HTTPS 端点
- 将服务器 URL、用户名、密码、默认服务器与远程项目写入 OpenCode Desktop 的设置(兼容 JSON 设置与 SQLite 状态两种存储,并自动备份原配置)
注意两点:
- 云端镜像内置 OpenCode V2;旧镜像(OpenCode 1.x)无法运行会话,提示报错时用
railway code --opencode --new新建 Agent - 配置完成后可能需要重启 OpenCode Desktop 才能加载新连接
核心逻辑见 opencode_config.rs。
常用进阶参数与日常命令
桌面端配置常用参数一览
| 参数 | 作用 |
|---|---|
--agent <名称或ID> |
指向已有云端 VM(默认复用当前环境的 VM,没有则创建) |
--new |
始终创建一个全新 VM |
--dir /path |
指定会话打开的远程目录(默认 /app) |
--dry-run |
预览将修改的本地文件,不实际执行 |
--remove |
移除本命令写入的桌面端配置(OpenCode 还会停止其服务器进程) |
查看、重连与休眠管理
railway code get-config my-box # 查看已保存的连接配置(离线可用,无需登录)
railway ca sleep my-box # 停止算力计费
railway code --opencode connect my-box # 用本地客户端重连远程服务器
VM 休眠后,重新执行一次 setup 命令即可唤醒并复用已有配置(凭据、项目都会保留)。完整的云端 Agent 命令说明见官方文档:docs/cloud-agents.md。
常见问题快速排查
| 现象 | 原因与解决方法 |
|---|---|
| 桌面应用连不上 | VM 已休眠,先用 railway ca wake <名称> 唤醒 |
| OpenCode 提示"not V2" | 镜像过旧,执行 railway code --opencode --new 新建 Agent |
| 配置了但应用里没变化 | setup 只写配置、不启动应用,请重启桌面应用加载 |
| code 端口被占用导致 OpenCode 失败 | 停掉占用端口的进程,或改用 --new 创建新 VM |
| 想离线核对连接信息 | 使用 railway code get-config,它读取本地快照,不依赖网络 |
相关源码与文档路径
| 模块 | 路径 |
|---|---|
| 桌面端对接主命令 | src/commands/cloud_agent/desktop.rs |
| Codex Desktop 配置导入 | src/commands/cloud_agent/desktop/codex_config.rs |
| OpenCode Desktop 配置存储 | src/commands/cloud_agent/desktop/opencode_config.rs |
| Codex 本地客户端 | src/commands/cloud_agent/codex/local.rs |
| OpenCode 凭据导入 | src/commands/cloud_agent/opencode/auth.rs |
| 云端 Agent 命令指南 | docs/cloud-agents.md |
至此,Railway CLI 的桌面端对接配置全部完成:一条命令把 AI 编程搬上云端,本地桌面应用只负责交互,用完 railway ca sleep 即可停止计费。