Cách cài đặt OpenCode trên VPS an toàn

OpenCode là gì, và bạn đang thiết lập cái gì

OpenCode là một agent AI coding mã nguồn mở được xây dựng cho terminal. Bạn khởi chạy nó bên trong một thư mục project, nó sẽ đọc code, đề xuất thay đổi, chỉnh sửa file và chạy các command, tất cả đều thông qua một giao diện terminal user interface (TUI). Nó có license MIT, kết nối với hơn 75 model provider, và với khoảng 165,000 GitHub stars tính đến giữa năm 2026, đây là coding agent mã nguồn mở có nhiều star nhất hiện nay. Để chạy OpenCode trên một VPS, bạn cài đặt nó dưới một user không có đặc quyền (unprivileged user) riêng biệt, để API key của model vào một file riêng tư, và chạy nó bên trong tmux để session không bị ngắt khi kết nối của bạn bị mất. Hướng dẫn này sẽ thực hiện chính xác những việc đó, theo đúng thứ tự.

Một lưu ý về tên gọi để tránh nhầm lẫn. Repository chính thức là anomalyco/opencode, được duy trì bởi team Anomaly (trước đây là SST), và dự án từng nằm tại %%sst/opencode. Một repository cũ không liên quan tên là opencode-ai/opencode cũng tồn tại trên GitHub, vì vậy hãy kiểm tra kỹ để đảm bảo bạn đang đọc đúng tài liệu của dự án. Trang web chính thức là opencode.ai.

Tại sao nên chạy OpenCode trên một VPS

Một session của coding agent thường kéo dài. OpenCode có thể mất nhiều phút để thực hiện refactor hoặc chạy một test suite, và nếu bạn chạy nó trên laptop, việc gập máy hoặc mất kết nối Wi-Fi sẽ làm chết session ngay giữa tác vụ. Trên một VPS bên trong tmux, agent sẽ tiếp tục làm việc sau khi bạn ngắt kết nối, và bạn có thể reattach lại sau đó để xem nó đã làm gì. Đây cũng là mô hình giống như chạy Claude Code trên VPS với tmux, và đây là lợi ích lớn nhất về mặt trải nghiệm khi chuyển một agent từ laptop lên server.

Lý do thứ hai là vị trí đặt máy. Một VPS nằm gần với code mà bạn deploy: repository, các build tools, test database, và thường là cả staging environment đã nằm sẵn ở đó hoặc ngay cạnh đó. Một agent chỉnh sửa code và chạy tests sẽ hoạt động tốt nhất trên chính máy mà các tests đó thực sự chạy. Và vì máy chủ là máy bạn kiểm soát, bạn có thể cố ý cung cấp cho agent một môi trường bị giới hạn (contained environment), điều mà phần tiếp theo sẽ thực hiện.

Nếu bạn vẫn đang cân nhắc công cụ, chạy một coding AI agent trên VPS sẽ so sánh các lựa chọn rộng hơn, bao gồm cả Aider và Goose.

Cấp cho OpenCode một user riêng

Đây là điểm bắt đầu thực tế: một coding agent sẽ chỉnh sửa file và chạy command. Đó là nhiệm vụ của nó, nhưng cũng chính là rủi ro. OpenCode sẽ chạy build, test và bất kỳ shell command nào mà tác vụ yêu cầu; judgment của model tuy tốt nhưng không hoàn hảo. Quyền hạn của account mà agent chạy chính là giới hạn tối đa mà một command lỗi có thể gây ra, vì vậy đừng chạy nó dưới quyền root, và đừng chạy nó bằng chính user quản trị server.

Không giống như một agent chạy ngầm, OpenCode có tính tương tác, vì vậy user của nó cần một shell thực thụ và một home directory:

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

Hãy để các project bạn muốn nó làm việc dưới thư mục /home/opencode, được clone bởi user đó. Không cấp quyền sudo cho account này. Nếu agent chạy một command gây phá hoại, nó chỉ có thể phá hủy những gì account này sở hữu, tương tự như lý do chạy các service dưới quyền một unprivileged user. Hãy làm việc bên trong một git repository, vì một repository sẽ biến bất kỳ lỗi chỉnh sửa nào thành một git revert thay vì một sự mất mát dữ liệu.

Cài đặt OpenCode

Dự án có hai cách cài đặt. Dùng script cài đặt là nhanh nhất, và chạy nó dưới user opencode sẽ giữ mọi thứ bên trong home directory của user đó:

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

Thói quen curl | bash thông thường cũng áp dụng ở đây như mọi nơi khác: trên một server quan trọng, hãy download script về trước, đọc nó, rồi mới chạy. Sau khi cài đặt, hãy mở một shell mới để thay đổi PATH mà trình cài đặt thực hiện có hiệu lực, sau đó kiểm tra xem binary có phản hồi không:

opencode --version

Nếu bạn thích dùng package manager và máy đã có sẵn Node.js, cách dùng npm sẽ cài đặt cùng một công cụ này cho toàn hệ thống (system-wide), giúp binary opencode nằm trong PATH của mọi user:

sudo npm install -g opencode-ai

Dù cách nào, việc kiểm tra cũng như nhau: opencode --version sẽ in ra số phiên bản. Nếu sau khi cài bằng script mà gặp lỗi command not found, nghĩa là shell hiện tại chưa đọc PATH mới, hãy log out và log in lại bằng user opencode.

Đặt API key vào một file riêng tư

OpenCode cần một key cho bất kỳ model provider nào bạn sử dụng, và key đó có thể tiêu tốn tiền của bạn, vì vậy hãy đối xử với nó như một password. Hãy tạo một file mà chỉ user opencode mới có quyền đọc, với mode 600, và để key ở đó thay vì gõ trực tiếp vào command (điều này sẽ khiến key nằm trong shell history):

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

Hãy đưa biến môi trường của provider vào đó, ví dụ ANTHROPIC_API_KEY=... hoặc tương đương cho provider của bạn, vì OpenCode sẽ nhận các biến môi trường provider tiêu chuẩn. Load file đó vào shell trước khi bạn bắt đầu agent:

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

OpenCode cũng có một cách tương tác: lệnh /connect bên trong TUI sẽ hướng dẫn bạn thêm provider và lưu credential vào ~/.local/share/opencode/auth.json trong home directory của user. Nếu bạn dùng cách đó, hãy xác nhận file là riêng tư bằng lệnh chmod 600 ~/.local/share/opencode/auth.json. Cả hai cách đều giữ key tránh khỏi command line; hãy chọn một cách và làm nhất quán.

Chạy OpenCode bên trong tmux

tmux là thứ khiến việc thiết lập trên VPS trở nên xứng đáng, vì một tmux session vẫn tiếp tục chạy khi kết nối SSH của bạn kết thúc. Hãy khởi tạo một session, di chuyển vào project của bạn, và chạy agent:

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

Bạn sẽ thấy TUI mở ra với một prompt ở dưới cùng và tên project của bạn trên giao diện. Hãy đưa cho nó một tác vụ bằng ngôn ngữ tự nhiên, và nó sẽ bắt đầu đọc file và đề xuất các thay đổi. Khi muốn thoát, hãy detach bằng tổ hợp Ctrl-b rồi d, và agent sẽ tiếp tục làm việc ngay cả khi laptop đã gập. Để reattach lại sau đó, dùng:

tmux attach -t opencode

Session, cuộc hội thoại và bất kỳ tác vụ nào đang chạy đều nằm chính xác ở nơi bạn đã để lại. Điều này giúp duy trì công việc khi mất kết nối, nhưng không giúp duy trì khi server reboot, vì vậy sau khi reboot, bạn cần khởi động một tmux session mới theo cách tương tự.

Kết nối với một model

OpenCode không phụ thuộc vào bất kỳ provider cụ thể nào. Nó sử dụng AI SDK và danh mục Models.dev để hỗ trợ hơn 75 provider, vì vậy cùng một công cụ có thể dùng với Anthropic, OpenAI, Google và hàng chục bên khác, bao gồm cả các server local. Cách nhanh nhất là dùng lệnh /connect bên trong TUI để liệt kê các provider và xử lý credential. Để có một thiết lập có thể commit và tái lập được, hãy đặt một file opencode.json ở root project và thiết lập model là provider/model-id:

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

Một model local cũng hoạt động qua cùng một file đó, vì bất kỳ server nào tương thích với OpenAI đều có thể được khai báo là một provider. Nếu bạn chạy model bằng Ollama trên cùng một VPS, config sẽ trỏ đến local API của nó, và tên model sẽ là bất cứ thứ gì mà ollama list hiển thị trên máy của bạn:

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

Có một thói quen cần áp dụng ngay từ ngày đầu. OpenCode đi kèm với hai agent mà bạn có thể chuyển đổi bằng phím Tab: Build, agent mặc định với toàn quyền truy cập, và Plan, agent sẽ vô hiệu hóa khả năng thực hiện thay đổi. Hãy bắt đầu một tác vụ mới ở chế độ Plan, để nó đọc code và đề xuất hướng tiếp cận, và chỉ chuyển sang Build khi bạn đồng ý với kế hoạch đó. Trên một server, việc chạy thử ở chế độ read-only trước là một bước bảo vệ rẻ tiền.

Phạm vi ảnh hưởng (Blast radius), nói thẳng ra

