OpenCode: cài đặt, mô hình và lần khởi chạy đầu tiên

OpenCode là một tác tử lập trình AI mã nguồn mở dành cho terminal: bản thân công cụ miễn phí (giấy phép MIT), và bạn có thể kết nối bất kỳ mô hình nào — từ Claude và GPT đến mô hình cục bộ thông qua Ollama. Kho dự án đã vượt mốc hai trăm nghìn sao trên GitHub. Cụm từ “Claude Code miễn phí với mọi mô hình” nghe hấp dẫn, nhưng cần làm rõ: công cụ miễn phí; điều khoản sử dụng phụ thuộc vào mô hình bạn chọn.

Dưới đây là mọi thông tin theo tài liệu chính thức: công cụ này là gì, cách cài đặt trên macOS, Linux hoặc Windows, cách kết nối mô hình và việc cần làm khi khởi chạy lần đầu. Có một phần riêng về chi phí, vì “miễn phí” ở đây chỉ áp dụng cho công cụ: các mô hình có tính phí và đó là điều thường gây nhầm lẫn nhất.

Thông tin thực tế về cách làm việc với Ailoot có trong tài liệu.

OpenCode là gì, nói một cách đơn giản?#

Nói ngắn gọn, OpenCode làm được những việc tương tự Claude Code: nhận yêu cầu bằng ngôn ngữ thông thường và thực hiện trong dự án của bạn. Hai công cụ khác nhau ở hai điểm. Mã nguồn hoàn toàn mở nên bạn có thể đọc và kiểm tra. Ngoài ra, công cụ không bị ràng buộc với một nhà cung cấp mô hình duy nhất: nó hoạt động với hơn 75 nhà cung cấp, từ Anthropic và OpenAI đến mô hình cục bộ chạy trên phần cứng của bạn.

Dự án do nhóm Anomaly phát triển. Kho mã được tạo ngày 30 tháng 4 năm 2025 và tính đến ngày 4 tháng 10 năm 2026 có hơn 211 nghìn sao và 28 nghìn forks (đã xác minh bằng yêu cầu GitHub API). Ngôn ngữ lập trình là TypeScript. Tài liệu được cập nhật liên tục, vì vậy hướng dẫn dưới đây dựa trên phiên bản hiện tại.

Đừng nhầm lẫn các tên gọi: gói npm thuộc dòng hiện tại có tên opencode-ai, kho mã là anomalyco/opencode, còn lệnh terminal đơn giản là opencode. Các bài viết cũ có thể dùng địa chỉ sst/opencode: tổ chức đã đổi tên và liên kết cũ hiện chuyển hướng đến địa chỉ mới.

