Railway CLI

Railway CLI

Railway CLI 可让你通过命令行与 Railway 项目交互。请阅读 CLI 文档。

安装

一步安装 Railway CLI 并配置 Agent 支持（适用于 macOS、Linux，以及通过 WSL 使用的 Windows）：

bash <(curl -fsSL railway.com/install.sh) --agents -y

此操作会将 CLI 安装到 ~/.railway/bin，并运行 railway setup agent，为检测到的 Agent 工具进行配置。

如需安装 CLI 但不配置 Agent：

bash <(curl -fsSL railway.com/install.sh) -y

卸载 CLI：

bash <(curl -fsSL cli.new) -r

CLI 文档中还提供其他安装方式：Homebrew、npm、Scoop、预构建二进制文件和从源码构建。

IaC 部分所有权

使用 railway config partials list 查找命名部分及其拥有的资源地址。railway config partials release NAME 会清除某个部分的所有权，而 railway config partials transfer FROM TO 会将其转移到另一个部分。添加多个 --resource ADDRESS 选项以选择资源；省略这些选项则会应用于整个源部分。使用 --dry-run 预览确切地址。

这些命令无需原始创作文件即可运行，且只会更改所有权元数据。有关确认、JSON/CI 用法以及恢复为整个项目管理的信息，请参阅 IaC 指南。

身份验证

使用 CLI 前，请先通过 Railway 账户进行身份验证：

railway login

对于没有浏览器的环境（例如 SSH 会话），请使用无浏览器登录：

railway login --browserless

令牌

对于 CI/CD 流水线，请设置环境变量，而不要使用交互式登录：

• 项目令牌：设置 RAILWAY_TOKEN，用于项目级操作。
• 账户或工作区令牌：设置 RAILWAY_API_TOKEN，用于账户级或工作区级操作。

RAILWAY_TOKEN=xxx railway up

更多信息请参阅令牌。

Agent 设置

为 AI 编码工具配置 Railway Agent 支持：

railway setup agent -y

此操作会安装 Railway 技能，并为检测到的工具（例如 Claude Code、Cursor、Codex、OpenCode、GitHub Copilot、Factory Droid、Pi 和 Antigravity）配置远程 Railway MCP 服务（通过 railway mcp proxy 连接 mcp.railway.com，并使用 CLI 登录信息进行身份验证）。

如果只需要设置其中一部分，请使用对应的命令：

railway mcp install --agent cursor
railway skills --agent claude-code

启用自动更新后，由 CLI 管理的技能会在后台静默更新，包括 CLI 版本变更后的首次常规命令（无论是通过 railway upgrade 还是包管理器升级）。本地修改或删除的技能会被跳过，用户添加的文件会保留。请重启编码工具以加载已更新的技能。使用 railway skills update 查看跳过的更新，或添加 --force 明确覆盖本地更改。

railway autoupdate disable（或 RAILWAY_NO_AUTO_UPDATE=1）会禁用 CLI 和技能的自动更新及其更新通知。仍可使用 railway upgrade、railway check-updates 和 railway skills update 命令。

选择使用本地的 GraphQL 驱动 MCP 服务：

railway setup agent -y --local
# or
railway mcp install --local --agent cursor

有关 VM 启动、重新连接、Desktop 设置和身份验证的详细信息，请参阅 cloud-agent 命令指南。

更新进度和状态

railway upgrade 会将 CLI 安装和托管技能同步作为一个流程展示。工作完成后，各阶段会依次推进，最终摘要会说明新版本是否已生效，或将在下次执行命令时使用。即使禁用了自动更新，此显式命令也会同步托管技能。

自动发现和下载会在后台静默运行。新 CLI 生效且技能同步完成后，交互式命令会为每个 CLI 版本显示一条完成回执。保留的本地修改会以中立方式报告；技能同步失败会与 CLI 安装成功分开报告。使用 JSON、管道输出、帮助和版本输出的命令不会显示或消耗回执。需要手动升级的安装方式则会在每个版本发布时显示一条可用性通知。

运行 railway autoupdate status，查看正在运行的版本和记录的已安装版本、已暂存或正在进行的 CLI 更新、技能同步结果以及非托管技能。使用 railway skills update 查看详细的技能结果或重试同步。

云端 Agent 启动默认行为

每次使用 --codex、--opencode、--claude、--grok 或 --railway 调用 railway code，都会创建一个新的 VM。这也适用于 remote、Codex desktop-only，以及 -- 后的 harness 参数；--new 可用但并非必需。对于现有后端，请使用 connect [agent]；对于显式服务器设置，请使用 --agent <name-or-id>；对于 shell，请使用 railway ca ssh <agent>。裸启动以及共享 CA/Desktop 配置仍保留现有的目标选择行为。

