在 VPS 上运行 OpenCode

OpenCode 是什么，您要搭建的又是什么

OpenCode 是一个为终端打造的开源 AI 编程智能体。您在某个项目目录里启动它，它就会读取您的代码、提出修改建议、编辑文件并运行命令，这一切都在一个终端用户界面（TUI）里完成。它采用 MIT 许可证，可连接 75 个以上的模型提供方，截至 2026 年年中约有 165,000 个 GitHub 星标，是目前星标最多的开源编程智能体。要在 VPS 上运行 OpenCode，您需要在一个专用的非特权用户下安装它，把模型 API 密钥放进一个私有文件，并在 tmux 里启动它，这样当您的连接断开时会话仍能存活。本指南就按这个顺序完成这些步骤。

有一处命名说明能帮您省去困惑。规范的代码仓库是 anomalyco/opencode，由 Anomaly 团队（此前称为 SST）维护，项目过去位于 sst/opencode。GitHub 上还存在一个名为 opencode-ai/opencode 的较旧且无关的仓库，所以请确认您看的是正确项目的文档。官方站点是 opencode.ai。

为什么要在 VPS 上运行 OpenCode

一次编程智能体会话往往很长。OpenCode 可能会花上好几分钟去完成一次重构或跑一遍测试套件，如果它运行在您的笔记本上，合上盖子或掉线的 Wi-Fi 就会在任务中途终结这个会话。而在 VPS 上的 tmux 里，智能体在您断开连接后仍会继续工作，您稍后重新接入就能看到它做了什么。这和 在 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 密钥放进一个私有文件

无论您用哪个模型提供方，OpenCode 都需要一个密钥，而这个密钥能花掉您的钱，所以要把它当作密码来对待。创建一个只有 opencode 用户可读、权限为 600 的文件，把密钥放在那里，而不要把它输进命令里，否则它会留在您的 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 确认该文件是私有的。这两种方式都能让密钥不出现在您的命令行里；选一种并保持一致。

在 tmux 里启动 OpenCode

tmux 才是让这套 VPS 方案值得的原因，因为一个 tmux 会话在您的 SSH 连接结束后仍会继续运行。启动一个会话，进入您的项目，然后运行智能体：

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

您应当看到 TUI 打开，底部有一个输入框，界面里显示着您的项目名。用平实的语言给它一个任务，它就会开始读取文件并提出修改建议。当您想离开时，用 Ctrl-b 然后按 d 分离会话，智能体会在您合上笔记本后继续工作。稍后用以下命令重新接入：

tmux attach -t opencode

会话、对话内容以及任何正在运行的任务，都还在您离开时的样子。这能挺过您的断连，但挺不过服务器重启，所以重启之后请用同样的方式启动一个新的 tmux 会话。

指定一个模型

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 上的 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。在服务器上，一次只读的先行处理是很便宜的保险。

老实说说影响范围

编程智能体并不是被动的，所以要明确讲清楚这套方案能挡住什么、挡不住什么。它挡得住文件损坏：opencode 用户只拥有自己的家目录，别无其他，所以编辑和删除都止步于这条边界。它挡得住凭据外泄：密钥只存在于一个权限为 600 的文件里，在一个账户里。它挡不住这个账户本就能合法做的事，所以如果项目目录里放着生产部署凭据，智能体就能用它们；请把这类凭据完全排除在智能体的账户之外。

与 OpenClaw 这类网关型智能体不同，OpenCode 是一个交互式终端程序，不是守护进程。它不打开任何监听端口，也没有长期运行的服务，所以对智能体本身而言，既没有要写的 systemd 单元，也没有要在防火墙上放行的端口。它的约束就是这个用户账户和这个项目目录，这也是为什么本指南的第一节才是最要紧的一节。

围绕它的这台机器仍然需要常规的照料，因为一台跑编程任务的 VPS 依然是一台公开的服务器：仅用密钥的 SSH 并禁用 root 登录（如 VPS 上的 SSH 加固 所述）、一道默认拒绝的防火墙，以及日常更新。还要审阅智能体产出的东西。在推送之前读一读它的 diff，就像您会审阅一位新贡献者的 pull request 一样，因为最终部署结果的人是您。

最后，让工具本身保持最新。OpenCode 发布频繁，而对一个会在您服务器上运行命令的程序来说，更新里带的修复很重要。更新走的是您当初安装时的同一条路：以 opencode 用户身份重新运行安装脚本，或者如果您是通过 npm 安装的，就运行 sudo npm update -g opencode-ai，然后用 opencode --version 确认新版本。时不时花上一分钟维护，比去调试一个几个月前的旧版本早已修复的行为要划算得多。

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 密钥存进一个权限为 600 的文件，并在放手让 Build 智能体做任何改动之前，先用它的 Plan 智能体做一次只读的先行处理。这样智能体就只能损坏它自己账户拥有的东西，服务器的其余部分则触及不到。

OpenCode 和 Claude Code 有什么区别？

OpenCode 是开源的（MIT），且与提供方无关，通过一个界面连接 75 个以上的模型提供方，包括本地的。Claude Code 是 Anthropic 自家的终端智能体，围绕 Anthropic 的模型打造。如果您想要一个工具通吃众多提供方，或者想要一套配上本地模型、完全自托管的技术栈，那么 OpenCode 更合适；两者都能在 VPS 上的 tmux 里良好运行，用的是同一套非特权用户的搭建方式。