Railway Cloud Agents 与 OpenCode：连接云端开发机

OpenCode on Cloud Agents

AI 参与说明（Agent：Cursor）：本文根据 2026-10-26 读取的 Railway Cloud Agents 文档、CLI 参考、定价页与 changelog，以及 OpenCode Console、Cursor Cloud Agents 的官方页面整理。文中命令转录自这些页面；本文环境没有登录 Railway，也没有执行 railway 或 OpenCode。执行入口 Cursor Cloud。运行记录中的模型标识为 grok-4.7-high-fast；reasoning effort 未作为独立字段取得。提供方 xAI。中文经 humanizer-zh 编辑。AI 协助只表示整理过程，不代表质量保证或作者身份。能力、价格和命令以文末链接的当时页面为准。

Railway Cloud Agents 给你的是一台属于你的开发虚拟机。OpenCode 2 跑在这台机器上，本机的 Desktop 或终端只做客户端；你也可以把 OpenCode 客户端一并放进 Railway CA。用完要自己 sleep，因为断开连接不会停机，也没有 idle timeout。

这台机器不是 railway up 部署出去的 Service，也不是 OpenCode Console 的模型账单。它和 Cursor Cloud Agents、Devin 一类远程编码环境更接近：编码工具在远处的电脑上改文件、跑命令。差别在于 Railway 把这台电脑交给你长期保管，Cursor 则按一次任务来克隆仓库、开 PR，再回收虚拟机。

阅读前先看这几个词

四条线不要并成一件事

A cloud agent is a personal virtual machine. OpenCode Desktop and a local terminal client connect to an authenticated HTTPS server on that machine. Railway CA terminal sessions use SSH. Closing the client keeps the VM running. Sleeping stops its processes and compute billing while retaining files. (Cloud agents, Manage agents and sessions)

flowchart TD
  laptop["本机 OpenCode 客户端"]
  ca["Cloud Agents VM"]
  svc["Service"]
  console["OpenCode Console"]
  provider["其他模型 Provider"]
  laptop -->|"HTTPS 用户名和密码"| ca
  laptop -->|"railway up 或镜像"| svc
  ca -->|"可选：Console 模型"| console
  ca -->|"自带 Provider 登录"| provider

Cloud Agents 当前通过 Priority Boarding 提供，文档写明可能有 breaking changes。2026-08-07 的 changelog 把它作为 Beta 发布，CLI 里同时出现 railway ca 和 railway code。2026-08-21 的 changelog 补上了仪表盘里发起任务，以及 railway ca 里切换会话。2026-09-25 的 changelog 把 OpenCode 接到这台 VM 上。同周另有 ssh railway.new 的限时免费 VM，那是另一条领取流程，不是本文的 Cloud Agents。(Cloud Agents Beta，Cloud Agents Everywhere，OpenCode on Cloud Agents)

机器上有什么

镜像是 Ubuntu 开发环境。文档列出的编码工具包括 Claude Code、Codex、Grok CLI、Railway Agent 和 OpenCode 2，另外还有已登录的 Railway CLI、GitHub CLI、Git、Node.js（pnpm、yarn）、Python（uv）、mise，以及 ripgrep、jq、PostgreSQL 工具、SQLite、构建工具和 Chromium。pi、Cursor CLI、Factory Droid 也在镜像里，但要自己在 shell 里登录，它们不是 railway code 的集成启动项。会话从 /app 开始。(Cloud agents)

从本地仓库目录启动，只会带上项目上下文和符合条件的配置。本地源码不会自动上传。仓库要在 agent 上 gh repo clone，或让编码工具自己克隆。

VM 规格跟着 workspace 计划走，不能单独改。每个用户每天最多创建 25 个 agent。Enterprise 使用 Pro 的规格。(Cloud agents)

这张表是 Cloud Agents 的 VM 大小。同一文档站里 Service 的默认资源上限是另一套数字，不要拿去套这台开发机。