本地 Railway TUI 原型

railway code --railway                       # new VM, local TUI on its public agent endpoint
railway code --railway --agent my-box --dir /app/project
railway code --railway connect my-box        # connect to an existing VM; wake it if asleep
railway code --railway remote                # run the TUI on a new VM over SSH
railway code --railway --connection-json     # setup and verify, without opening a TUI
railway code get-config my-box               # replay saved connection details

railway code --railway 会创建新的 VM，并在 Railway CA 会话窗格中打开客户端，使用与 Codex 和 OpenCode 相同的设置进度和终端框架。connect 仅用于重用现有 VM；正常启动无需使用它。设置期间使用 --agent my-box 可指定目标 VM。会话侧边栏会列出并恢复守护进程的原生会话。

本地 railway-agent-tui 通过 WebSocket 连接到现有的 CloudAgent.agentWsUrl（wss://<agent-domain>/agent）。它与平台监督的 railway-agent serve 守护进程以及持久会话共用基础设施，这些会话也供控制面板聊天和 VM 的 TUI 使用。创建或唤醒 VM 会启动该守护进程；启动器会先通过 get_state 验证公共控制协议，然后再打开 TUI。它不会启动第二个守护进程，也不需要 code-* 域名。--dir 用于选择远程项目，默认为 /app；如果本地保存了目录，重新连接时会使用该目录。不指定名称时，将使用常规云端 Agent 选择方式。没有 Agent 端点的旧版 VM 会报告此限制。

网关会在每次 WebSocket 升级时使用来自 cloudAgentHarnessToken 的五分钟 JWT。每次 TUI 连接（包括重新连接和切换会话）时，一个小型本地 WebSocket 桥接程序都会签发新令牌。这是一条公共 WSS 数据通道，不使用 SSH 隧道。本地桥接程序需要自己的随机能力令牌；TUI 退出时，桥接程序及其连接都会关闭。升级令牌过期不会中断正在进行的对话。过期的网关令牌既不会保存在 get-config 中，也不会传递给 TUI。模型凭据和工具执行仍留在 VM 上。

每次本地启动、重新连接和 --connection-json 调用都会检查公共 agent-releases 仓库中的最新稳定版本。缺少客户端或客户端版本过旧时，会自动将其安装到 ~/.railway/runtimes/railway-tui/<version>/，并将捆绑的守护进程放在 TUI 旁边。已安装的客户端与最新版本一致时会重复使用。替换任何文件前，都会根据发布资源的 SHA-256 摘要校验下载内容；下载失败不会影响之前安装的版本。客户端需要支持 attach 的版本（v0.1.15 或更高版本）；服务器版本由 VM 镜像提供。发布内容必须包含适用于你平台的资源；Windows 用户需要使用 WSL 或 remote。

TUI 会在 CA 框架内打开，只需按一个按键即可调出会话侧边栏。--connection-json 会返回公共 URL、远程目录、客户端版本和令牌签发元数据，不包含凭据。使用 get-config 中的重新连接命令即可再次打开。显式指定 remote 以及透传的 harness 参数仍会沿用由 VM 托管的行为。

编码后端和应用端点

code-* 端点是可选项，仅在创建 VM 时配置。 普通云端 Agent 默认不会请求该端点。 创建 VM 时，托管的 Codex/OpenCode 客户端会自动请求该端点：

railway code --codex --new
railway code --opencode --new

# Explicitly request the endpoint on a plain cloud agent:
railway ca create my-box --code-endpoint

# Choose a custom port instead of the default 4096:
railway code --opencode --new --code-port 5000
railway ca create my-box --code-port 5000

OpenCode Desktop 设置也会请求该端点。仅使用 SSH 的会话不需要代码端点。API 使用可选的 CloudAgentCreateInput.codeEndpoint 对象： {} 表示选择端口 4096，{ "port": 5000 } 表示选择自定义端口，不提供该对象则会禁用端点。端口必须在 1024-65535 范围内，且不能是应用端口 8080 或网关端口 8790。API 会根据该配置注入 RAILWAY_CODE_PORT，FactoryVM 会注入 RAILWAY_PUBLIC_DOMAIN_<port>。调用方和引导变量无法覆盖 RAILWAY_CODE_PORT，也不能通过设置该变量来配置路由。

