如何在 VPS 上运行 OpenCode

OpenCode 是什么，以及本指南将配置什么

OpenCode 是一个面向终端的开源 AI 编程代理。您可以在项目目录中启动它。它会读取代码、提出修改建议、编辑文件并运行命令，所有操作都在终端用户界面（TUI）中完成。OpenCode 使用 MIT 许可证，支持连接 75 多个模型提供商。截至 2026 年年中，它在 GitHub 上约有 165,000 个 Star，是目前 Star 数最多的开源编程代理。要在 VPS 上运行 OpenCode，您需要将其安装在专用的非特权用户下，将模型 API 密钥存储在私有文件中，并在 tmux 中启动它，以便连接中断后会话仍能保持。这篇指南将按此顺序完成全部配置。

有一个名称说明可以避免混淆。规范仓库是 anomalyco/opencode，由 Anomaly 团队维护，该团队以前称为 SST。该项目过去位于 sst/opencode。GitHub 上还存在一个名为 opencode-ai/opencode 的无关旧仓库，因此请确认您查看的是正确项目的文档。官方网站是 opencode.ai。

在 VPS 上运行 OpenCode 的原因

编码代理会话通常持续很长时间。OpenCode 可能需要数分钟来完成重构或运行测试套件。如果在笔记本电脑上运行，合上屏幕或 Wi-Fi 连接中断都会导致会话在任务完成前终止。在 tmux 中的 VPS 上运行代理后，即使断开连接，代理仍会继续工作；稍后重新连接即可查看执行结果。这与在 VPS 上使用 tmux 运行 Claude Code的方式相同，也是将代理从笔记本电脑迁移出去后最明显的便利之一。

第二个原因是部署位置。VPS 通常靠近要部署的代码：代码仓库、构建工具、测试数据库以及暂存环境往往已经位于该服务器上或其附近。能够修改代码并运行测试的代理，最适合运行在实际执行这些测试的计算机上。由于该主机由您控制，因此可以有意为代理提供隔离环境，下一节将介绍这一点。

如果您还在选择工具，可以参阅在 VPS 上运行编码 AI 代理，其中会比较更广泛的工具，包括 Aider 和 Goose。

为 OpenCode 创建专用用户

先明确一点：编码代理会编辑文件并运行命令。这是它的工作，也是风险所在。OpenCode 会执行构建、测试以及任务所需的 shell 命令。模型的判断通常可靠，但并不完美。代理运行所使用的账户决定了错误命令能够触及的范围上限。因此，不要以 root 身份运行它，也不要使用管理服务器的同一用户运行它。

与后台代理不同，OpenCode 需要交互运行，因此其用户需要真实的 shell 和主目录：

sudo useradd --create-home --shell /bin/bash opencode
sudo -iu opencode

将需要它处理的项目放在 /home/opencode 下，并由该用户克隆。不要为此账户授予 sudo 权限。如果代理运行了破坏性命令，它只能破坏该账户拥有的内容。这与以非特权用户运行服务的原则相同。此外，应在 git 仓库中工作，因为仓库可以将错误编辑变成 git revert，而不是造成数据丢失。

安装 OpenCode

项目提供两种安装方式。安装脚本最快，并且以 opencode 用户运行脚本可将所有内容保存在该用户的主目录中：

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

这里同样应遵循通常的 curl | bash 习惯：对于需要维护的服务器，先下载脚本并阅读内容，然后再运行。安装完成后，启动新的 shell，使安装程序修改的 PATH 生效，然后检查二进制文件是否能正常响应：

opencode --version

如果更喜欢使用包管理器，并且服务器上已经安装 Node.js，npm 方式会在系统范围内安装相同的工具，使 opencode 二进制文件对所有用户都位于 PATH 中：

sudo npm install -g opencode-ai

无论采用哪种方式，检查方法都相同：opencode --version 会输出版本号。脚本安装后出现 command not found，表示当前 shell 尚未读取更新后的 PATH，因此请以 opencode 用户身份注销并重新登录。

将 API key 放入私有文件

OpenCode 需要您所使用的模型提供商的 key。该 key 可能产生费用，因此应按密码处理。创建一个只有 opencode 用户可以读取的文件，并将权限设为 600。将 key 保存在该文件中，不要直接将其输入命令，否则 key 会出现在 shell 历史记录中：

install -m 600 /dev/null ~/opencode.env
nano ~/opencode.env

在文件中写入您所用提供商的变量，例如 ANTHROPIC_API_KEY=...，或您所用提供商对应的变量。OpenCode 会读取提供商的标准环境变量。启动代理前，将该文件加载到 shell 中：

set -a; source ~/opencode.env; set +a

OpenCode 还提供交互式替代方式：在 TUI 中运行 /connect 命令，按提示添加提供商，并将凭据保存到用户主目录下的 ~/.local/share/opencode/auth.json。如果使用此方式，请通过 chmod 600 ~/.local/share/opencode/auth.json 确认文件为私有文件。这两种方式都不会将 key 暴露在命令行中。请选择其中一种，并保持一致。

在 tmux 中启动 OpenCode

tmux 让 VPS 配置真正发挥作用，因为 SSH 连接结束后，tmux 会话仍会继续运行。启动一个会话，进入项目目录，然后启动代理：

tmux new -s opencode
cd ~/my-project
opencode

此时应看到 TUI 已打开，底部显示提示符，界面中显示项目名称。用自然语言向它描述任务，它就会开始读取文件并提出修改建议。需要离开时，按 Ctrl-b，然后按 d 退出会话；即使合上笔记本电脑，代理也会继续工作。稍后可使用以下命令重新连接：