每台 agent 有一个公网 HTTPS 域名，对应 VM 里的端口 8080，变量名是 RAILWAY_PUBLIC_DOMAIN。sleep 和 wake 之后域名不变。OpenCode 的托管服务器占用这个端口。要在同一端口跑别的程序，先停掉 OpenCode 服务器，或另开一台 agent；setup 不会替你杀掉无关进程。生产流量应部署成 Service，不要把这台开发机的 8080 当成线上入口。(Cloud agents)

第一天：打开功能并连上 OpenCode

下面的顺序来自 Cloud agents quickstart 和 OpenCode。命令按 2026-10-26 的页面抄录，没有在本文环境里执行。

1. 在 Priority Boarding 里启用 Cloud Agents。
2. 安装或升级 Railway CLI。安装器同时会提供给编码工具用的 Railway tooling：

curl -fsSL agents.railway.com | sh
railway upgrade
railway login
railway ca setup

railway ca setup 保存默认项目、默认编码工具、skills 偏好和主题。目录已经 railway link 过时，链接优先于这个默认项目。临时改目标用 --project 和 --environment。查看已保存的选择：

railway ca setup --show

3. 本机安装 OpenCode 2。下面三种都是文档给出的官方装法。不带 /v2 的 opencode.ai/install 会装上 1.x，和 agent 上的服务器不匹配。

curl -fsSL https://opencode.ai/v2/install | bash

brew install anomalyco/tap/opencode-v2

npm install -g @opencode/cli

跳过这一步也可以。选择连接时，Railway 会提议安装终端客户端。Desktop 要先安装并至少打开一次，再跑 setup。

4. 按你要坐在哪里，只选一条连接。三条都会在 Cloud Agents 上准备 OpenCode 2 服务器。OpenCode 1.x 时期创建的 agent 不会原地升级，CLI 会拒绝在上面启动 OpenCode，需要 --new 另开一台，再把仓库克隆过去。(Troubleshoot cloud agents)

flowchart TD
  startNode["Priority Boarding 与 railway ca setup"]
  choice{"客户端放在哪"}
  desktop["railway ca desktop --opencode"]
  localTerm["railway code --opencode"]
  remote["railway code --opencode remote"]
  work["在 /app 克隆仓库并开始会话"]
  sleepNode["railway ca sleep 名称"]
  startNode --> choice
  choice --> desktop
  choice --> localTerm
  choice --> remote
  desktop --> work
  localTerm --> work
  remote --> work
  work --> sleepNode

Desktop

railway ca desktop --opencode

CLI 创建或唤醒 agent，在后台启动 OpenCode 服务器，检查带认证的 HTTPS，然后把服务器 URL、用户名、密码、默认服务器和远程项目写进 OpenCode Desktop。macOS 上，正在运行的 OpenCode 会被重启以套用设置。Windows 和 Linux 要先退出 Desktop。配置已经写入但应用没有重新打开时，手动打开即可。

开始一次云端会话：macOS 用 Cmd+B，Windows 和 Linux 用 Ctrl+B 打开 Home。在 Projects 里找到 Railway:，打开 /app，或打开你用 --dir 指定的目录，再从项目菜单里 New session。改默认服务器不会把已经打开的本地会话搬到云端。

本机终端

railway code --opencode

这条命令准备同一台云端服务器，打印 Desktop 手动填写所需的 URL、用户名、密码和目录，并给出以后重连的命令。按 Enter 启动本机 OpenCode 客户端；没有客户端时会先提议安装。拒绝或取消提示后，服务器继续跑，连接信息会再打印一次。这条路径不写 Desktop 配置。要自动写入，用上一节的 railway ca desktop --opencode。

非交互终端里，本地客户端流程只打印连接信息，不提示、不安装、也不打开客户端。多个候选时要带上名称或 ID。

客户端也在 Railway CA

railway code --opencode remote

客户端和服务器都在云端机器上，终端进入 Railway CA 里的 OpenCode。它不会启动本机客户端。--dir 只用于本机客户端的服务器目录，不能和 remote 一起用。从 Railway CA 界面打开同一类会话可以用：

railway ca --opencode

