如何在 VPS 上运行 OpenCode

OpenCode 的作用，以及本教程要配置的内容

OpenCode 是一个面向终端的开源 AI 编程代理。您可以在项目目录中启动它。它会读取代码、提出修改建议、编辑文件并运行命令，所有操作都通过终端用户界面（TUI）完成。OpenCode 采用 MIT 许可证，支持连接 75 多个模型提供商。截至 2026 年 10 月，它在 GitHub 上约有 213,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 或 git restore 即可恢复，而不会直接造成损失。未提交的更改不受保护。

安装 OpenCode

项目文档介绍了多种安装方式，其中两种适合服务器。安装脚本最快。以 opencode 用户运行脚本，可将所有内容保留在该用户的主目录中：

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

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

opencode --version

如果更喜欢使用包管理器，并且服务器上已经安装了 Node.js，可以使用 npm，将同一工具安装到 npm 的全局前缀中：

sudo npm install -g opencode-ai

使用系统范围的 Node.js 时，该前缀通常是 /usr/local 或 /usr，其 bin 目录位于每个用户的 PATH 中。版本管理器或自定义前缀会将二进制文件放到其他位置。因此，如果需要让 opencode 用户找到 opencode，请先运行 npm prefix -g。

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

这两条命令都会安装 OpenCode 1.x 系列。该系列仍会发布新版本（2026 年 10 月 11 日发布 1.19.0），本指南介绍的也是这一系列。OpenCode 2 现已作为独立安装版本提供，可从 https://opencode.ai/v2/install 或 npm 软件包 @opencode/cli 安装。它的工作方式不同：每个用户账户运行一个共享的后台服务器，负责管理会话、权限和工具执行，终端再连接到该服务器。其迁移指南要求在安装 2 之前移除通过软件包管理器安装的 1.x，因为两者都使用 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-5-5"
}

选择提供商仍在提供的模型：Anthropic 已于 15 June 2026 停止提供 claude-sonnet-4-20250514，因此仍指定该模型的配置会失败。

本地模型也可通过同一文件使用，因为任何兼容 OpenAI API 的服务器都可以声明为提供商。如果通过 在同一 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 提供两个 agent，可使用 Tab 键在它们之间切换：Build 是默认 agent，拥有完整访问权限；Plan 是用于分析的受限 agent，在修改文件前会阻止操作或请求确认。不过，Plan 并非严格只读，因为它仍可运行 shell 命令，而 shell 命令可能修改文件。开始新任务时先使用 Plan，让它读取代码并提出方案；确认方案后，再切换到 Build。如果希望第一次检查真正只读，请在 opencode.json 中禁止 Plan 修改文件和运行 shell 命令，因为 OpenCode 将 deny 视为阻止操作，而 ask 只会请求您批准：

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "plan": {
      "permission": { "edit": "deny", "bash": "deny" }
    }
  }
}

在服务器上，先进行一次无法修改任何内容的检查，是一种低成本的保护措施。Claude Code 将同一选择称为权限模式，而不是 agent。如果同时运行这两个工具，建议阅读其将自动模式设为默认模式的变化，因为会话启动时使用的模式决定了无人监控的 agent 能够修改多少内容。

爆炸半径：实话实说

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

不同于 OpenClaw 这类网关代理，OpenCode 1.x 是交互式终端程序，不是 daemon。默认情况下，它不会打开监听端口（只有 --port、--hostname 或 --mdns 标志会让 TUI 监听），也没有长期运行的服务，因此无需为代理本身编写 systemd 单元，也无需为其配置端口防火墙规则。OpenCode 2 通过共享后台服务器改变了这一点，因此迁移前请重新确认。隔离边界由用户账户和项目目录构成，这也是本指南第一节最重要的原因。

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

最后，请保持工具本身为最新版本。OpenCode 发布频繁，而更新会修复与在服务器上运行命令相关的重要问题。使用安装时采用的同一路径进行更新：以 opencode 用户重新运行安装脚本；如果通过 npm 安装，则运行 sudo npm update -g opencode-ai；然后使用 opencode --version 确认新版本。两种方式都会继续使用 1.x 系列；迁移到 OpenCode 2 是单独的迁移工作。偶尔花一分钟维护，比排查数月前版本已经修复的行为问题成本更低。

FAQ

OpenCode 可以使用本地模型代替付费 API 吗？

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

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

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

允许 OpenCode 在我的 VPS 上运行命令安全吗？

只要进行隔离，就可以控制风险。为 OpenCode 分配专用的非特权用户，不授予 sudo 权限；将项目保存在 git 中，并在每项任务前提交，以便回滚错误修改；将 API key 保存在权限模式为 600 的文件中。开始修改前，先使用 Plan agent 执行初步检查；如果希望该检查严格保持只读，可将 Plan 的编辑和 shell 命令设置为 deny。这样，代理最多只能修改其账户拥有的内容，服务器的其他部分仍无法访问。

OpenCode 和 Claude Code 有什么区别？

OpenCode 采用 MIT 许可证并且与提供商无关，可通过一个界面连接超过 75 个模型提供商，包括本地提供商。Claude Code 是 Anthropic 自有的终端代理，围绕 Anthropic 的模型构建。如果希望在多个提供商之间使用同一个工具，或使用包含本地模型的完全自托管技术栈，OpenCode 更适合；两者都可以在 VPS 的 tmux 中运行，并采用相同的非特权用户配置。