Bởi Matt Connor
Cách chạy OpenCode trên VPS an toàn với tmux
Cài OpenCode trên VPS dưới user không đặc quyền, chạy trong tmux để giữ session và khóa API key trong file riêng tư. Hỗ trợ hơn 75 model provider.
OpenCode là gì và bạn đang thiết lập gì
OpenCode là AI coding agent mã nguồn mở được thiết kế cho terminal. Bạn khởi động nó bên trong thư mục dự án. Nó đọc code, đề xuất thay đổi, chỉnh sửa file và chạy command, tất cả trong terminal user interface (TUI). OpenCode dùng giấy phép MIT, kết nối với hơn 75 model provider và có khoảng 219,000 GitHub star tính đến tháng 10 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 VPS, bạn cài nó dưới một user không có quyền đặc biệt, đặt model API key trong một file riêng tư và khởi động nó bên trong tmux để session vẫn hoạt động khi kết nối bị ngắt. Guide này thực hiện đúng theo thứ tự đó.
Một lưu ý về tên gọi sẽ giúp tránh nhầm lẫn. Repository chính thức là anomalyco/opencode, do team Anomaly duy trì, trước đây có tên là SST. Dự án từng ở sst/opencode. Trên GitHub cũng có một repository không liên quan tên opencode-ai/opencode, hiện đã được archive. Vì vậy, hãy kiểm tra để chắc chắn bạn đang đọc tài liệu của đúng dự án. Trang web chính thức là opencode.ai.
Vì sao nên chạy OpenCode trên VPS
Một phiên làm việc với coding agent thường kéo dài. OpenCode có thể mất nhiều phút để xử lý một đợt refactor hoặc chạy một test suite. Nếu chạy trên laptop, việc đóng nắp máy hoặc mất kết nối Wi-Fi sẽ làm phiên bị dừng giữa chừng. Khi chạy agent trên VPS bên trong tmux, agent vẫn tiếp tục làm việc sau khi bạn ngắt kết nối. Sau đó, bạn có thể kết nối lại để xem agent đã thực hiện những gì. Đây cũng là cách chạy Claude Code trên VPS với tmux, và là lợi ích lớn nhất về trải nghiệm khi chuyển agent khỏi laptop.
Lý do thứ hai là vị trí. VPS ở gần code bạn deploy: repository, công cụ build, test database và thường cả môi trường staging đã nằm trên đó hoặc ở máy kế bên. Agent chỉnh sửa code và chạy test sẽ hoạt động hiệu quả nhất trên chính máy đang chạy các test đó. Vì đây là server do bạn kiểm soát, bạn có thể chủ động cấp cho agent một môi trường được cô lập. Phần tiếp theo sẽ thực hiện việc này.
Nếu bạn vẫn đang chọn công cụ, chạy coding AI agent trên VPS sẽ so sánh nhiều lựa chọn hơn, bao gồm Aider và Goose.
Cấp cho OpenCode một user riêng
Hãy bắt đầu từ thực tế: coding agent chỉnh sửa file và chạy command. Đó là nhiệm vụ của nó, đồng thời cũng là rủi ro. OpenCode sẽ chạy các bản build, test và mọi shell command mà task có vẻ cần; phán đoán của model tốt nhưng không hoàn hảo. Account mà agent chạy dưới đó giới hạn mức độ mà một command nguy hiểm có thể tác động, vì vậy không chạy agent bằng root và cũng không dùng cùng user đang quản trị server.
Không giống background agent, OpenCode chạy tương tác, nên user của nó cần có shell thực và home directory:
sudo useradd --create-home --shell /bin/bash opencode
sudo -iu opencodeĐặt các project bạn muốn OpenCode xử lý bên dưới /home/opencode và clone chúng bằng user đó. Không cấp quyền sudo cho account này. Nếu agent chạy một command phá hoại, nó chỉ có thể phá những gì account này sở hữu. Đây cũng là nguyên tắc giống như chạy service bằng user không có đặc quyền. Đồng thời, hãy làm việc trong một git repository và commit trước khi giao task cho agent, vì khi đó một chỉnh sửa sai vào phần đã commit chỉ còn cách khôi phục bằng git revert hoặc git restore thay vì mất dữ liệu. Các thay đổi chưa được commit không được bảo vệ.
Cài đặt OpenCode
Dự án có tài liệu hướng dẫn nhiều cách cài đặt. Trong đó có 2 cách phù hợp với server. Install script là cách nhanh nhất. Chạy script dưới user opencode sẽ giữ mọi thứ bên trong home của user đó:
curl -fsSL https://opencode.ai/install | bashThói quen curl | bash thông thường cũng áp dụng ở đây. Với server quan trọng, trước hết hãy download script, đọc nội dung, rồi mới chạy nó. Sau khi cài đặt, hãy mở một shell mới để thay đổi PATH do installer thực hiện có hiệu lực. Sau đó kiểm tra binary:
opencode --versionNếu thích dùng package manager và Node.js đã có trên máy, cách cài qua npm sẽ cài cùng tool đó vào global prefix của npm:
sudo npm install -g opencode-aiVới Node.js được cài trên toàn hệ thống, prefix đó thường là /usr/local hoặc /usr. Thư mục bin của prefix nằm trong PATH của mọi user. Version manager hoặc prefix tùy chỉnh có thể đặt binary ở nơi khác. Vì vậy, hãy chạy npm prefix -g trước nếu cần để user opencode tìm thấy opencode.
Dù dùng cách nào, bước kiểm tra vẫn giống nhau: opencode --version sẽ in ra số version. Nếu thấy command not found sau khi cài bằng script, shell hiện tại chưa đọc PATH mới. Hãy logout rồi login lại bằng user opencode.
Cả 2 command đều cài dòng OpenCode 1.x. Dòng này vẫn phát hành các bản release, trong đó có bản 1.19.3 vào ngày 16 tháng 10 năm 2026. Guide này mô tả dòng 1.x. OpenCode 2 hiện đã được phát hành dưới dạng bản cài đặt riêng, từ https://opencode.ai/v2/install hoặc package npm @opencode/cli. Nó hoạt động khác: một background server dùng chung cho từng user account sẽ quản lý session, permission và việc thực thi tool. Terminal sẽ kết nối đến server đó. Migration guide yêu cầu gỡ bản 1.x được cài bằng package manager trước khi cài bản 2, vì cả 2 đều dùng command opencode.
Đặt API key trong file riêng tư
OpenCode cần key cho model provider bạn sử dụng. Key đó có thể tiêu tiền của bạn, nên hãy bảo vệ nó như password. Tạo một file chỉ user opencode có thể đọc, với mode 600. Lưu key trong file đó thay vì nhập vào command, vì key có thể bị ghi vào shell history:
install -m 600 /dev/null ~/opencode.env
nano ~/opencode.envĐặt biến của provider vào file, ví dụ ANTHROPIC_API_KEY=... hoặc biến tương đương của provider đó. OpenCode sẽ đọc các biến môi trường chuẩn của provider. Load file vào shell trước khi khởi động agent:
set -a; source ~/opencode.env; set +aOpenCode cũng có cách tương tác khác: command /connect 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 dùng cách này, hãy xác nhận file là private bằng chmod 600 ~/.local/share/opencode/auth.json. Cả hai cách đều giữ key khỏi command line. Hãy chọn một cách và sử dụng nhất quán.
Khởi động OpenCode trong tmux
tmux là thành phần khiến việc thiết lập VPS trở nên đáng làm, 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 tạo một session, chuyển đến project của bạn rồi khởi động agent:
tmux new -s opencode
cd ~/my-project
opencodeBạn sẽ thấy TUI mở ra, có prompt ở phía dưới và tên project trong giao diện. Hãy giao nhiệm vụ bằng ngôn ngữ thông thường. Agent sẽ bắt đầu đọc file và đề xuất thay đổi. Khi muốn rời đi, hãy detach bằng Ctrl-b rồi d. Agent vẫn tiếp tục làm việc ngay cả khi bạn đóng laptop. Sau đó reattach bằng:
tmux attach -t opencodesession, cuộc trò chuyện và mọi task đang chạy vẫn ở đúng trạng thái trước đó. Cách này chịu được việc bạn mất kết nối, nhưng không chịu được server reboot. Sau khi reboot, bạn cần tạo một tmux session mới theo cách tương tự. Bạn cũng có thể mở cửa sổ tmux thứ hai và chạy một agent khác song song với agent đầu tiên. Tuy nhiên, các OpenCode session độc lập với nhau, trong khi các Claude Code session trên cùng một máy có thể gửi message cho nhau. Đây là một cách khác để chia một công việc thành hai phần.
Trỏ đến một model
OpenCode không phụ thuộc vào provider cụ thể. Nó sử dụng AI SDK và catalog Models.dev để hỗ trợ hơn 75 provider, nên cùng một công cụ hoạt động với Anthropic, OpenAI, Google và hàng chục provider khác, bao gồm cả server chạy cục bộ. Cách nhanh nhất là dùng lệnh /connect trong TUI; lệnh này liệt kê các provider và xử lý credential. Nếu muốn có cấu hình có thể commit và tái tạo, hãy đặt một opencode.json trong thư mục gốc của project và đặt model bằng provider/model-id:
{
"$schema": "https://opencode.ai/config.json",
"model": "anthropic/claude-sonnet-5-5"
}Chọn một model mà provider của bạn vẫn đang cung cấp: Anthropic đã ngừng cung cấp claude-sonnet-4-20250514 vào ngày 15 June 2026, nên các cấu hình vẫn khai báo model này sẽ fail.
Model cục bộ cũng hoạt động qua cùng file đó, vì bất kỳ server tương thích với OpenAI nào cũng có thể được khai báo thành một provider. Nếu bạn chạy một model bằng Ollama trên cùng VPS, cấu hình sẽ trỏ đến API cục bộ của nó, còn tên model là giá trị 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 tích hợp sẵn đáng áp dụng ngay từ đầu. OpenCode cung cấp 2 agent và bạn chuyển đổi giữa chúng bằng phím Tab: Build, agent mặc định có toàn quyền truy cập, và Plan, agent bị giới hạn để phân tích, từ chối chỉnh sửa file bên ngoài chính thư mục plan của nó mà không hỏi trước. Plan không hoàn toàn chỉ đọc, vì nó vẫn có thể chạy shell command, và shell command có thể thay đổi file. Hãy bắt đầu task mới trong Plan, để nó đọc code và đề xuất cách thực hiện, rồi chỉ chuyển sang Build khi bạn đồng ý với plan. Nếu muốn lượt chạy đầu tiên thực sự chỉ đọc, hãy chặn quyền chỉnh sửa và chạy shell command của Plan trong opencode.json, vì OpenCode coi deny là chặn hành động, còn ask chỉ yêu cầu bạn phê duyệt:
{
"$schema": "https://opencode.ai/config.json",
"agent": {
"plan": {
"permission": { "edit": "deny", "bash": "deny" }
}
}
}Trên server, lượt chạy đầu tiên không thể thay đổi bất cứ thứ gì là một biện pháp bảo vệ ít tốn kém. Claude Code diễn đạt cùng quyết định đó dưới dạng permission mode thay vì agent, và việc chuyển sang auto mode làm mặc định của nó đáng để đọc nếu bạn chạy cả 2 công cụ, vì mode mà session khởi động sẽ quyết định agent không được giám sát có thể thay đổi bao nhiêu.
Phạm vi ảnh hưởng, nói thẳng
Coding agent không thụ động, vì vậy cần nói rõ thiết lập này kiểm soát được và không kiểm soát được điều gì. Thiết lập này giới hạn được hư hại đối với file: user opencode sở hữu home directory của chính nó và không sở hữu gì khác, nên việc chỉnh sửa và xóa chỉ diễn ra trong phạm vi đó. Thiết lập này vẫn để lộ credential: key nằm trong một file có mode 600 và thuộc một account duy nhất. Thiết lập này không giới hạn những gì account có thể thực hiện hợp lệ. Vì vậy, nếu project directory chứa credential để deploy production, agent có thể sử dụng chúng; hãy để các credential đó hoàn toàn bên ngoài account của agent.
Không giống gateway agent như OpenClaw, OpenCode 1.x là chương trình terminal tương tác, không phải daemon. Theo mặc định, nó không mở listening port nào (chỉ các flag --port, --hostname hoặc --mdns mới khiến TUI listen) và không có service chạy lâu dài. Vì vậy, không cần viết systemd unit và cũng không cần cấu hình firewall cho một port của chính agent. OpenCode 2 thay đổi điểm này bằng shared background server, vì vậy hãy kiểm tra lại trước khi migrate. Cơ chế containment nằm ở user account và project directory. Đây là lý do section đầu tiên của hướng dẫn này quan trọng nhất.
Phần hệ thống bao quanh agent vẫn cần được quản trị theo cách tiêu chuẩn, vì coding VPS vẫn là public server: SSH chỉ dùng key và tắt root login, như trong Hardening SSH trên VPS, firewall mặc định deny, và cập nhật định kỳ. Đồng thời, hãy review những gì agent tạo ra. Đọc diff trước khi push, giống như khi đọc 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 luôn cập nhật chính tool này. OpenCode thường xuyên release phiên bản mới, và các bản cập nhật có những bản sửa quan trọng đối với chương trình chạy command trên server của bạn. Cập nhật bằng đúng cách đã dùng khi cài đặt: chạy lại install script vớ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. Cả hai cách vẫn giữ bạn ở nhánh 1.x; chuyển sang OpenCode 2 là một migration riêng. Thỉnh thoảng dành một phút để bảo trì sẽ rẻ hơn việc debug hành vi mà một build đã quá cũ đã được sửa từ nhiều tháng trước.
FAQ
OpenCode có thể dùng model local thay cho API trả phí không?
Có. OpenCode xem mọi server tương thích với OpenAI là một provider, nên model do Ollama cung cấp trên cùng VPS cũng hoạt động: khai báo provider trong opencode.json cùng với baseURL local và tên model mà Ollama báo cáo. Điểm cần lưu ý là phần cứng, vì model đủ tốt cho công việc lập trình thực tế cần nhiều memory. Hãy chọn cấu hình server phù hợp với model trước khi tải model xuống.
Làm cách nào để OpenCode tiếp tục chạy sau khi tôi đóng laptop?
Chạy OpenCode bên trong tmux trên VPS. Khởi động agent trong một session có tên bằng tmux new -s opencode, detach bằng Ctrl-b rồi d. 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ể attach lại bất cứ lúc nào bằng tmux attach -t opencode; conversation và mọi task đang chạy vẫn còn đó. Reboot server sẽ kết thúc session, nên hãy tạo session mới sau khi reboot.
Cho phép OpenCode chạy command trên VPS có an toàn không?
Có thể kiểm soát được nếu bạn cô lập nó. Cấp cho OpenCode một user không có đặc quyền và không có sudo, lưu project trong git và commit trước mỗi task để có thể rollback khi chỉnh sửa lỗi, lưu API key trong file có mode 600, đồng thời dùng agent Plan để kiểm tra bước đầu trước khi cho agent Build thay đổi bất cứ thứ gì. Nếu muốn bước kiểm tra này hoàn toàn chỉ đọc, hãy đặt phần chỉnh sửa và shell command thành deny cho Plan. Agent khi đó chỉ có thể gây ảnh hưởng đến những gì account của nó sở hữu, còn phần còn lại của server vẫn nằm ngoài phạm vi truy cập.
OpenCode khác Claude Code như thế nào?
OpenCode là phần mềm nguồn mở (MIT) và không phụ thuộc provider, kết nối với hơn 75 model provider, bao gồm cả provider local, thông qua một interface. Claude Code là terminal agent của Anthropic, được xây dựng quanh các model của Anthropic. Nếu bạn muốn dùng một tool với nhiều provider, hoặc một stack self-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 cách thiết lập user không có đặc quyền.