带有 code-* 域名的云端 Agent 会开放配置的端口，供托管的 Codex 或 OpenCode 服务使用。两个启动器都会使用此端点，将 app-* 域名和端口 8080 留给你的应用使用。代码端口一次只能运行一个托管后端；如果另一个进程正在使用该端口，设置时会报告冲突。OpenCode 的服务 URL 也会提供 Web UI，并显示打印出的凭据。

没有代码端点的 Agent 会继续使用端口 8080 运行托管后端。这是在创建时配置的：在现有 VM 内设置环境变量或重新连接都不会附加域名。休眠和唤醒会保留已选择的路由。正在运行的托管服务会继续使用当前端点。重启时，服务会使用 VM 显式配置的代码端口；没有该配置的旧 VM 会保留已保存的端口。已配置的代码端点在其域名不可用时绝不会回退到应用域名。

使用检查点添加或更改端点

使用现有的 cloudAgentCheckpointCreate mutation 捕获源 VM，并轮询 cloudAgentCheckpoint，直到其状态为 SUCCEEDED。然后创建新的 VM：

railway ca create restored-box --from-checkpoint <checkpoint-id> --code-endpoint
# Or select a custom port:
railway ca create restored-box --from-checkpoint <checkpoint-id> --code-port 5000
railway code --opencode --agent restored-box

对应的 API 请求如下：

mutation {
  cloudAgentCreate(input: {
    environmentId: "<same-environment-id>"
    name: "restored-box"
    cloudAgentCheckpointId: "<checkpoint-id>"
    codeEndpoint: { port: 5000 }
  }) {
    id
    name
    domains { prefix port domain }
  }
}

磁盘会还原到一台具有独立身份和域名的新 VM 中。进程不会保留。已保存的 Codex/OpenCode 凭据和项目目录会继续使用，而启动器会采用新 VM 配置的端点。源 VM 的变量不会自动复制；请传入所需变量或使用引导程序。检查点和引导程序创建操作都需要显式选择启用。单独的分叉操作会保留源 VM 的代码端点和端口。

OpenCode 客户端和远程服务

在云端 Agent 上准备经过身份验证的服务，然后打开本地客户端：

railway code --opencode
railway code --opencode --name my-box

OpenCode 指 OpenCode V2：云端 Agent 镜像内置官方 V2 opencode，CLI 会直接启动它。不再支持 OpenCode 1，之前的 --opencode2 版本标志也已移除。由旧版镜像创建、其 opencode 仍为 1.x 的 Agent 无法运行 OpenCode 会话；启动或恢复会话时会显示

This cloud agent is on an older image whose OpenCode is not V2. Create a new agent with railway code --opencode --new.

较早版本的 CLI 将偏好设置、已保存的连接和 VM 历史记录为 opencode2，现在会将其作为 OpenCode 读取。

如果兼容的 OpenCode Desktop 安装中已有设置文件或桌面数据库，Railway 会自动在其中保存服务 URL、凭据、默认服务和项目。最终输出会确认配置已更新；请在 Desktop 的服务器选择器中打开 Railway: <agent-name>。支持 JSON 设置和 SQLite renderer 状态，并会备份之前的设置。你可能需要重启 OpenCode Desktop 才能加载更新后的配置。配置失败不会导致操作中断，并会与连接详情一并报告；重新运行命令即可重试。 CLI 还会打印服务器 URL、用户名、密码和项目目录，供手动配置，并提供 Railway 重连命令： railway code --opencode connect <agent>。 匹配的本地终端客户端会在 Railway CA 界面内自动启动。交互式启动时，加载面板会显示配置过程和客户端设置；如果缺少客户端，则会静默安装。使用 connect 重连时，如果缺少客户端，会先询问是否安装；拒绝后，服务器会继续运行，并打印连接详情。使用 railway code get-config 查看已保存的连接和 Desktop 设置。设置失败时，诊断输出会保持可见。 系统会验证本地客户端与远程服务器的协议和版本是否兼容。

新建的 OpenCode Agent 命名为 oc-railg-3ed；Codex 使用 codex-railg-3ed，Claude Code 使用 cc-railg-3ed，Grok 使用 grok-railg-3ed，Railway 使用 rlwy-railg-3ed：名称由项目名称的前五个字母或数字（转为小写）加上随机三字符后缀组成。使用默认云 Agent 项目时，标签会改用本地仓库或目录的名称。 创建前会检查是否已存在同名项；--name 可覆盖生成的名称。remote 和 railway ca desktop 也使用相同的命名规则。

使用本地客户端连接到现有服务器：

railway code --opencode connect
railway code --opencode connect my-box

