Cara Pasang OpenCode pada VPS dengan Selamat

Apakah OpenCode dan perkara yang anda sediakan

OpenCode ialah ejen pengekodan AI sumber terbuka yang dibina untuk terminal. Anda memulakannya di dalam direktori projek, dan ia membaca kod anda, mencadangkan perubahan, menyunting fail, serta menjalankan arahan, semuanya daripada antara muka pengguna terminal (TUI). Ia dilesenkan di bawah MIT, bersambung dengan lebih daripada 75 penyedia model, dan dengan kira-kira 219,000 bintang GitHub setakat Oktober 2026, ia merupakan ejen pengekodan sumber terbuka yang paling banyak mendapat bintang. Untuk menjalankan OpenCode pada VPS, anda memasangnya di bawah pengguna tanpa keistimewaan (unprivileged user) yang khusus, meletakkan kunci API model anda dalam fail peribadi, dan memulakannya di dalam tmux supaya sesi tersebut kekal apabila sambungan anda terputus. Panduan ini melakukan perkara tersebut, mengikut urutan itu.

Satu nota penamaan dapat mengelakkan kekeliruan. Repositori kanun ialah anomalyco/opencode, diselenggara oleh pasukan Anomaly (dahulunya dikenali sebagai SST), dan projek itu pernah berada di sst/opencode. Repositori lama yang tidak berkaitan bernama opencode-ai/opencode, yang kini diarkibkan, juga wujud di GitHub, jadi pastikan anda membaca dokumentasi projek yang betul. Laman rasmi ialah opencode.ai.

Mengapa menjalankan OpenCode pada VPS

Sesi ejen pengekodan mengambil masa yang lama. OpenCode boleh menghabiskan masa beberapa minit untuk melakukan refactor atau menjalankan suite ujian, dan jika ia berjalan pada komputer riba anda, penutupan skrin atau sambungan Wi-Fi yang terputus akan mematikan sesi tersebut di tengah tugasan. Pada VPS di dalam tmux, ejen akan terus berfungsi selepas anda terputus sambungan, dan anda boleh menyambung semula kemudian untuk melihat apa yang telah dilakukannya. Ini adalah corak yang sama seperti menjalankan Claude Code pada VPS dengan tmux, dan ia merupakan peningkatan kualiti hidup yang paling ketara apabila memindahkan ejen dari komputer riba anda.

Sebab kedua ialah penempatan. VPS berada dekat dengan kod yang anda deploy: repositori, alat binaan, pangkalan data ujian, dan selalunya persekitaran staging yang sudah tersedia di sana atau bersebelahannya. Ejen yang menyunting kod dan menjalankan ujian berfungsi dengan paling baik pada mesin tempat ujian tersebut benar-benar dijalankan. Dan kerana mesin tersebut adalah pelayan yang anda kawal, anda boleh memberikan ejen persekitaran yang terkawal secara khusus, seperti yang dilakukan dalam bahagian seterusnya.

Jika anda masih memilih alat, menjalankan ejen AI pengekodan pada VPS membandingkan bidang yang lebih luas, termasuk Aider dan Goose.

Berikan OpenCode pengguna sendiri

Berikut adalah titik permulaan yang jujur: ejen pengekodan menyunting fail dan menjalankan arahan. Itu adalah tugasnya, dan ia juga merupakan risikonya. OpenCode akan menjalankan binaan, ujian, dan apa sahaja arahan shell yang diperlukan oleh tugasan tersebut, dan pertimbangan model adalah baik tetapi tidak sempurna. Akaun yang digunakan oleh ejen adalah had maksimum bagi apa yang boleh dicapai oleh arahan yang berniat jahat, jadi jangan jalankannya sebagai root, dan jangan jalankannya sebagai pengguna yang sama yang mentadbir pelayan.

Tidak seperti ejen latar belakang, OpenCode adalah interaktif, jadi penggunanya memerlukan shell sebenar dan direktori utama:

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

Simpan projek yang anda mahu ia kerjakan di bawah /home/opencode, yang diklon oleh pengguna tersebut. Jangan berikan akaun itu sebarang hak sudo. Jika ejen menjalankan arahan yang merosakkan, ia hanya boleh memusnahkan apa yang dimiliki oleh akaun ini sahaja, yang merupakan alasan yang sama seperti menjalankan servis sebagai pengguna tanpa keistimewaan. Bekerja di dalam repositori git juga, dan lakukan commit sebelum anda memberikan tugasan kepada ejen, kerana suntingan yang buruk pada kerja yang telah di-commit boleh dipulihkan dengan git revert atau git restore dan bukannya satu kehilangan. Perubahan yang tidak pernah anda commit tidak dilindungi.