Cập nhật ngày 4 tháng 10 năm 2026: nhóm đã phát hành OpenCode 2.0, thế hệ lớn tiếp theo của công cụ. Hướng dẫn cài đặt và kết nối mô hình dưới đây vẫn dành cho dòng 1.x hiện tại (cài đặt bằng lệnh curl -fsSL https://opencode.ai/install | bash; phiên bản hiện tại tính đến ngày 30 tháng 9 năm 2026 là 1.18.34): phiên bản này vẫn được hỗ trợ tích cực và là phiên bản mà tài liệu chính thức tại opencode.ai/docs cài đặt. Phần riêng bên dưới trình bày chính xác những thay đổi trong phiên bản thứ hai và thời điểm nên chuyển sang phiên bản này.

OpenCode khác Claude Code và Codex như thế nào?#

Nếu bạn đã có gói đăng ký Claude, tiếp tục dùng Claude Code làm công cụ chính là hợp lý — chúng tôi có hướng dẫn cài đặt chi tiết về công cụ này. OpenCode phù hợp trong ba trường hợp: bạn muốn làm việc qua gói ChatGPT Plus hoặc GitHub Copilot, muốn chạy mô hình cục bộ mà không tốn phí API, hoặc muốn dùng một giao diện duy nhất cho nhiều mô hình. Chúng tôi cũng có bài đánh giá và hướng dẫn cài đặt Codex.

Nếu vẫn đang chọn công cụ, hãy bắt đầu với phần tổng quan này: mọi người dùng gì để lập trình trong năm 2026. Nếu OpenCode đã được cài đặt và bạn cần kết nối nó với các tác tử khác trong Devin Desktop thông qua ACP, hãy xem hướng dẫn thiết lập đó.

OpenCode 2.0 có gì mới?#

Cài phiên bản thứ hai bằng lệnh curl -fsSL https://opencode.ai/v2/install | bash. Theo hướng dẫn di chuyển chính thức (opencode.ai/v2/docs/migrate-v1), cả hai phiên bản đều dùng cùng lệnh opencode và theo mặc định không còn được cài song song: trình cài đặt v2 thay thế tệp nhị phân v1, và trước khi cài v2 qua trình quản lý gói, tài liệu yêu cầu rõ ràng phải gỡ phiên bản v1 trước. Tuy nhiên, cấu hình vẫn được đọc từ cùng các tệp — ~/.config/opencode/ và <project>/.opencode/ — vì vậy các thiết lập, tác tử và máy chủ MCP được chuyển sang mà không cần viết lại. Có ba thứ cần viết lại: plugin (có API mới), tích hợp với server API (giao thức đã thay đổi) và cài đặt terminal (giờ dùng một tệp cli.json chung thay cho nhiều tệp tui.json).

Hai tính năng mới đáng chú ý nhất trong v2 là: thứ nhất, Console — dịch vụ trả phí dành cho nhóm, có theo dõi mức sử dụng, ngân sách và chính sách dùng chung cho tất cả thành viên. Thứ hai, nhóm cuối cùng cũng công bố giá gói đăng ký Go: $10 mỗi tháng cho Go và $40 mỗi tháng cho Go Plus với hạn mức cao hơn (trang opencode.ai/go, được xác minh ngày 4 tháng 10 năm 2026). Trước đó, tài liệu chỉ nói đây là “gói đăng ký chi phí thấp” mà không nêu con số.

Nếu bạn mới bắt đầu và chỉ muốn cài tác tử, hãy làm theo hướng dẫn bên dưới; hướng dẫn này dành cho phiên bản đầu tiên hiện tại mà chính tài liệu khuyến nghị. Hãy cân nhắc v2 nếu bạn cần các tính năng plugin mới hoặc Console cho nhóm — nhưng hãy chuẩn bị viết lại một số plugin cũ để dùng API mới. Nếu bạn quan tâm hơn đến một ứng dụng máy tính mã nguồn mở không cần terminal, chúng tôi có bài đánh giá ZCode, một tác tử tương tự khác có giao diện riêng.

Cần chuẩn bị gì trước khi cài đặt?#

Nói thêm một chút về terminal, vì đây là nơi duy nhất mà quá trình cài đặt có thể không diễn ra như dự tính. OpenCode hiển thị giao diện đầy đủ với các bảng và phần tô sáng trong terminal, nên tài liệu yêu cầu trình giả lập hiện đại. Nếu giao diện trông không đúng sau khi khởi chạy, trước tiên hãy cài một trong bốn lựa chọn được nêu: WezTerm (hoạt động trên mọi hệ thống), Alacritty, Ghostty hoặc Kitty. Trên Windows, cách chính là thông qua WSL; phần này được trình bày riêng bên dưới.

Thứ hai là mô hình. OpenCode hoạt động thông qua mô hình mà bạn kết nối: bản thân nó không xử lý yêu cầu. Có bốn lựa chọn: gói đăng ký (ChatGPT Plus, GitHub Copilot, GitLab Duo), khóa API từ bất kỳ nhà cung cấp nào, OpenCode Zen — dịch vụ tổng hợp của chính nhóm — hoặc mô hình cục bộ thông qua Ollama. Cả bốn lựa chọn được trình bày trong phần kết nối mô hình.

Nếu không có mô tả dự án, tác tử phải đoán các lệnh build, cấu trúc tệp và quy ước đang dùng — từ đó dẫn đến “ảo giác”. OpenCode dùng tệp AGENTS.md cho việc này. Cách tiếp cận tương tự áp dụng cho Claude Code và mọi tác tử khác; chỉ tên tệp hướng dẫn là thay đổi.

Cài OpenCode trên macOS và Linux như thế nào?#

Cách được khuyến nghị là dùng trình cài đặt chính thức:

1. Chạy trình cài đặt

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

   Tập lệnh phát hiện hệ thống của bạn và tải OpenCode xuống. Nếu sau khi cài đặt không tìm thấy lệnh, hãy đóng rồi mở lại terminal; đường dẫn sẽ được nhận diện trong phiên mới.

2. Kiểm tra cài đặt thành công

   opencode --version
   

   Lệnh trả về số phiên bản, nghĩa là cài đặt thành công. Nếu nhận được phản hồi “command not found”, hãy quay lại bước đầu tiên: mở phiên terminal mới hoặc tự chỉnh sửa PATH.

Nếu muốn tự quản lý gói, bạn có thể chọn:

brew install anomalyco/tap/opencode

npm install -g opencode-ai

Lệnh Homebrew cố ý bắt đầu bằng anomalyco/tap/: tài liệu khuyến nghị tap riêng của họ vì nhóm Homebrew cập nhật công thức cho brew install opencode ít thường xuyên hơn. Cùng một tên gói opencode-ai cũng hoạt động với bun, pnpm và yarn (bun install -g opencode-ai, yarn global add opencode-ai). Trên Arch Linux, dùng sudo pacman -S opencode từ kho stable hoặc paru -S opencode-bin để cài phiên bản mới nhất từ AUR.

Cập nhật OpenCode bằng opencode upgrade; khi khởi chạy, công cụ cũng tự tải bản cập nhật nếu bật tính năng cập nhật tự động. Sau khi cập nhật, kiểm tra phiên bản bằng lệnh quen thuộc opencode --version. Công cụ cũng có sẵn lệnh gỡ cài đặt:

opencode uninstall

Lệnh hiển thị chính xác những gì sẽ bị xóa và yêu cầu xác nhận. Nếu muốn, bạn có thể giữ lại cấu hình và dữ liệu phiên làm việc bằng các cờ --keep-config và --keep-data.

Cài OpenCode trên Windows như thế nào?#

Lựa chọn đầu tiên do chính nhà phát triển khuyến nghị là WSL. Cài đặt bằng một lệnh trong PowerShell chạy với quyền quản trị viên:

wsl --install

Sau khi khởi động lại, mở Ubuntu từ menu Start và chạy lệnh quen thuộc bên trong:

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

Các tệp trên ổ đĩa Windows có thể truy cập trong WSL qua /mnt/ — ổ C: ở /mnt/c/, còn ổ D: ở /mnt/d/. Vì vậy, có thể mở dự án tại C:\Users\Name\project như sau:

cd /mnt/c/Users/Name/project
opencode

Lựa chọn thứ hai là bỏ qua WSL và dùng trình quản lý gói Windows. Trong PowerShell:

choco install opencode

scoop install opencode

Lựa chọn thứ ba là ứng dụng máy tính và phiên bản web. Ứng dụng cài đặt như một chương trình thông thường và hiển thị giao diện trong cửa sổ mà không cần terminal. Phiên bản web khởi chạy bằng lệnh opencode web: lệnh mở OpenCode trong trình duyệt và tài liệu cũng khuyến nghị chạy từ WSL để tránh sự cố truy cập tệp. Tài liệu còn liệt kê các lựa chọn ít phổ biến hơn — mise, Docker và tệp nhị phân dựng sẵn từ trang phát hành GitHub. Việc cài qua bun trên Windows vẫn đang được triển khai; nếu bun là trình quản lý gói chính của bạn, hãy dùng lựa chọn npm.

Kết nối mô hình với OpenCode như thế nào?#

OpenCode hỗ trợ hơn 75 nhà cung cấp thông qua AI SDK và Models.dev, cùng với các mô hình cục bộ. Phần lớn được kết nối bằng lệnh /connect trong giao diện; với mô hình cục bộ, bạn cũng chỉ định địa chỉ máy chủ trong cấu hình. Các lựa chọn khác nhau về cách thanh toán và yêu cầu đối với máy tính:

Tài liệu khuyên người mới bắt đầu với OpenCode Zen. Nhóm đã chọn các mô hình hoạt động tốt cụ thể trong vai trò tác tử và thử nghiệm cách kết hợp chúng với nhà cung cấp bằng các tác vụ của chính nhóm.

Cách kết nối: nhập /connect, chọn OpenCode Zen, đăng nhập và thêm phương thức thanh toán tại opencode.ai/auth, lấy khóa rồi dán vào. Sau đó /models sẽ hiển thị danh sách mô hình được đề xuất. Tính đến ngày 4 tháng 10 năm 2026, danh sách có, chẳng hạn, GPT 6.1 Sol, GPT 6 Astra, Claude Opus 5.5, Claude Sonnet 5, GLM 5.3 và Kimi K2.5. Tài liệu cảnh báo rõ rằng danh sách không đầy đủ và nhanh chóng lỗi thời vì mô hình mới ra mắt mỗi tuần.

Kết nối gói đăng ký bằng cùng lệnh /connect: chọn ChatGPT Plus hoặc GitHub Copilot trong danh sách rồi đăng nhập tài khoản — không cần thiết lập thêm.

Nếu chọn Anthropic, /connect đưa ra hai lựa chọn: nhập khóa API thủ công hoặc chọn Claude Pro/Max rồi xác thực qua trình duyệt. Tuy nhiên, Anthropic cấm plugin bên thứ ba dùng gói đăng ký Claude Pro/Max, và các plugin tích hợp thuộc loại này đã bị gỡ khỏi OpenCode từ phiên bản 1.3.0. Nếu bạn gặp bài viết cũ về “OpenCode thông qua gói đăng ký Claude”, bài viết đó nói đến những plugin đã bị gỡ chứ không phải ủy quyền chính thức. Các gói ChatGPT Plus, GitHub Copilot, GitLab Duo (được đánh dấu là thử nghiệm) và Atomic Chat dùng được mà không cần thiết lập thêm.

OpenCode lưu khóa bạn nhập qua /connect trong tệp ~/.local/share/opencode/auth.json. Nếu không muốn chọn mô hình mỗi lần, hãy đặt mô hình mặc định trong tệp cấu hình opencode.json ở thư mục gốc của dự án:

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

Định dạng là provider/model; cả hai mã định danh đều hiển thị trong kết quả /models.

Kết nối mô hình cục bộ qua Ollama như thế nào?#

Lựa chọn này có nghĩa là hoàn toàn không tốn phí API: mô hình chạy trên máy tính của bạn. Nếu đang chọn các mô hình miễn phí nói chung, chúng tôi có bài đánh giá riêng về những mô hình hoạt động khá tốt như tác tử và những mô hình chỉ làm được điều đó trên lý thuyết. Để dùng OpenCode, hãy cài Ollama từ trang chính thức rồi tải một mô hình:

ollama pull qwen3-coder

Một chi tiết hữu ích trong tài liệu: Ollama có thể tự cấu hình để dùng với OpenCode và có hướng dẫn tích hợp riêng. Nếu muốn thiết lập mọi thứ thủ công, hãy thêm nhà cung cấp cùng địa chỉ máy chủ Ollama cục bộ vào opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder": {
          "name": "Qwen3 Coder"
        }
      }
    }
  }
}

