如何在 VPS 上运行 OpenCode 并保护 API 密钥
学习如何在 VPS 上安装 OpenCode,使用非特权用户和 tmux 保持会话,并将模型 API 密钥存放在权限受限的私有文件中。
OpenCode 是什么,以及本指南要配置什么
OpenCode 是一个面向终端的开源 AI 编码代理。您可以在项目目录中启动它。它会读取代码、提出修改建议、编辑文件并运行命令,所有操作都在终端用户界面(TUI)中完成。OpenCode 采用 MIT 许可证,支持连接超过 75 个模型提供商。截至 2026 年 11 月 3 日,它在 GitHub 上约有 224,000 个 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 月 28 日为 1.19.5),本指南介绍的也是这一系列。OpenCode 2 现已作为独立安装版本发布,可从 https://opencode.ai/v2/install 或 npm 包 @opencode/cli 安装,其工作方式有所不同:默认情况下,终端通过共享的后台服务器运行会话,该服务器由 opencode service 管理。其迁移指南要求在安装 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 +aOpenCode 还提供交互式替代方式:在 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 提供两个可使用 Tab 键切换的代理:Build 是默认代理,具有完整访问权限;Plan 是用于分析的受限代理,未经询问不会在其计划目录之外编辑文件。但 Plan 并非严格只读,因为它仍可运行 shell 命令,而 shell 命令可能修改文件。请在 Plan 中开始新任务,让它读取代码并提出方案;确认方案后,再切换到 Build。如果您希望第一轮操作真正只读,仅禁止 Plan 编辑文件和运行 shell 命令还不够。Plan 可以将工作交给内置的 Explore 子代理,而该子代理仍保留自己的 shell 访问权限,因为父代理的限制不会传递给它启动的子代理。因此,请在 opencode.json 中为 Plan 禁止文件编辑、shell 命令和子代理委派(task 权限)。OpenCode 将 deny 视为阻止操作,而 ask 只会请求您的批准:
{
"$schema": "https://opencode.ai/config.json",
"agent": {
"plan": {
"permission": { "edit": "deny", "bash": "deny", "task": "deny" }
}
}
}在服务器上,先执行一轮无法修改任何内容的操作,是一种成本很低的预防措施。Claude Code 将同一决策表示为权限模式,而不是代理;如果您同时运行这两个工具,建议阅读其将自动模式设为默认模式的变更,因为会话启动时使用的模式决定了无人监控的代理可以修改多少内容。
诚实评估影响范围
编码代理不是被动工具,因此应明确说明此配置能限制什么,以及不能限制什么。它只会将文件损坏范围限制在 opencode 账户有权限修改的文件内;项目目录本身不是沙箱。模式 600 可防止其他非特权账户读取密钥文件,但 OpenCode 以文件所有者身份运行,因此可以读取该文件。它无法限制该账户按权限正常执行的操作。因此,如果项目目录中存有生产环境部署凭据,代理就可以使用这些凭据;应将这类凭据完全移出代理账户。
OpenCode 1.x 同时支持本文使用的交互式 TUI,以及通过 opencode serve 运行的独立非交互式服务器。无头 HTTP 服务器默认监听 127.0.0.1:4096;设置 OPENCODE_SERVER_PASSWORD 可要求 HTTP 基本身份验证。此 tmux 配置不需要 systemd 单元,但如果启用服务器模式,在对外开放之前,应检查监听地址和防火墙规则。OpenCode 2 默认使用共享后台服务器,因此迁移前应重新确认这一点。其隔离边界就是用户账户的操作系统权限,这也是本指南第一节最重要的原因。
外部防护仍需按标准方式配置,因为运行编码代理的 VPS 仍是公网服务器:仅允许密钥认证并禁用 root 登录,如VPS 上的 SSH 加固所述;配置默认拒绝的防火墙,并定期更新系统。还应审核代理生成的内容。在推送之前阅读其差异,就像审核新贡献者提交的拉取请求一样,因为最终由您部署这些结果。
最后,保持工具本身为最新版本。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 密钥存储在权限为 600 的文件中,并先使用 Plan agent 进行初步检查,再让 Build agent 修改任何内容。如果希望该检查严格保持只读,请将 Plan 的编辑、shell 命令和子代理委派权限(task)设置为 deny,因为 Explore 等子代理拥有各自的权限,仍然可以运行 shell 命令。代理仍可访问其账户的操作系统权限所允许访问的任何内容;OpenCode 的权限系统不是安全沙箱。
OpenCode 和 Claude Code 有什么区别?
OpenCode 是开源软件(MIT),与提供商无关,可通过一个界面连接 75 个以上的模型提供商,包括本地提供商。Claude Code 是 Anthropic 自有的终端代理,围绕 Anthropic 的模型构建。如果您希望使用一个工具连接多个提供商,或构建完全自托管且使用本地模型的技术栈,OpenCode 更合适;两者都可以在 VPS 的 tmux 中运行,并使用相同的非特权用户配置。