connect 会发现你拥有的 Agent 上正在运行的 OpenCode 服务器。此前由 CLI 以 OpenCode 1 启动的服务器不会被发现或重新连接；请使用 railway code --opencode --new 创建新 Agent。 如果只有一个匹配项，则直接连接；如果有多个匹配项，则会显示 workspace/project/agent 选择器。输入名称或 ID 可直接指定 Agent，也可以唤醒已保存的服务器。连接时还会更新兼容的 Desktop 安装配置。 连接操作不会创建新 Agent，也不会在无关的设备上安装服务器。 在非交互式终端中，CLI 仍会尝试配置 Desktop 并打印连接详情，而不会提示、安装软件或启动终端客户端；有多个匹配项时，必须指定名称或 ID。

在 Railway CA 中同时于云 Agent 内运行客户端和服务器：

railway code --opencode remote

Harness 启动会创建新的 VM；--agent <name-or-id> 用于指定现有 Agent。 对于本地客户端设置，--dir 用于选择远程项目目录（默认为 /app）。OpenCode V2 使用其服务器的启动目录，因此切换目录需要创建新 Agent。设置过程与 Desktop 使用相同的生成凭据、HTTPS 检查、提供商登录行为、技能和 MCP 同步方式。系统会将设置保存到检测到的 Desktop 安装中，并打印出来供手动输入。 正在运行的服务器及其密码会被复用。完成后使用 railway ca sleep <name>。

将 Harness 专用参数放在 -- 之后，例如： railway code --opencode -- run --standalone "explain this project"。

云 Agent 引导配置

将已配置并运行的云 Agent 保存为可复用的启动配置：

railway ca bootstrap save dev --agent configured-vm
railway ca bootstrap list
railway ca bootstrap save updated --agent another-vm --default
railway ca bootstrap default dev

railway code --codex                         # uses your local environment default
railway code --codex --bootstrap updated     # selects a named bootstrap
railway code --codex --no-bootstrap          # starts with a clean VM
railway ca create scratch --bootstrap dev

在 railway ca 启动器中，点击 Target Project 下方的引导配置行，或按 Option+B。如果已有引导配置，该行会显示 Select Bootstrap，并打开一个紧凑列表，每个引导配置占一行。选择一个引导配置，将其设为本地默认项；选择 Create New 创建引导配置；或选择 No Default，以便今后启动云 Agent 时不使用引导配置。在侧边栏中选择项目或环境，然后按 b 打开同一列表；列表会默认定位到末尾的 Create New，并使用该行对应的环境，而不会更改启动器的提示词目标。 在树形列表或引导配置列表中按 n，为新 VM选择 Agent。 选择器包含 ChatGPT Codex、Use bootstrap 复选框，以及 Option+B 快捷键，可使用项目默认引导配置、选择其他引导配置，或从头开始。 这些启动选项不会更改已保存的默认配置。在 VM、其会话或其获得焦点的终端中按 Option+N，即可打开相同的新 VM选择器，并选择引导配置和项目。选择器会预先选中当前 VM 的项目和环境；启动后会创建一台全新的机器。

失败的捕获不会显示在 TUI 引导配置选择器中。已就绪的引导配置和仍在保存的捕获会显示在 No Default 之前，Create New 则始终位于最后。

应用快捷键使用 Option（其他键盘上为 Alt）：Option+B 打开引导配置，Option+T 选择目标项目，Option+O 打开 SSH shell。 Option+Esc 可将键盘焦点返回树形列表。Ctrl+B、Ctrl+T 和 Ctrl+] 仍为兼容性快捷键；Ctrl+C 保持标准的中断行为。

在现有 VM 上按 Enter，可重新打开其主要编码 Agent 终端。 CLI 会使用该 VM 的配置和会话历史来识别 Agent； 如果无法识别，则会请你选择，且不会使用或更改默认配置。 点击终端窗格只会更改焦点；要连接到尚未打开的线程， 仍需按 Enter 或双击该线程。

拖动侧边栏与终端之间的边缘可调整侧边栏大小。线程 文本和水平分隔线会占用全部可用宽度。侧边栏使用纯深灰色背景，右侧边框标示其凸起边缘。 松开鼠标时会保存宽度，下次打开 CLI 时会恢复该宽度。终端变窄时，显示宽度会暂时受限，但不会 更改该首选项。拖动过程中按 Escape 可取消操作。

Create bootstrap 表单始终在终端窗格中居中显示。表单包含带边框的 名称字段、可选的仓库字段（owner/repo 或 HTTPS URL），以及编码 Agent 字段，另有一个 Make default 复选框。点击字段和 Create bootstrap 按钮，或使用 Tab/Shift+Tab 在字段间移动，使用左/右键编辑文本或选择 Agent，并按 Enter 激活控件。页脚会显示可用快捷键。