Sau đó /models trong giao diện sẽ liệt kê mô hình cục bộ. Chọn mô hình rồi bắt đầu làm việc. Một lưu ý thực tế trong tài liệu: nếu tác tử ngừng gọi công cụ (chỉnh sửa tệp hoặc chạy lệnh), hãy tăng num_ctx trong cài đặt Ollama — bắt đầu với giá trị 16k–32k. Mô hình cục bộ yếu hơn mô hình đám mây cụ thể ở khả năng làm việc như tác tử, và ngữ cảnh nhỏ khiến vấn đề trầm trọng hơn. Nếu phiên bản cục bộ không đủ đáp ứng, bạn có thể kết nối Qwen trên đám mây bằng khóa; hướng dẫn lấy khóa nằm trong bài cách lấy khóa API cho Qwen Code.

OpenCode và việc sử dụng có giá bao nhiêu?#

Mọi chi phí ở đây đều dành cho mô hình và có bốn trường hợp. Với khóa API hoặc Zen, bạn trả theo mức sử dụng thực tế; số tiền phụ thuộc vào lượng công việc của tác tử. Go là gói đăng ký cho các mô hình mở của nhóm OpenCode: $10 mỗi tháng cho Go và $40 mỗi tháng cho Go Plus với hạn mức cao hơn (đã xác minh trên trang opencode.ai/go vào ngày 4 tháng 10 năm 2026). Hạn mức phụ thuộc vào mô hình: chẳng hạn, Go cho phép khoảng 110 yêu cầu mỗi 5 giờ (440 mỗi tháng) với Kimi K3 và khoảng 26.000 yêu cầu mỗi 5 giờ với DeepSeek V4.1 Flash nhẹ hơn. Để truy cập một mô hình cụ thể vượt hạn mức, tài liệu nêu giá riêng ($15 mỗi tháng cho Kimi K3, $60 cho Go Plus). Xem trang gói đăng ký khi kết nối để biết danh sách đầy đủ các mô hình và hạn mức. Với ChatGPT Plus hoặc Copilot, các yêu cầu được tính trong gói đăng ký bạn đang trả tiền; chỉ cần nhớ rằng gói đăng ký cũng có giới hạn cường độ sử dụng riêng. Cuối cùng, yêu cầu tới mô hình cục bộ qua Ollama không mất phí — nhưng bạn cần máy tính đủ mạnh để chạy nhanh.