Memasang OpenCode

Projek ini mendokumentasikan beberapa cara pemasangan, dan dua daripadanya sesuai untuk pelayan. Skrip pemasangan adalah yang paling pantas, dan menjalankannya sebagai pengguna opencode memastikan segala-galanya berada di dalam direktori home pengguna tersebut:

curl -fsSL https://opencode.ai/install | bash

Tabiat curl | bash yang biasa digunakan di sini seperti di tempat lain: pada pelayan yang anda utamakan, muat turun skrip terlebih dahulu, baca kandungannya, kemudian jalankannya. Selepas pemasangan, mulakan shell baharu supaya perubahan PATH yang dibuat oleh pemasang berkuat kuasa, kemudian semak binari tersebut:

opencode --version

Jika anda lebih suka pengurus pakej dan Node.js sudah tersedia pada mesin tersebut, kaedah npm memasang alat yang sama ke dalam awalan global npm:

sudo npm install -g opencode-ai

Dengan Node.js seluruh sistem, awalan tersebut biasanya /usr/local atau /usr, yang direktori bin miliknya berada pada PATH setiap pengguna. Pengurus versi atau awalan tersuai meletakkan binari di tempat lain, jadi jalankan npm prefix -g terlebih dahulu jika anda mahu opencode ditemui oleh pengguna opencode.

Walau apa pun, semakannya adalah sama: opencode --version memaparkan nombor versi. Ralat command not found selepas pemasangan skrip bermakna shell semasa belum membaca PATH yang dikemas kini, jadi log keluar dan log masuk semula sebagai pengguna opencode.

Kedua-dua arahan memasang barisan OpenCode 1.x, yang masih mengeluarkan versi (1.19.3 pada 16 Oktober 2026), dan panduan ini menerangkan barisan tersebut. OpenCode 2 kini dikeluarkan sebagai pemasangan berasingan, daripada https://opencode.ai/v2/install atau pakej npm @opencode/cli, dan ia berfungsi secara berbeza: pelayan latar belakang kongsi bagi setiap akaun pengguna mengurus sesi, kebenaran, dan pelaksanaan alat, manakala terminal bersambung kepadanya. Panduan migrasinya menyatakan untuk membuang pemasangan 1.x yang diuruskan oleh pakej sebelum memasang 2, kerana kedua-duanya menggunakan arahan opencode.

Simpan kunci API dalam fail peribadi

OpenCode memerlukan kunci untuk mana-mana penyedia model yang anda gunakan, dan kunci tersebut boleh membelanjakan wang anda, jadi layan ia seperti kata laluan. Cipta fail yang hanya boleh dibaca oleh pengguna opencode, dengan mod 600, dan simpan kunci tersebut di sana daripada menaipnya ke dalam arahan yang akan menyebabkannya tersimpan dalam sejarah shell anda:

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

Letakkan pemboleh ubah penyedia anda di dalamnya, contohnya ANTHROPIC_API_KEY=... atau yang setara untuk penyedia anda, kerana OpenCode mengambil pemboleh ubah persekitaran penyedia standard. Muatkan fail tersebut ke dalam shell anda sebelum anda memulakan ejen:

set -a; source ~/opencode.env; set +a

OpenCode juga mempunyai alternatif interaktif: arahan /connect di dalam TUI akan membimbing anda menambah penyedia dan menyimpan kelayakan tersebut ke ~/.local/share/opencode/auth.json dalam direktori home pengguna. Jika anda menggunakan laluan tersebut, sahkan fail itu adalah peribadi dengan chmod 600 ~/.local/share/opencode/auth.json. Kedua-dua laluan memastikan kunci tidak terdedah dalam baris arahan anda; pilih satu dan kekal konsisten.

Mulakan OpenCode di dalam tmux

tmux menjadikan persediaan VPS berbaloi kerana sesi tmux terus berjalan apabila sambungan SSH anda tamat. Mulakan satu sesi, masuk ke dalam direktori projek anda, dan lancarkan ejen tersebut:

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

Anda sepatutnya melihat TUI dibuka dengan prompt di bahagian bawah dan nama projek anda pada antara muka tersebut. Berikan tugasan dalam bahasa biasa, dan ia akan mula membaca fail serta mencadangkan perubahan. Apabila anda ingin keluar, detach dengan menekan Ctrl-b kemudian d, dan ejen tersebut akan terus bekerja walaupun komputer riba anda ditutup. Sambung semula kemudian dengan:

tmux attach -t opencode