tmux attach -t opencode

会话、对话和正在运行的任务都会保持在原来的位置。断开连接不会影响它们，但服务器重启会清除这些状态，因此重启后需要按相同方式启动新的 tmux 会话。你也可以打开第二个 tmux 窗口，在第一个代理旁边运行另一个代理。不过，OpenCode 会话彼此独立；而在同一台服务器上运行的 Claude Code 会话可以互相发送消息，这提供了另一种将任务拆分为两部分的方法。

指定模型

OpenCode 与具体提供商无关。它使用 AI SDK 和 Models.dev 目录支持 75 多个提供商，因此同一工具可用于 Anthropic、OpenAI、Google 以及其他数十个提供商，也支持本地服务器。最快的方式是在 TUI 中使用 /connect 命令。该命令会列出提供商并处理凭据。若要使用可提交到版本库并可复现的配置，请在项目根目录创建 opencode.json，并将模型设置为 provider/model-id：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-20250514"
}

本地模型也使用同一个文件，因为任何兼容 OpenAI 的服务器都可以声明为提供商。如果您在同一台 VPS 上通过 在同一台 VPS 上运行 Ollama 提供模型，配置应指向其本地 API，模型名称则以您机器上 ollama list 显示的名称为准：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": { "baseURL": "http://127.0.0.1:11434/v1" },
      "models": { "your-model-name": { "name": "Local coding model" } }
    }
  }
}

从一开始就应养成一个值得采用的习惯。OpenCode 内置两个可通过 Tab 键切换的代理：Build 是默认代理，拥有完整访问权限；Plan 会禁用修改能力。开始新任务时先使用 Plan，让它读取代码并提出方案。确认方案后，再切换到 Build。在服务器上，先进行只读检查可以降低风险。Claude Code 将同一决策称为权限模式，而不是代理。如果您同时使用这两个工具，建议阅读其将自动模式设为默认模式的变化，因为会话启动时使用的模式决定了无人监控的代理可以修改多少内容。

真正的影响范围

代码代理不是被动工具，因此应明确说明此设置能限制什么，不能限制什么。它可以限制文件损坏：opencode用户拥有自己的主目录，不拥有其他目录，因此编辑和删除操作会止步于该边界。它不能防止凭据暴露：密钥存放在一个权限为600的文件中，并归一个账户所有。它也不能限制该账户依法可以执行的操作。因此，如果项目目录中存有生产环境部署凭据，代理就可以使用这些凭据；应将此类凭据完全移出代理账户。

与 OpenClaw 这类网关代理不同，OpenCode 是交互式终端程序，不是守护进程。它不会监听端口，也没有长期运行的服务，因此无需为代理编写 systemd 单元，也无需为代理本身配置防火墙端口。隔离边界由用户账户和项目目录构成，这也是本指南第一节最重要的原因。

外围环境仍需按标准方式维护，因为代码 VPS 仍是公网服务器：禁用 root 登录并仅允许基于密钥的 SSH，如 VPS 上的 SSH 加固；配置默认拒绝的防火墙；并定期更新系统。还应审查代理生成的内容。在推送前阅读其差异，就像阅读新贡献者提交的拉取请求一样，因为最终由您部署这些结果。

最后，应保持工具本身为最新版本。OpenCode 发布更新频繁，而更新会修复对服务器上执行命令的程序很重要的问题。使用安装时采用的相同方式更新：以 opencode用户重新运行安装脚本；如果通过 npm 安装，则运行 sudo npm update -g opencode-ai；然后使用 opencode --version确认新版本。偶尔花一分钟维护，比排查数月前的旧版本已经修复的问题更省时。

FAQ

OpenCode 可以使用本地模型，而不是付费 API 吗？

可以。OpenCode 将所有兼容 OpenAI 的服务器视为 provider，因此，在同一台 VPS 上由 Ollama 提供服务的模型也可以使用：在 opencode.json 中声明 provider，填写本地 baseURL 和 Ollama 报告的模型名称。需要注意的是硬件要求，因为要支持实际的编码工作，模型需要大量内存。因此，下载模型前应根据模型规格配置服务器。

如何让 OpenCode 在关闭笔记本电脑后继续运行？

在 VPS 的 tmux 中运行它。使用 tmux new -s opencode 在命名会话中启动 agent，按 Ctrl-b 后按 d 分离会话。SSH 连接结束后，会话仍会在服务器上运行。随时使用 tmux attach -t opencode 重新连接，会话中的对话和正在运行的任务都会保留。服务器重启会结束会话，因此重启后需要重新创建会话。

允许 OpenCode 在 VPS 上运行命令是否安全？

在进行隔离的情况下可以控制风险。为 OpenCode 创建专用的非特权用户，不授予 sudo 权限；将项目保存在 git 中，以便撤销所有编辑；将 API key 存储在权限模式为 600 的文件中；在允许 Build agent 修改任何内容前，先使用 Plan agent 执行只读检查。这样，agent 只能修改其账户拥有的内容，服务器的其他部分不会被其访问。

OpenCode 和 Claude Code 有什么区别？

OpenCode 是开源软件（MIT 许可证），且不绑定 provider。它通过统一接口连接 75 个以上的模型 provider，包括本地 provider。Claude Code 是 Anthropic 自有的终端 agent，围绕 Anthropic 的模型构建。如果您希望使用一个工具连接多个 provider，或构建完全自托管且使用本地模型的技术栈，OpenCode 更适合；两者都可以在 VPS 的 tmux 中运行，并使用相同的非特权用户配置。