Nên làm gì khi khởi chạy lần đầu?#

Lần đầu khởi chạy — từ bên trong thư mục dự án:

cd path/to/project
opencode

Giao diện mở ra với một ô nhập liệu. Trước tiên, dùng lệnh /init: tác tử quét các tệp quan trọng trong kho, hỏi vài câu nếu cần và tạo tệp AGENTS.md — hướng dẫn về cấu trúc dự án, các lệnh cần chạy để build và kiểm thử, cùng các quy ước được sử dụng. Tài liệu khuyến nghị commit tệp này vào git; từ đó OpenCode sẽ dùng nó làm chỉ dẫn thường trực cho dự án. Xét về mục đích, AGENTS.md tương đương trực tiếp với CLAUDE.md trong hệ sinh thái OpenCode.

Thứ hai, hãy dùng chế độ Plan. Phím Tab chuyển đổi giữa hai tác tử chính: Build có toàn quyền truy cập tệp và lệnh, còn Plan dành cho phân tích và lập kế hoạch — theo mặc định, chỉnh sửa tệp và chạy lệnh bash trong chế độ Plan cần được bạn phê duyệt. Với tác vụ mới, tài liệu khuyên nên bắt đầu bằng một kế hoạch: đọc dự định của tác tử, sửa cách diễn đạt rồi mới chuyển lại sang Build bằng Tab.