Sesi, perbualan, dan sebarang tugasan yang sedang berjalan berada tepat di tempat anda meninggalkannya. Ini bertahan daripada gangguan sambungan anda, tetapi tidak daripada but semula pelayan, jadi selepas but semula anda perlu memulakan sesi tmux baharu dengan cara yang sama. Tiada apa yang menghalang anda daripada membuka tetingkap tmux kedua dan menjalankan ejen lain di samping yang pertama, walaupun sesi OpenCode kekal bebas antara satu sama lain, manakala sesi Claude Code pada mesin yang sama boleh menghantar mesej antara satu sama lain, yang merupakan cara berbeza untuk membahagikan tugasan kepada dua bahagian.

Menghalakannya ke model

OpenCode adalah agnostik penyedia. Ia menggunakan AI SDK dan katalog Models.dev untuk menyokong lebih daripada 75 penyedia, jadi alat yang sama berfungsi dengan Anthropic, OpenAI, Google, dan berpuluh-puluh yang lain, termasuk pelayan tempatan. Laluan pantas ialah arahan /connect di dalam TUI, yang menyenaraikan penyedia dan mengendalikan kelayakan. Untuk persediaan yang boleh anda komit dan hasilkan semula, letakkan opencode.json dalam root projek dan tetapkan model sebagai provider/model-id:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-5-5"
}

Pilih model yang masih disokong oleh penyedia anda: Anthropic menamatkan claude-sonnet-4-20250514 pada 15 Jun 2026, jadi konfigurasi yang masih menamakannya akan gagal.

Model tempatan berfungsi melalui fail yang sama, kerana mana-mana pelayan yang serasi dengan OpenAI boleh diisytiharkan sebagai penyedia. Jika anda menghidangkan model dengan Ollama pada VPS yang sama, konfigurasi menghala ke API tempatannya, dan nama model adalah apa sahaja yang ditunjukkan oleh ollama list pada mesin anda:

{
  "$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" } }
    }
  }
}

Satu tabiat terbina dalam yang wajar diamalkan sejak hari pertama. OpenCode menyediakan dua ejen yang boleh anda tukar antara satu sama lain dengan kekunci Tab: Build, ejen lalai dengan akses penuh, dan Plan, ejen terhad untuk analisis yang menolak penyuntingan fail di luar direktori pelan sendiri tanpa bertanya. Walau bagaimanapun, Plan tidaklah benar-benar hanya baca sahaja (read-only), kerana ia masih boleh menjalankan arahan shell, dan arahan shell boleh mengubah fail. Mulakan tugas baharu dalam Plan, biarkan ia membaca kod dan mencadangkan pendekatan, dan hanya tukar kepada Build apabila anda bersetuju dengan pelan tersebut. Jika anda mahu laluan pertama itu benar-benar hanya baca sahaja, nafikan penyuntingan dan arahan shell untuk Plan dalam opencode.json, kerana OpenCode menganggap deny sebagai menyekat tindakan tersebut, manakala ask hanya meminta kelulusan anda:

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

Pada pelayan, laluan pertama yang tidak boleh mengubah apa-apa adalah langkah keselamatan yang berbaloi. Claude Code membingkai keputusan yang sama sebagai mod kebenaran dan bukannya ejen, dan peralihannya kepada mod auto sebagai lalai wajar dibaca jika anda menjalankan kedua-dua alat tersebut, kerana mod sesi bermula menentukan sejauh mana ejen yang tidak dipantau boleh membuat perubahan.

Radius impak, secara jujur

Ejen pengekodan bukanlah pasif, jadi nyatakan dengan jelas perkara yang dilakukan dan tidak dilakukan oleh persediaan ini. Ia melibatkan risiko kerosakan fail: pengguna opencode hanya memiliki direktori home sendiri dan tiada yang lain, jadi penyuntingan dan pemadaman terhenti pada sempadan tersebut. Ia melibatkan risiko pendedahan kelayakan: kunci disimpan dalam satu fail dengan mod 600, dalam satu akaun. Ia tidak mengehadkan perkara yang boleh dilakukan oleh akaun tersebut secara sah, jadi jika direktori projek menyimpan kelayakan deploy pengeluaran, ejen boleh menggunakannya; jauhkan kelayakan tersebut sepenuhnya daripada akaun ejen.

Berbeza dengan ejen gerbang seperti OpenClaw, OpenCode 1.x ialah program terminal interaktif, bukan daemon. Secara lalai, ia tidak membuka port pendengar (hanya flag --port, --hostname, atau --mdns yang menyebabkan TUI mendengar) dan tidak mempunyai servis yang berjalan lama, jadi tiada unit systemd untuk ditulis dan tiada port untuk difirewall bagi ejen itu sendiri. OpenCode 2 mengubah perkara ini dengan pelayan latar belakang berkongsinya, jadi semak semula perkara ini sebelum anda melakukan migrasi. Pengekangan yang ada hanyalah akaun pengguna dan direktori projek, itulah sebabnya bahagian pertama panduan ini adalah yang paling penting.