不带参数的 railway ca 是终端界面：选 agent、看会话、新建会话。项目仪表盘的 Agents 标签可以看状态、开控制台、看会话、开始工作、复制 SSH 命令或删除 agent。Desktop 连接仍要从你自己的电脑跑 railway ca desktop，由 CLI 写进已安装的应用。(Manage agents and sessions)

Herdr 是另一条把机器放进侧边栏的入口。railway ca 参考里，herdr new 接受的工具标志是 --claude、--codex、--grok、--railway，页面没有列出 --opencode。OpenCode 按上面三条路径连接。

确认自己连的是云端目录

让当前会话用终端工具执行 hostname 和 pwd，再和 Desktop 里选中的远程项目对照。模型口头回答主机名不算验证。本地旧会话会继续留在本机。(OpenCode，Troubleshoot cloud agents)

仓库还要自己放上去。把 setup 打印的名字代入：

railway ca ssh <agent-name> -- bash

在 agent 上：

cd /app
gh repo clone OWNER/REPOSITORY

OpenCode 服务器的启动目录默认是 /app。可以先停在 /app，再让它进入克隆下来的子目录。若要让服务器直接从子目录启动，在准备服务器时指定，并先在 agent 上准备好这个目录：

railway code --opencode --new --dir /app/my-project

文档给的第一项任务是有边界的：先读仓库、说明怎么运行、跑已有测试，失败先总结，再改代码。(Cloud agents quickstart)

命令按用途记

名称示例是 oc-railg-3ed：oc-、项目名里最多五位字母或数字、再加三位随机字符。已有 agent 保持原名。--name 可以在创建时覆盖。服务器发现看的是配置，不靠这个前缀。(Manage agents and sessions)

--agent 和 --new 冲突。connect 不接受 --new、--name、--variable、--env-file，也不会改服务器已经保存的目录；名称含糊时改用 ID。变量只在创建时写入，--variable 覆盖同名的 --env-file 项，不能用它们去改一台已经在跑的 agent。--keep-awake 仍被接受，但已经不需要。(railway code，Credentials and configuration)

手动把 Desktop 指到已打印的服务器时：名称用 agent 名，Server 用打印出的 HTTPS URL，用户名是 opencode，密码用 setup 生成的那一串，目录是 /app 或你选的远程目录。终端里的等价形式是：

OPENCODE_SERVER_USERNAME=opencode OPENCODE_SERVER_PASSWORD='<server-password>' opencode --server 'https://<agent-domain>'

这串密码是进入编码服务器和项目文件的凭证，和模型 Provider 的登录不是一回事。不要把它贴到公开位置。

同一台 agent 上的多个会话共用磁盘。任务可能改到同一批文件时，分开工作目录或使用 Git worktree。(Manage agents and sessions)

断开连接仍在计费

Disconnecting leaves the cloud agent running. There is no idle timeout. A running agent bills for compute while it is awake, including when no client is connected. Sleeping stops compute billing and keeps the disk. Deleting the agent removes the disk. (Manage agents and sessions，Cloud agents)

stateDiagram-v2
  [*] --> Awake: 创建
  Awake --> Awake: 断开客户端
  Awake --> Sleeping: railway ca sleep
  Sleeping --> Awake: Desktop setup 或带名称的 connect
  Awake --> [*]: railway ca delete
  Sleeping --> [*]: railway ca delete

OpenCode 从 sleep 回来时，重跑 Desktop setup，或执行带名称的 railway code --opencode connect。这两条会唤醒 VM 并重新拉起托管服务器，已保存的服务器凭证会继续用。没有一条需要你在本地维持的 SSH 隧道。railway ca wake <agent-name> 负责把机器唤醒；Claude 和 Codex 的 Desktop 要先 wake 再重连。OpenCode 仍要靠上面的 setup 或 named connect 把服务器拉起来。(OpenCode，railway ca)

账单分成两截。