Tài liệu đưa ra lời khuyên này:

Tác vụ càng cụ thể và bạn cung cấp càng nhiều ngữ cảnh thì càng ít phải làm lại. Thêm tệp vào yêu cầu bằng @ — bắt đầu nhập tên, giao diện sẽ tìm chúng bằng tìm kiếm gần đúng. Bạn có thể kéo ảnh trực tiếp vào terminal; tin nhắn bắt đầu bằng ! sẽ chạy như lệnh shell và kết quả được thêm vào ngữ cảnh của tác tử. Nếu bạn giao việc sai hoặc tác tử làm không đúng, /undo hoàn tác các thay đổi và có thể chạy liên tiếp nhiều lần. Đổi ý lần nữa? /redo khôi phục phần đã hoàn tác. Còn /share tạo liên kết cuộc trò chuyện cho nhóm; nếu không dùng lệnh này, cuộc trò chuyện sẽ không được đăng ở đâu cả.

OpenCode còn làm được gì?#

Lệnh tùy chỉnh. Có thể biến bất kỳ yêu cầu lặp lại nào thành lệnh: đặt tệp markdown trong .opencode/commands/, khai báo description, agent và model trong frontmatter rồi viết mẫu prompt bên dưới. Sau đó gọi lệnh bằng /. Kiểm tra dự án trước khi phát hành, xem lại lỗi gần đây, tạo migration — bất cứ việc gì bạn thường xuyên yêu cầu.

