如何在 VPS 上安裝並執行 OpenCode

OpenCode 是什麼，以及你要設定的內容

OpenCode 是一套開源 AI 終端機程式碼代理程式，專為終端機設計。你可以在專案目錄中啟動它，讓它讀取程式碼、提出變更、編輯檔案及執行命令，全部透過終端機使用者介面（TUI）完成。它採用 MIT 授權，可連接超過 75 家模型供應商；截至 October 2026 約有 219,000 個 GitHub stars，是目前獲得最多 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 與家目錄：

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 的全域 prefix：

sudo npm install -g opencode-ai

使用系統範圍的 Node.js 時，該 prefix 通常是 /usr/local 或 /usr，其 bin 目錄會位於每個使用者的 PATH 中。版本管理程式或自訂 prefix 可能會將二進位檔放在其他位置；如果需要讓 opencode 能由 opencode 使用者找到，請先執行 npm prefix -g。

無論採用哪種方式，檢查方法都相同：opencode --version 會顯示版本號。若在執行安裝指令碼後看到 command not found，表示目前的 shell 尚未讀取更新後的 PATH；請以 opencode 使用者登出，再重新登入。

兩個命令都會安裝 OpenCode 1.x 系列。此系列仍會發布新版本（16 October 2026 為 1.19.3），本指南介紹的也是此系列。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 會讀取提供者標準的環境變數。啟動 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-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。如果希望第一次處理真正保持唯讀，請在 opencode.json 中拒絕 Plan 的編輯和 shell 命令，因為 OpenCode 將 deny 視為阻止動作，而 ask 只會要求你核准：

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

在伺服器上，先進行無法修改任何內容的處理，是低成本的保護措施。Claude Code 將相同決策表述為權限模式，而不是代理程式；如果你同時執行兩種工具，值得閱讀其將 auto mode 設為預設模式的變更，因為工作階段啟動時所使用的模式，會決定未受監看代理程式能夠修改多少內容。

真正的影響範圍

coding agent 並非被動執行，因此應明確說明這項設定能限制什麼，以及不能限制什麼。它能限制檔案損害：opencode 使用者擁有自己的 home 目錄，沒有其他目錄的權限，因此編輯與刪除操作會止於這個邊界。它也能限制憑證暴露：金鑰只存放在一個檔案中，權限模式為 600，且僅屬於一個帳號。但它無法限制該帳號依法可執行的操作；如果專案目錄存有正式環境部署憑證，agent 仍可使用這些憑證，因此應完全避免將它們放在 agent 的帳號中。

不同於 OpenClaw 這類 gateway agent，OpenCode 1.x 是互動式終端機程式，不是 daemon。預設不會開啟任何 listening port（只有 --port、--hostname 或 --mdns flag 會讓 TUI 進入 listening 狀態），也沒有長時間執行的服務，因此不需要撰寫 systemd unit，也不需要為 agent 本身設定 port 防火牆規則。OpenCode 2 會透過共用的 background server 改變這項行為，因此在遷移前應重新確認。這裡的隔離依靠 user account 和 project directory，這也是本指南第一節最重要的原因。

外部防護仍需依照標準方式維護，因為 coding VPS 仍是公開伺服器：停用 root login，僅允許使用金鑰的 SSH，如 VPS 上的 SSH 強化；設定 default-deny firewall；並定期更新系統。同時應檢查 agent 產出的內容。推送前先閱讀 diff，就像檢查新貢獻者的 pull request，因為最後由你部署這些結果。

最後，請讓工具本身保持最新。OpenCode 經常發布版本，而對於會在伺服器上執行命令的程式而言，更新所包含的修正十分重要。更新時使用安裝時採用的相同方式：以 opencode 使用者重新執行安裝 script；如果是透過 npm 安裝，則執行 sudo npm update -g opencode-ai，再使用 opencode --version 確認新版本。這兩種方式都會維持在 1.x 系列；遷移至 OpenCode 2 則是另一項作業。偶爾花一分鐘維護，總比之後除錯數個月前的版本已經修正的行為更省事。

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 儲存在檔案權限為 600 的檔案中。若希望第一次檢查嚴格限制為唯讀，可先使用 Plan agent，再讓 Build agent 進行變更，並將編輯與 shell 命令設定為 deny。如此一來，agent 只能修改該帳號擁有的內容，伺服器的其他部分則無法存取。

OpenCode 與 Claude Code 有何不同？

OpenCode 採用開放原始碼授權（MIT），且不綁定特定 provider，可透過單一介面連接 75 個以上的模型 provider，包括本機模型。Claude Code 是 Anthropic 自有的終端機 agent，主要搭配 Anthropic 的模型。若需要在多個 provider 之間使用同一套工具，或希望建置完全自架且採用本機模型的環境，OpenCode 會更合適；兩者都能在 VPS 的 tmux 中順利執行，並採用相同的非特權使用者設定。