VM 的 compute 按 VM 价，不按 Service 的容器价。定价页写的是：内存按使用中的量计，包含操作系统和文件系统缓存；CPU 按实际使用计；出站流量另计。虚拟机在等待工作时，内存以及后台 CPU、出站流量仍然计费。按秒计量，和计划里其余用量共用 included usage。销毁之后不再产生 compute 用量。Cloud Agents 文档把 sleep 定义为停下 compute 计费并保留磁盘，所以「等待工作仍计内存」对应的是醒着但没人连接的那段时间，不是 sleep 之后。(Pricing Plans 的 VM pricing，Manage agents and sessions)

月价是「一整月占满 1 GB，或一整月占满 1 vCPU」的算法，不是这台 agent 的固定月租。规格表里的 4 vCPU / 4 GB 是上限，账单看的是测到的使用量。Hobby 的 included usage 是每月 $5，Pro 是每月$20，超出部分另计；订阅费先抵这部分用量。Free 在定价概览里是每月 $1 的资源额度。数字以定价页当时的表格为准。(Pricing Plans，Pricing)

同一份 VM pricing 下面，给 Sandbox 的省钱建议是用 idle timeout 或做完就销毁。Cloud Agents 的管理页写的是没有 idle timeout。不要把 Sandbox 的自动休眠套到这台开发机上。忘了 sleep 的醒着的 agent 会继续产生 compute 费用。

模型费用另算。Cloud Agents 文档写：编码 Provider 的用量走你自己的 Provider 账户或 API 账单。OpenCode Console 是这条链路里的一个可选 Provider：用 /connect 选 OpenCode 的按量 Provider 并填入 API key，Console 模型从工作区预付 credits 扣费；接上你已有的 Anthropic、OpenAI 或 Bedrock 时，token 由那个 Provider 计费，Console 不扣 credits。Console 没有席位费。购买 credits 时，在金额之外另加处理费 4.6% + $0.31；页面例子是购买$50 时实付 $52.61，余额入账仍是$50。余额到零后，付费请求以 HTTP 402 失败。(Models，Providers，Billing)

Railway 定价页上还有一条 Railway Agent 的 token 行项目：它按底层模型原价转嫁，和 compute 共用 included usage。那是 railway code --railway 这条编码工具，不是 OpenCode，也不是 OpenCode Console。

三套凭据各管一件事

Signing in to a model provider does not replace the OpenCode server password. An authenticated OpenCode connection can still need a provider account before it answers a prompt. (Credentials and configuration)

CLI 会把本机 OpenCode 的 Provider 登录复制到 agent，已在 agent 上配好的凭证会保留。复制的是 Provider 凭证，不包括本机聊天、会话和 MCP 凭证。本机没有可复制的登录时，agent 仍能起来；在远程会话里连接 Provider，或在 agent 上执行：

railway ca ssh <agent-name> -- bash
opencode auth login

Provider 凭证经 SSH 传上机器。文档写明它不会放进镜像、Railway 环境变量或 SSH 命令参数。

railway ca setup 还可以打开个人 skill 同步。OpenCode 的来源目录是 ~/.config/opencode/skills，另外可选 ~/.claude/skills、~/.codex/skills、~/.grok/skills、~/.agents/skills。打包超过 2 MB 会警告，超过 10 MB 会在创建 agent 前失败。.git、node_modules 和环境文件会被排除。之后关掉同步，已经复制到 VM 的 skill 还在。

从仓库目录启动时，默认会导入符合条件的 .mcp.json。导入的名字带 user- 前缀。在 agent 上，配置里的 localhost 指的是这台云端机器。导入配置不会把每个应用的 OAuth 会话都拷过去。可在 ~/.railway/agent-prefs.json 里用 "mcp": { "enabled": false } 关掉。

和 Cursor Cloud Agents 怎么选

两者都是远程编码环境，不是应用托管。官方描述的工作单位不一样。

Cursor 的 Cloud Agent 在隔离 VM 里跑：从已连接的 Git 托管克隆仓库，在单独分支上改动，再推上去交给人。安全说明里的一次运行包括启动、准备 VM、在 VM 里执行、保存会话和产物、推分支并打开 draft PR，然后在空闲后按生命周期计时器 hibernate 再删除 VM。入口包括 Cursor Desktop、cursor.com/agents、iOS、Slack、GitHub 或 Bitbucket 上的 @cursor、Linear 和 API。(Cloud Agents，Security overview)