Tác tử phụ. Ngoài Build và Plan còn có ba tác tử: General dành cho tác vụ nhiều bước (truy cập mọi công cụ trừ danh sách tác vụ), Explore để đọc nhanh mã mà không có quyền chỉnh sửa, và Scout để nghiên cứu thư viện bên ngoài. Gọi chúng bằng cách nhắc tên trong tin nhắn với @.

Máy chủ MCP. Kết nối công cụ bên ngoài qua phần mcp trong tệp cấu hình opencode.json — hỗ trợ cả máy chủ cục bộ và từ xa. Mỗi máy chủ MCP bổ sung công cụ của nó vào ngữ cảnh; một máy chủ ngốn nhiều ngữ cảnh như GitHub có thể dùng hết ngữ cảnh rất nhanh — hãy kết nối có chọn lọc, chỉ những gì bạn cần. Chúng tôi có hướng dẫn với các cấu hình sẵn dùng về khái niệm MCP; hướng dẫn viết về Claude Code nhưng giao thức được dùng chung.

Phiên bản web và máy chủ. opencode web mở giao diện trong trình duyệt. Để truy cập từ máy khác, dùng opencode serve --hostname 0.0.0.0 --port 4096; hễ có quyền truy cập mạng, hãy nhớ đặt mật khẩu bằng biến OPENCODE_SERVER_PASSWORD. Không có mật khẩu thì máy chủ không được bảo vệ.

Cài đặt gặp trục trặc thì nên làm gì?#

Sau khi cài đặt, xuất hiện “opencode: command not found”. Terminal chưa nhận biết đường dẫn mới. Trước hết, hãy đóng rồi mở lại terminal. Nếu vẫn không được, tìm nơi trình cài đặt đặt tệp nhị phân và thêm thư mục đó vào PATH của terminal.

Mô hình im lặng hoặc báo lỗi ủy quyền. Kiểm tra xem nhà cung cấp đã kết nối chưa: nhập /connect rồi xác thực lại. Khóa được lưu trong ~/.local/share/opencode/auth.json — nếu bạn chuyển cài đặt từ máy khác hoặc xóa thư mục, tệp này có thể bị thiếu. Tài liệu hướng dẫn riêng về lỗi ProviderInitError và AI_APICallError: với lỗi thứ nhất, xác thực lại nhà cung cấp; với lỗi thứ hai, xóa thư mục ~/.cache/opencode rồi khởi động lại.

Giao diện bị lỗi: các bảng phân tán hoặc ký tự khó đọc xuất hiện thay cho biểu tượng. Trước tiên, hãy kiểm tra terminal. Cài một trong các lựa chọn được khuyến nghị — WezTerm hoạt động trên cả ba hệ thống — rồi khởi chạy OpenCode từ đó.

Nếu vẫn không giải quyết được, hãy xem nhật ký: trên macOS và Linux, nhật ký nằm trong ~/.local/share/opencode/log/; trên Windows, nhấn Win+R rồi nhập %USERPROFILE%\.local\share\opencode\log. Hệ thống giữ lại mười tệp mới nhất; bật ghi nhật ký chi tiết bằng cờ opencode --log-level DEBUG. Với các nhật ký này, bạn có thể gửi báo cáo lỗi trong kho GitHub của dự án.

Mọi người còn hỏi gì về OpenCode?#

Truy cập Ailoot.