Một coding agent không hề thụ động, vì vậy hãy nói thẳng những gì thiết lập này có và không có khả năng gây hại. Nó có khả năng gây hư hại file: user opencode chỉ sở hữu home directory của chính nó và không gì khác, nên các thay đổi và xóa file sẽ dừng lại ở ranh giới đó. Nó có khả năng làm lộ credential: key nằm trong một file với mode 600, trong một account. Nó không thể làm gì vượt quá quyền hạn hợp lệ của account đó, vì vậy nếu thư mục project chứa credential deploy production, agent có thể sử dụng chúng; hãy giữ chúng hoàn toàn tách biệt khỏi account của agent.

Không giống như một gateway agent như OpenClaw, OpenCode là một chương trình terminal tương tác, không phải là một daemon. Nó không mở port lắng nghe và không có service chạy ngầm, vì vậy không cần viết systemd unit hay cấu hình firewall cho chính agent. Sự cô lập nằm ở account user và thư mục project, đó là lý do tại sao phần đầu tiên của hướng dẫn này là phần quan trọng nhất.

Tuy nhiên, máy chủ vẫn cần được chăm sóc tiêu chuẩn, vì một coding VPS vẫn là một server công cộng: SSH chỉ dùng key và tắt root login, giống như trong SSH hardening trên VPS, firewall mặc định là deny-all, và cập nhật định kỳ. Và hãy kiểm tra những gì agent tạo ra. Hãy đọc các diff trước khi bạn push chúng, giống như cách bạn đọc một pull request từ một contributor mới, vì chính bạn là người deploy kết quả đó.

Cuối cùng, hãy giữ cho chính công cụ này luôn mới nhất. OpenCode phát hành bản cập nhật thường xuyên, và các bản cập nhật mang theo các bản sửa lỗi quan trọng cho một chương trình chạy command trên server của bạn. Việc cập nhật cũng dùng cách bạn đã cài đặt: chạy lại script cài đặt dưới user opencode, hoặc chạy sudo npm update -g opencode-ai nếu bạn cài qua npm, sau đó xác nhận phiên bản mới bằng opencode --version. Một phút bảo trì định kỳ sẽ rẻ hơn nhiều so với việc debug những lỗi mà một bản build cũ từ nhiều tháng trước đã sửa rồi.

FAQ

OpenCode có thể dùng model local thay vì API trả phí không?

Có. OpenCode coi bất kỳ server nào tương thích với OpenAI là một provider, vì vậy một model chạy bởi Ollama trên cùng một VPS đều hoạt động: khai báo provider trong opencode.json với baseURL local và tên model mà Ollama báo cáo. Điểm mấu chốt là phần cứng, vì một model đủ tốt để làm việc coding thực tế cần lượng RAM lớn, vì vậy hãy chọn server có cấu hình phù hợp với model trước khi bạn download nó.

Làm sao để OpenCode tiếp tục chạy sau khi tôi gập laptop?

Hãy chạy nó bên trong tmux trên VPS. Khởi chạy agent trong một session có tên bằng tmux new -s opencode, detach bằng Ctrl-b rồi d, và session sẽ tiếp tục chạy trên server sau khi kết nối SSH kết thúc. Bạn có thể reattach bất cứ lúc nào bằng tmux attach -t opencode và cuộc hội thoại cùng tác vụ đang chạy vẫn còn đó. Một lần reboot server sẽ kết thúc session, vì vậy hãy khởi động một session mới sau khi reboot.

Chạy OpenCode để nó thực thi command trên VPS của tôi có an toàn không?

Nó có thể kiểm soát được nếu bạn cô lập nó. Hãy cấp cho OpenCode một user riêng biệt không có sudo, giữ các project trong git để mọi thay đổi đều có thể đảo ngược, lưu API key trong file với mode 600, và sử dụng agent Plan để chạy thử ở chế độ read-only trước khi bạn cho phép agent Build thay đổi bất cứ thứ gì. Khi đó agent chỉ có thể gây hại cho những gì account của nó sở hữu, và phần còn lại của server sẽ nằm ngoài tầm với.

Sự khác biệt giữa OpenCode và Claude Code là gì?

OpenCode là mã nguồn mở (MIT) và không phụ thuộc vào provider, kết nối với hơn 75 model provider, bao gồm cả các provider local, thông qua một giao diện duy nhất. Claude Code là agent terminal của chính Anthropic, được xây dựng xoay quanh các model của Anthropic. Nếu bạn muốn một công cụ dùng cho nhiều provider, hoặc một stack tự host hoàn toàn với model local, OpenCode là lựa chọn phù hợp; cả hai đều chạy tốt trên VPS bên trong tmux với cùng một thiết lập unprivileged-user.