Railway 这边没有「任务结束就回收机器」的 idle timeout。文件留在磁盘上，直到你 delete。仓库要在机器上克隆。OpenCode 能不能开 PR，取决于你让它怎么用镜像里的 GitHub CLI，Cloud Agents 没有把「打开 draft PR」写成固定收尾。

已经在用 OpenCode，并且希望 Desktop 或终端还是原来的界面、执行落在一台醒着就持续计费的 Ubuntu 机器上时，用 Cloud Agents。希望从聊天、Issue 或 PR 评论发起任务，由对方克隆仓库、跑完并交出 draft PR，用 Cursor Cloud Agents。只想把网站或 API 发布出去，用 Service，而不是这两条。

本站另一篇把 Cursor Cloud 放进站点开发闭环的记录，讲的是任务怎么分给远程编码环境，不讲 Railway 的 VM。见文末关联阅读。

连接失败时先看哪

文档里的排查顺序可以收成几条。完整步骤在 Troubleshoot cloud agents。

• 命令或标志不存在：先 railway upgrade，再看 railway code --help 和 railway ca desktop --help。功能本身还要在 Priority Boarding 里打开。
• 创建失败后机器可能已经在跑。先 railway ca list，对已有名字重试，不要立刻再 --new。
• OpenCode 有服务器但没有模型回复：确认会话属于 Railway 那台服务器，agent 醒着且服务器在跑，远程 OpenCode 已登录 Provider 并选了模型。服务器密码不能代替 Provider 登录。
• 在 agent 上看托管服务器日志：tail -n 100 ~/.railway/desktop/opencode/server.log。日志可能含配置细节，公开转贴前先看一遍。
• Desktop 仍连着本机：回到 Railway: 下面的 /app 开 New session。railway code --opencode 只打印手动配置，不写 Desktop。
• 8080 被别的进程占用：自己停掉那个进程，或 --new 换一台。setup 不会替换无关进程。
• 项目或文件不对：railway ca setup --show 看默认值。目录上的过期 link 可能退回默认项目，用 railway link 修好。--new 是一块新磁盘。

关联阅读

• OpenCode v2 在 Cloudflare 上怎么用：使用场景与 SDK 入门：OpenCode 作为在线 Agent 控制平面时的 SDK 边界，和本文的 Railway VM 不是同一条运行路径。
• Cursor Cloud、Grok Bot 与 Linear：以 yindongliang.com 为例的开发测试与观测闭环：远程编码任务怎样接到仓库和 PR，用来对照本文的持久开发机。

参考资料

资料整理日为 2026-10-26。CLI 行为以当天文档为准；本机安装的 Railway CLI 若较旧，先 railway upgrade，再以 --help 为准。

• OpenCode，文档标题 OpenCode：Desktop、本机客户端、remote、sleep 和手动连接。
• Cloud agents，文档标题 Cloud agents：VM、镜像、端口、规格和计价边界。
• Cloud agents quickstart，文档标题 Cloud agents quickstart：安装、克隆和第一项任务。
• Manage agents and sessions，文档标题 Manage agents and sessions：命名、会话、sleep 和没有 idle timeout。
• Credentials and configuration，文档标题 Credentials and configuration：三套凭证、skill 和 MCP。
• Troubleshoot cloud agents，文档标题 Troubleshoot cloud agents：OpenCode 1.x、端口和连错本机。
• railway code，文档标题 railway code。
• railway ca，文档标题 railway ca。
• Pricing Plans，文档标题 Pricing Plans，其中 VM pricing。
• Pricing，文档标题 Pricing，其中 Railway Agent 的 token 行项目。
• Deploying with the CLI，文档标题 Deploying with the CLI。
• Models，Providers，Billing，OpenCode Console。
• Cloud Agents 与 Security overview，Cursor。
• Changelog：Cloud Agents Beta（2026-08-07），Railway for Everyone, Cloud Agents Everywhere（2026-08-21），OpenCode on Cloud Agents（2026-09-25）。