Kotak yang melingkupinya masih memerlukan penjagaan standard, kerana VPS pengekodan tetap merupakan pelayan awam: SSH berasaskan kunci sahaja dengan log masuk root dilumpuhkan, seperti dalam pengukuhan SSH pada VPS, firewall dengan dasar default-deny, dan kemas kini rutin. Selain itu, semak hasil kerja ejen. Baca diff yang dihasilkannya sebelum anda melakukan push, sama seperti anda membaca pull request daripada penyumbang baharu, kerana andalah yang akan melakukan deploy terhadap hasil tersebut.

Akhir sekali, pastikan alat itu sendiri sentiasa terkini. OpenCode kerap mengeluarkan versi baharu, dan kemas kini membawa pembetulan yang penting bagi program yang menjalankan arahan pada pelayan anda. Kemas kini menggunakan laluan yang sama semasa anda memasangnya: jalankan semula skrip pemasangan sebagai pengguna opencode, atau jalankan sudo npm update -g opencode-ai jika anda memasang melalui npm, kemudian sahkan versi baharu dengan opencode --version. Kedua-duanya mengekalkan anda pada siri 1.x; beralih ke OpenCode 2 adalah migrasi yang berasingan. Penyelenggaraan selama seminit sekali-sekala adalah lebih murah daripada menyahpepijat gelagat yang sebenarnya telah dibetulkan dalam binaan beberapa bulan yang lalu.

FAQ

Bolehkah OpenCode menggunakan model tempatan dan bukannya API berbayar?

Boleh. OpenCode menganggap mana-mana pelayan yang serasi dengan OpenAI sebagai penyedia, jadi model yang dihoskan oleh Ollama pada VPS yang sama boleh digunakan: isytiharkan penyedia dalam opencode.json dengan baseURL tempatan serta nama model yang dilaporkan oleh Ollama. Cabarannya ialah perkakasan, kerana model yang cukup baik untuk kerja pengekodan sebenar memerlukan memori yang besar, jadi pastikan saiz pelayan mencukupi untuk model tersebut sebelum anda memuat turunnya.

Bagaimanakah cara untuk memastikan OpenCode terus berjalan selepas saya menutup komputer riba?

Jalankannya di dalam tmux pada VPS. Mulakan ejen dalam sesi bernama dengan tmux new -s opencode, nyahlekat (detach) dengan menekan Ctrl-b kemudian d, dan sesi tersebut akan terus berjalan pada pelayan selepas sambungan SSH anda tamat. Sambung semula (reattach) pada bila-bila masa dengan tmux attach -t opencode dan perbualan serta sebarang tugasan yang sedang berjalan masih ada di sana. But semula pelayan akan menamatkan sesi, jadi mulakan sesi baharu selepas but semula.

Adakah selamat untuk membiarkan OpenCode menjalankan arahan pada VPS saya?

Ia boleh dikawal jika anda mengehadkannya. Berikan OpenCode pengguna khusus yang tidak mempunyai keistimewaan (unprivileged) tanpa sudo, simpan projeknya dalam git dan lakukan commit sebelum setiap tugasan supaya suntingan yang salah boleh dipulihkan, simpan kunci API dalam fail dengan mod 600, dan gunakan ejen Plan untuk langkah awal sebelum anda membiarkan ejen Build mengubah apa-apa, dengan suntingan dan arahan shell ditetapkan kepada deny untuk Plan jika anda mahukan langkah tersebut benar-benar hanya baca sahaja (read-only). Ejen tersebut kemudiannya hanya boleh merosakkan apa yang dimiliki oleh akaunnya sendiri, dan bahagian lain pelayan kekal selamat.

Apakah perbezaan antara OpenCode dan Claude Code?

OpenCode adalah sumber terbuka (MIT) dan tidak terikat kepada mana-mana penyedia, ia bersambung dengan lebih daripada 75 penyedia model, termasuk model tempatan, melalui satu antara muka. Claude Code ialah ejen terminal milik Anthropic sendiri yang dibina di sekitar model Anthropic. Jika anda mahukan satu alat untuk pelbagai penyedia, atau tindanan (stack) yang dihoskan sepenuhnya sendiri dengan model tempatan, OpenCode adalah pilihan yang sesuai; kedua-duanya berjalan dengan baik pada VPS di dalam tmux dengan persediaan pengguna tanpa keistimewaan yang sama.