如何在 VPS 上安裝並執行 OpenCode

OpenCode 的功能與本指南的設定內容

OpenCode 是一個在終端機中運作的開放原始碼 AI 程式碼代理程式。您可以在專案目錄中啟動它，接著由它讀取程式碼、提出變更、編輯檔案並執行命令，所有操作都在終端機使用者介面（TUI）中完成。OpenCode 採用 MIT 授權，可連接超過 75 個模型供應商。截至 2026 年中，它在 GitHub 約有 165,000 顆星，是目前獲得最多 GitHub stars 的開放原始碼程式碼代理程式。若要在 VPS 上執行 OpenCode，請在專用的非特權使用者帳戶下安裝，將模型 API key 儲存在私密檔案中，並在 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 通常靠近您要部署的程式碼：儲存庫、建置工具、測試資料庫，以及 staging 環境，往往已經位於同一台機器或附近。能夠編輯程式碼並執行測試的代理，最適合執行在實際執行這些測試的機器上。此外，VPS 是由您控制的伺服器，因此可以刻意為代理提供隔離的環境，下一節會說明這項做法。

如果您仍在選擇工具，在 VPS 上執行程式碼 AI 代理會比較更廣泛的工具選項，其中包括 Aider 和 Goose。

為 OpenCode 建立專用使用者

先說明實際情況：程式碼代理程式會編輯檔案並執行命令。這是它的工作，也是風險所在。OpenCode 會執行建置、測試，以及工作所需的 shell 命令。模型的判斷力雖然良好，但並不完美。代理程式執行時所使用的帳戶，決定了錯誤命令最多能接觸到哪些資源。因此，請勿以 root 執行，也不要使用管理伺服器的相同使用者帳戶。

OpenCode 不同於背景代理程式。它是互動式工具，因此其使用者需要真正的 shell 與 home 目錄：

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

請將要讓它處理的專案放在 /home/opencode 下，並由該使用者 clone。不要授予此帳戶 sudo 權限。如果代理程式執行破壞性命令，它只能破壞此帳戶擁有的資源。這與以非特權使用者執行服務的原則相同。此外，請在 git repository 中工作，因為 repository 能將錯誤編輯變成 git revert，而不是造成損失。

安裝 OpenCode

專案文件提供 2 種安裝方式。安裝指令碼最快，而且以 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 會讀取提供者標準的環境變數。啟動 agent 前，先將檔案載入 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

工作階段、對話內容及任何正在執行的工作，都會保持在原本狀態。這能承受 SSH 連線中斷，但無法跨越伺服器重新開機；重新開機後，請以相同方式啟動新的 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 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 則停用變更功能。開始新工作時先使用 Plan，讓它讀取程式碼並提出作法。確認計畫後，再切換至 Build。在伺服器上，先以唯讀方式檢查是低成本的保險措施。Claude Code 將相同選擇定義為權限模式，而不是 agent。若您同時使用這兩項工具，值得閱讀其將 auto mode 改為預設模式的說明，因為工作階段啟動時採用的模式，會決定未受監控的 agent 能夠變更多少內容。

誠實面對影響範圍

Coding agent 不是被動工具，因此應明確說明這項設定能隔離什麼，以及不能隔離什麼。它能隔離檔案損害：opencode 使用者只擁有自己的家目錄，沒有其他目錄的權限，因此編輯與刪除操作會在該邊界停止。它能限制憑證暴露：金鑰只存在於單一帳號的一個 mode 600 檔案中。但它無法限制該帳號依法可執行的操作。因此，如果專案目錄中存有 production deploy credentials，agent 仍可使用這些憑證；請完全不要將它們放在 agent 的帳號中。

不同於 OpenClaw 這類 gateway agent，OpenCode 是互動式終端機程式，不是 daemon。它不會開啟 listening port，也沒有長時間執行的服務，因此不需要為 agent 本身撰寫 systemd unit，也不需要為它設定防火牆連接埠。隔離範圍就是使用者帳號與專案目錄，這也是本指南第一節最重要的原因。

外部環境仍需按照標準方式維護，因為 coding VPS 仍是公開伺服器：停用 root login 的僅限金鑰 SSH，如 VPS 上的 SSH 強化設定 所示；設定預設拒絕的防火牆；並定期更新系統。此外，也要檢查 agent 產生的內容。在推送前閱讀其 diff，就像閱讀新貢獻者提交的 pull request 一樣，因為最終由你負責部署結果。

最後，請保持工具本身為最新版本。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 儲存在 mode 600 的檔案中；並先使用 Plan agent 進行唯讀檢查，再允許 Build agent 變更內容。如此一來，agent 只能損害該帳號所擁有的內容，伺服器其他部分則不會受到影響。

OpenCode 與 Claude Code 有什麼不同？

OpenCode 採用 MIT 授權且不綁定 provider，能透過單一介面連接超過 75 個模型 provider，包括本機模型。Claude Code 是 Anthropic 自有的終端機 agent，主要搭配 Anthropic 的模型運作。如果你想使用一個工具連接多個 provider，或建立搭配本機模型的完整自架技術堆疊，OpenCode 更適合；兩者都能在 VPS 的 tmux 中搭配相同的非特權使用者設定順利執行。