创建过程中，CLI 会通过紧凑的进度卡片显示当前阶段，同时创建一台临时 VM，复制所选运行环境中可用的本地登录信息、 技能、MCP 配置和设置，可选地将仓库克隆到 /app，并保存检查点。由 Railway 管理的现有运行环境设置优先于导入的设置。私有仓库使用 VM 的 GitHub 访问权限。捕获就绪后，CLI 会应用你的默认选择并删除设置用 VM。配置或捕获失败时会尝试清理，并保留之前的默认配置。清理失败时会显示尚存 VM 的名称。

完成后，启动器会返回到未更改的提示符。从侧边栏创建时会返回树形列表。启动真实 VM 时，也只会在固定宽度的面板中显示当前准备阶段。 高亮一个正在运行的 VM，然后按 b，即可在 TUI 中打开“名称”表单。保存时会捕获其磁盘，不会停止、删除或断开源 VM。尚无默认项时，“设为默认”会默认勾选；已有默认项时则默认不勾选，你可以在创建前更改。磁盘捕获失败后，即使名称已被保留，该引导项也无法使用。从同一 VM 使用相同名称重试，即可复用失败的捕获记录；如果捕获仍在保存，TUI 会等待该捕获完成，而不会重复提交。此表单无法覆盖已就绪的引导项，也无法覆盖从其他 VM 捕获且使用相同名称的引导项。服务端快照超时会连同失败原因一起报告，只有捕获成功后才会更改默认项。扁平命令 railway ca bootstrap save 仍支持为现有名称保存新版本，并通过 --default 将其设为默认项。更改默认项会等待捕获成功。

引导项在同一项目／环境对内共享。默认项选择仅存储在你本地的 Railway CLI 配置中，并以 Railway 主机和环境 ID 为键（环境 ID 也用于标识项目）。这不会更改控制面板中的默认项，也不会更改团队成员的默认项。如果没有本地默认项，新 VM 会以干净状态启动。显式指定的 --project 和 --environment 标志优先级最高，其次是目录的 Railway 链接，然后是已保存的 CA 项目首选项。引导项名称仅在该环境内解析。list、save 和 default 支持 --json；save 接受用于存储引导项变量的 --env-file 和 --variable。启动时指定的变量会覆盖已存储的引导项变量。

只有新 VM 会使用引导项。连接到现有 VM 时会保留其磁盘。已删除、仍在保存或状态降级的本地默认项会导致错误；--no-bootstrap 可显式绕过默认项。ca create --from-checkpoint 也会绕过默认项，且不能与引导项标志同时使用。

快照包含文件和已安装的工具。使用幂等且非阻塞的 /etc/railway/bootstrap/startup.sh，以便在启动／唤醒时重启本地服务；使用 /etc/railway/bootstrap/AGENTS.md 编写设置说明。

使用本地终端或桌面客户端运行 Codex

在你的计算机上运行原生 Codex 终端 UI，并连接到持久化 Railway 云端 Agent 上的 Codex App Server：

railway code --codex
railway code --codex --agent my-box --dir /app
railway code --codex connect my-box
railway code --codex connect

新的 Codex Agent 使用与 OpenCode 相同的命名规则，并添加 codex- 前缀（例如 codex-railg-3ed）。生成的名称可用于 connect、get-config 和云端 Agent 生命周期命令；--name 可设置自定义名称。

仅使用桌面应用的工作流：

railway code --codex desktop-only
railway code --codex desktop-only --agent my-box --dir /app

此操作会准备 VM、启动或复用已认证的后端 App Server、验证其公共端点、注册 SSH，并保存远程项目，供 Codex Desktop 在下次启动时导入。随后操作会退出，但后端仍会继续运行。它绝不会提示你安装或启动本地终端客户端。结果面板会显示后端凭据、SSH 配置文件位置、桌面项目名称，以及用于重新连接或获取配置的命令。

