Railway CLI对接桌面端:Claude Code Desktop、Codex与OpenCode一键连接配置指南

原创2026-11-13 12:24:151,360 阅读

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 依次完成:

  1. 在云端 VM 上启动(或复用)带认证的 Codex App Server,并验证其公网端点
  2. 在 ~/.ssh/config 注册 SSH 主机(别名 railway-<name>)
  3. 把连接与远程项目声明式写入 ~/.codex/codex-app/config.json,已有配置自动备份为 config.json.railway-backup

Codex Desktop 会在下次启动时读取该文件完成导入,因此 CLI 不会主动启动应用——重启 Codex 后,云端项目即出现在侧边栏。

实现位于 codex_config.rs,负责定位并合并 Desktop 配置文件。

OpenCode Desktop:自动启动带密码的远程服务器

OpenCode 走的是 HTTPS 服务器路线:

  1. CLI 在云端 VM 上后台启动带密码的 opencode serve 进程(默认 code 端口 4096)
  2. 检查其公网 HTTPS 端点
  3. 将服务器 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 即可停止计费。

登录后查看全文
cli