如何在 VPS 上部署 OpenCode AI 代理

OpenCode 簡介與設定目標

OpenCode 是專為終端機設計的開源 AI 程式碼代理工具。您可以在專案目錄中啟動它，透過終端機使用者介面 (TUI) 讀取程式碼、建議修改、編輯檔案並執行指令。OpenCode 採用 MIT 授權，支援超過 75 個模型供應商。截至 2026 年中，其 GitHub 獲得約 165,000 顆星，是目前最受歡迎的開源程式碼代理工具。若要在 VPS 上執行 OpenCode，您需要為其建立專用的非特權使用者，將模型 API key 存放在私有檔案中，並在 tmux 中啟動以確保連線中斷時工作階段仍能持續。本指南將依序引導您完成這些步驟。

關於名稱的說明以避免混淆。官方儲存庫為 anomalyco/opencode，由 Anomaly 團隊（原名 SST）維護，該專案先前位於 sst/opencode。GitHub 上還存在一個名為 opencode-ai/opencode 的舊版且無關的儲存庫，請確認您閱讀的是正確專案的說明文件。官方網站為 opencode.ai。

為何要在 VPS 上執行 OpenCode

Coding agent 的工作流程通常耗時較長。OpenCode 在進行程式碼重構或執行測試套件時，可能需要數分鐘的時間；若在筆電上執行，一旦闔上螢幕或 Wi-Fi 連線中斷，工作任務就會被迫中止。若在 VPS 上透過 tmux 執行，即使斷開連線，agent 仍會持續工作，您稍後重新連線即可查看執行結果。這與 在 VPS 上使用 tmux 執行 Claude Code 的模式相同，也是將 agent 從筆電移至伺服器後，對開發體驗提升最顯著的優點。

第二個原因是部署位置。VPS 與您部署的程式碼環境距離更近：儲存庫、建置工具、測試資料庫，以及常見的 staging environment 通常都已部署於該處或鄰近環境。對於需要修改程式碼並執行測試的 agent 而言，在實際執行測試的機器上作業效率最高。此外，由於伺服器由您掌控，您可以刻意為 agent 提供一個隔離的環境，詳見下一節。

如果您仍在挑選工具，在 VPS 上執行 coding AI agent 提供了更廣泛的比較，包含 Aider 與 Goose。

為 OpenCode 配置獨立使用者

核心概念如下：程式碼代理（coding agent）負責編輯檔案並執行指令。這是其功能，同時也是風險所在。OpenCode 會執行建置、測試以及任務所需的任何 shell 指令；雖然模型判斷能力良好，但並非完美。代理程式所使用的帳號權限，決定了錯誤指令可能造成的最大破壞範圍。因此，請勿使用 root 權限執行，亦請勿使用伺服器管理員帳號執行。

與背景代理（background agent）不同，OpenCode 具備互動性，因此其使用者需要具備真實的 shell 與 home directory：

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

請將需要處理的專案存放於 /home/opencode，並由該使用者進行 clone。請勿賦予此帳號 sudo 權限。若代理程式執行了具破壞性的指令，其影響範圍僅限於該帳號所擁有的檔案，這與 以非特權使用者執行服務 的原理相同。此外，請務必在 git repository 中進行操作，因為 repository 能將錯誤的編輯轉化為 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 需要您所使用的模型供應商金鑰。由於金鑰涉及費用支出，請將其視為密碼處理。請建立一個權限為 600 且僅限 opencode 使用者讀取的檔案，並將金鑰存於其中。避免直接在指令中輸入金鑰，以免紀錄於 shell history 中：

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

請在檔案中寫入供應商的變數名稱，例如 ANTHROPIC_API_KEY=... 或您所使用供應商的對應變數，因為 OpenCode 會讀取標準的供應商環境變數。在啟動 agent 之前，請先載入該檔案：

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 設定的核心價值所在，因為即使 SSH 連線中斷，tmux session 仍會持續執行。請啟動一個 session，進入專案目錄，並啟動 agent：

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

您應該會看到 TUI 介面開啟，底部顯示提示字元，且介面顯示您的專案名稱。請使用自然語言下達指令，agent 便會開始讀取檔案並提議修改。若要離開，請按 Ctrl-b 後按 d 進行 detach，即使關閉筆電，agent 仍會繼續工作。稍後請使用以下指令重新 attach：

tmux attach -t opencode

Session、對話紀錄及任何執行中的任務都會保持原狀。這能應對連線中斷，但無法應對伺服器重啟；因此重啟後，請依照相同步驟啟動新的 tmux session。

指向模型

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 模式。在伺服器環境中，先進行唯讀的初步掃描是低成本的保險措施。

實際影響範圍

程式碼代理程式（coding agent）並非被動運作，因此請明確了解此設定的權限範圍。此設定包含檔案損毀風險：opencode 使用者僅擁有其家目錄（home directory）的權限，編輯與刪除操作僅限於該範圍。此設定包含憑證外洩風險：金鑰儲存在單一檔案中，權限設定為 600，且僅限單一帳戶存取。此設定不包含該帳戶具備的合法權限，因此若專案目錄中包含正式環境的部署憑證，代理程式便能使用它們；請務必將這些憑證完全移出代理程式的帳戶。

與 OpenClaw 等閘道型代理程式不同，OpenCode 是互動式終端機程式，而非守護行程（daemon）。它不會開啟監聽埠（listening port），也沒有長期運行的服務，因此不需要撰寫 systemd unit，也不需要為代理程式本身設定防火牆埠。隔離機制僅限於使用者帳戶與專案目錄，這也是為何本指南的第一部分至關重要。

儘管有隔離機制，仍須進行標準維護，因為開發用 VPS 仍屬於公開伺服器：應參考 SSH hardening on a VPS 設定僅限金鑰的 SSH 並停用 root 登入、設定預設拒絕（default-deny）的防火牆，並定期更新。此外，請審核代理程式產生的內容。在推送（push）之前，請像審核新貢獻者的 pull request 一樣閱讀其 diff，因為最終執行部署的人是您。

最後，請保持工具本身為最新版本。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 在具名 session 中啟動 agent，並按 Ctrl-b 後按 d 進行 detach，如此 session 就能在 SSH 連線結束後繼續在伺服器上執行。隨時可以使用 tmux attach -t opencode 重新 attach，對話內容與執行中的任務都會保留。伺服器重啟會導致 session 結束，重啟後請重新啟動 session。

讓 OpenCode 在我的 VPS 上執行指令是否安全？

只要進行限制，風險是可控的。請為 OpenCode 提供一個不具備 sudo 權限的專用非特權使用者，將專案存放在 git 中以確保所有修改皆可復原，將 API key 儲存在權限為 600 的檔案中，並在允許 Build agent 進行修改前，先使用 Plan agent 進行唯讀的第一輪掃描。如此一來，agent 僅能損害其帳號所擁有的內容，伺服器的其餘部分將保持安全。

OpenCode 與 Claude Code 有何不同？

OpenCode 是開源軟體 (MIT) 且與提供者無關，透過單一介面可連接超過 75 個模型提供者（包含本地提供者）。Claude Code 是 Anthropic 開發的終端機 agent，專為 Anthropic 模型設計。若你需要一個可連接多個提供者的工具，或是包含本地模型的完全自託管架構，OpenCode 是較佳選擇；兩者皆適合在 VPS 的 tmux 中，並使用相同的非特權使用者設定來執行。