终端设置会带上你可用的本地 Codex 登录状态和已配置的技能／MCP 同步设置，在已配置的代码端口上启动 App Server（默认值为 4096；对于旧版连接则为 8080），验证其公共 WebSocket 握手，并在 Railway CA 框架内自动启动本地客户端。工具、文件和对话线程都存储在 VM 上。在 Codex 中使用 /resume，或在 CA 侧边栏中选择一段对话，即可重新打开远程线程。connect 会发现正在运行的 Codex 服务；如果显式指定 Agent，也会在需要时唤醒并重启先前配置的服务。点击窗格中的网页链接即可在浏览器中打开，包括缩短后的 URL 和带标签的链接。 远程终端客户端在 ~/.railway/codex-client/<backend-id>/ 下使用独立且持久的 CODEX_HOME。VM 负责管理自己的工具和会话；本地专用的 MCP 服务、插件和钩子不得参与远程启动。这也能确保终端的繁忙指示器和取消状态与后端保持一致。按下 Ctrl+C 会中断正在进行的工作；终端空闲时按下 Ctrl+C 则会退出；在空提示符下按下 Ctrl+D，即使仍在启动过程中也会断开连接。

终端连接通过 Agent 的公共域名使用 wss://。持有者令牌通过环境变量传递给本地客户端。远程服务的令牌、PID、版本、目录和日志位于 ~/.railway/codex/ 下。在明确选择的 Agent 上进行设置时，若版本未变，则会沿用其令牌和运行正常的服务。若端口已被占用，或运行中的项目目录不同，则需要使用其他 Agent。

设置和 connect 也会在 ~/.ssh/config 中将 Agent 的 SSH 主机注册并验证为 railway-<agent-name>，使用与 railway ca desktop --codex 相同的注册方式。重新连接时，会在 SSH 和 Codex Desktop 的已保存配置中，将先前的默认项 railway-agent-<agent-name> 升级。它们会在后台将连接和远程项目合并到 ~/.codex/codex-app/config.json（如果已设置 $CODEX_HOME，则为 $CODEX_HOME/codex-app/config.json）。设置绝不会启动或激活 Codex Desktop；下次启动应用时，它会导入已保存的配置。 在 Codex Desktop 的项目侧边栏中找到 Railway: <name>。现有的自定义 SSH 别名和项目标签会保留。connect 会导入服务的实际工作目录。你可以在终端和 Desktop 中使用同一台 VM。

服务设置会在替换正在运行的进程前，在后台检查 npm 上最新的官方 Codex 版本，并验证已通过身份验证的 App Server。版本缓存位于 ~/.railway/runtimes/codex-server/<version>/ 下，更新诊断信息位于 ~/.railway/codex/update.log。更新失败时会保留现有服务。connect 会保留运行中服务的版本；重启已停止的服务时会检查更新。终端模式会使用 npm，在 ~/.railway/runtimes/codex-client/<version>/ 下自动查找或安装完全匹配的本地 @openai/codex 版本。

对于脚本，--connection-json 会返回一个 JSON 对象，其中包含 schemaVersion、Agent 身份，以及连接的 url、token、directory、version 和 reused。进度信息会输出到 stderr。

railway code --codex --connection-json connect my-box
railway code --codex remote             # run the UI inside Railway CA
railway code --codex -- exec "run tests" # execute inside the VM

关闭本地客户端不会停止服务。使用 railway ca sleep my-box 停止计算资源，然后使用 railway code --codex connect my-box 唤醒并重新连接。Codex 目前将其远程 App Server 传输标记为实验性功能。

本地连接会启用自动命令权限。Codex 会在禁用审批的情况下，以完整 VM 访问权限启动、恢复和分叉对话；OpenCode 客户端则会使用 --auto 运行。重新连接时也会应用这些设置。Codex 会记录对远程项目目录的信任，包括恢复会话时选择的不同仓库。

首次启动 OpenCode 时会打开原生主页／启动画面。提交提示词后才会创建对话；带有初始提示词启动时，则会直接进入该对话。连接详情会在启动前显示，并在本地客户端退出后再次显示。

云端 Agent 对话历史

在 railway ca 和 railway code 界面中，展开左侧列表中的云端 Agent，即可浏览其 Claude、Grok、Codex 和 OpenCode 对话。 选择标题并按 Enter，即可重新打开对应的对话线程。保存的对话在线程终端退出后仍然可用；打开列表不会为这些对话启动客户端。新的 harness 面板会以 New Thread 开始，然后采用 harness 生成的标题。[S] 专用于直接 VM Shell；harness 控制台、服务进程和配置命令不会生成会话行。 对话元数据会在本地缓存，重启后仍然保留，休眠的 VM 也不例外。发现操作会在启动时、选择或展开运行中的机器时、按 Option+F / Alt+F 显示侧边栏时，以及手动刷新时执行。已加载的行、行顺序、展开状态和所选对话都会保留。 机器的状态图标始终表示该机器的状态。

在任何位置（包括会话内部）使用 Option+R / Alt+R 刷新 Agent 和可见对话。 这也会查找未打开项目中的 Agent；没有单独的发现快捷键。侧边栏获得焦点时，按普通的 r 会刷新所选环境。

在已保存的对话上按 x / X，即可从对应 harness 中删除该对话。后台执行原生删除时，该行会立即消失；如果删除失败，该行会恢复并显示错误。这会删除已保存的对话，而不仅仅是断开其终端。草稿 New Thread 面板只会关闭，[S] Shell 行则仍保留结束会话操作。

系统不会定期轮询账户或 VM 历史记录。Codex 和 OpenCode 的标题与活动状态变化来自其现有的原生客户端连接。活动 SSH harness 面板的输出会触发一次合并读取，以获取 Railway 存储的会话报告，不会再打开其他 VM 连接。空闲的侧边栏不会自行刷新历史记录；在其他位置发生的更改会在下次手动刷新时显示。

Claude 和 Grok 历史记录会通过 SSH 直接从 VM 中发现，包括在 Railway 启动器之外启动的对话。Claude 使用固定版本的官方 Agent SDK；首次发现历史记录时会在 VM 上自动缓存该 SDK。Grok 使用其已保存的 summary.json 元数据。发现操作会遵循 CLAUDE_CONFIG_DIR 和 GROK_HOME，并过滤隐藏的子 Agent 和空的启动记录。临时发现失败时，会保留之前加载的行。Codex 和 OpenCode 也会公开其 VM 本地元数据索引，因此无需本地保存的后端连接即可查看其历史记录。早期 CLI 版本以 opencode2 保存的 OpenCode 历史记录会列为 OpenCode。

选择 Claude 或 Grok 对话线程时，如果存在已验证的活动终端，则会重新连接到该终端；否则，会根据记录的项目和配置目录恢复其原生 UI。Claude 后台任务使用 claude attach。实时元数据和钩子会更新线程状态，并将原生面板关联到其对话 ID。云端 VM 上的 Grok 启动和恢复对话会使用 --trust --always-approve，跳过文件夹信任和工具审批提示。下次执行 railway code 配置后，SSH 自动启动也会使用相同标志；本地设置不会更改。 原生 Codex 和 OpenCode 客户端操作会通过逐面板的身份验证桥接，更新面板对应的确切对话标识。 历史记录属于保存它的 VM；休眠的 Agent 需要先唤醒，再打开其对话线程。

SSH Shell 和恢复对话

railway ca ssh my-box                 # open a login shell
railway ca ssh my-box --session       # attach to or start a durable session
railway ca ssh my-box --session name  # attach to a named session
railway ca ssh my-box --resume        # resume the latest Claude conversation

普通 SSH 会绕过 harness 自动启动。终端结束后打开持久会话时，交互式用户可以选择最近的 Claude 对话。 在 CA 界面中，按 Option+O / Alt+O 可在所选 VM 上打开 Shell，并在退出时返回界面。侧边栏的 c 操作会复制 Shell 命令。

检索已保存的连接配置

railway code get-config                  # most recently saved connection
railway code get-config my-box           # a specific agent by name
railway code get-config codex-railg-3ed   # generated names work too
railway code get-config <agent-id>        # use an ID if names are ambiguous
railway code get-config my-box --json

Codex 终端设置、connect 和 desktop-only（包括其 railway ca desktop --codex 别名）会保存已验证的后端连接和 桌面端配置结果。OpenCode 设置和重新连接也会保存其服务详情；普通云端终端启动会保存 SSH 详情。

get-config 可在任何目录中使用本地快照，无需登录、 访问网络、唤醒 VM、启动客户端或应用桌面端配置。 其人类可读输出使用与创建和重新连接相同的简洁结果面板。 --json 包含已保存的 Agent/SSH 元数据和特定运行环境的 codex 或 opencode 对象，其中包括凭据和桌面端状态。这些是已保存的 详情，而非实时运行状况检查；重新运行设置/连接操作可刷新这些信息。

Railway 会在 ~/.railway/code-configs.json 中保留每个 Agent 的最新快照， 并继续写入 ~/.railway/last-code-config.json，以兼容现有 CLI 版本。 首次写入归档时，会保留已有的最新快照。按名称查询需要此电脑上之前保存过的连接；未知名称会报错，重复名称则会列出其 ID。 这些文件设为私有，并在锁定状态下以原子方式更新。railway logout 会删除这两个已保存配置文件。

桌面应用中的云端 Agent

为 Claude Code Desktop、Codex 或 OpenCode Desktop 准备云端 Agent：

railway ca desktop --claude
railway ca desktop --codex
railway ca desktop --opencode --agent my-box
railway ca desktop --opencode --new

仅选择 Codex 时，railway ca desktop --codex 是 railway code --codex desktop-only 的兼容别名。它使用相同的后端启动和 桌面端导入流程，并传递 --agent、--new、--dir、项目/环境 以及其 SSH 别名/配置/验证选项。现有的 --dry-run、 --remove 和多应用设置命令仍可使用。

可以组合应用标志，为同一个 Agent 准备多个应用。设置会沿用可用的本地登录信息，应用你的技能/MCP 同步偏好， 并写入 Agent 的 SSH 配置。--dry-run 会预览本地文件，但不会创建或唤醒 Agent，也不会启动连接。必要时会复用并唤醒现有 Agent；如果目标环境中不存在 Agent，设置会创建一个。即使组合多个应用标志，--new 也始终会创建全新的 Agent。它不能与 --agent 或 --remove 一起使用。

Codex 设置会在后台使用 Codex Desktop 的第 1 版应用配置注册 SSH 主机和命名远程项目，不会启动或激活应用。Codex Desktop 会在下次启动时导入配置。 现有连接和重试/超时偏好会予以保留；已更改的配置会备份到 config.json.railway-backup。 --dry-run 会预览合并后的配置。--remove 会移除 SSH 区块和该别名的导入声明；请在 Codex 中移除已导入的连接和项目，因为其导入机制不会删除它们。

OpenCode Desktop 会直接连接到 Agent 现有的 HTTPS 地址。 CLI 会在后台启动受密码保护的 opencode serve ，并在配置的代码端口上运行（默认为 4096，旧版连接为 8080），检查其公开端点，并将 URL、 用户名、密码、默认服务和远程项目保存到桌面端设置中。 桌面端兼容性根据其捆绑客户端版本单独判定，与发布渠道无关；在兼容时优先使用稳定版 OpenCode (ai.opencode.desktop)。 支持 JSON 服务设置和 SQLite 渲染器状态；仅含草稿的数据库不会改变设置的保存位置。 服务使用镜像内官方的 OpenCode V2 opencode；CLI 不会在 Agent 上安装或升级 OpenCode。如果旧镜像中的 opencode 为 1.x，或版本低于已保存的服务上次运行的版本，则会拒绝运行，并提示使用 railway code --opencode --new 创建新的 Agent。终端客户端会遵循服务记录的版本，并在需要时安装到 ~/.railway/runtimes/opencode-client/<version>/。

使用 railway ca --opencode 启动终端会话。新建会话选择器中只有一个 OpenCode 选项；按 Shift+Tab 可循环切换运行环境。

设置过程还会显示连接详情，并提醒你可能需要重启 OpenCode Desktop，以加载更新后的配置。 私有 .railway-backup 文件会保留之前的设置和服务状态。 设置完成后，你可以关闭终端；无需保持本地隧道运行。

按 Cmd+B（Windows/Linux 上按 Ctrl+B）打开 Home。在 Projects 下找到 Railway: <agent-name> 和 /app（或你的 --dir），然后使用该项目的菜单 → New session。设置默认服务不会迁移现有聊天记录。OpenCode 会从本地 V2 凭据数据库（~/.local/share/opencode/opencode.db，或 $XDG_DATA_HOME/opencode/）导入每个提供商的当前账户，同时保留云端 Agent 上已配置的账户。本地 OpenCode 仍为 V1 的机器没有可复制的存储。凭据会通过 SSH 发送，导入后会删除临时传输文件。如果没有可复制的本地登录信息，请在远程服务的设置中连接提供商。

如果可用，OpenCode 会使用 Agent 的代码端点。设置过程不会接管已占用的服务端口；请停止其他进程，或使用 --new 创建新的 Agent。 重新运行 railway ca desktop --opencode --agent my-box 会复用正在运行的服务及其凭据，或在休眠唤醒或重启后重新启动服务。 远程凭据和进程状态会私密存储在 ~/.railway/desktop/opencode/ 下；启动日志位于该目录中的 server.log。

railway ca desktop --opencode --agent my-box --remove 会停止运行中的 Agent 上由工具管理的 OpenCode 进程，并移除共享 SSH 配置块以及设置过程保存的 Desktop 连接和项目。它不会唤醒休眠中的 Agent。 Agent 会保留；railway ca sleep my-box 会停止其计算资源计费。

贡献

有关如何在本地设置此代码库的信息，请参阅 CONTRIBUTING.md。

反馈

欢迎在 Central Station 分享反馈和建议。