Việc cài đặt OpenCode đôi khi có thể gây bối rối khi lỗi thiết lập làm gián đoạn quá trình hoặc công cụ không chạy như mong đợi. Từ thiếu lệnh đến vấn đề tương thích Node.js, người dùng thường gặp khó khăn trong lần cài đặt đầu tiên. Hướng dẫn cài đặt OpenCode này cung cấp giải pháp đầy đủ để khắc phục các lỗi thường gặp và thiết lập OpenCode thành công trên Mac và Windows, dù bạn dùng Desktop hay CLI/TUI, để có thể bắt đầu lập trình mà không bị chậm trễ.
OpenCode là gì?
OpenCode là tác tử lập trình AI mã nguồn mở, được thiết kế để giúp nhà phát triển viết, chỉnh sửa, gỡ lỗi và quản lý mã trực tiếp trong môi trường họ ưa dùng, dù là terminal, IDE hay ứng dụng máy tính. Không giống các trợ lý lập trình AI truyền thống chủ yếu tập trung vào gợi ý mã, OpenCode có thể hiểu toàn bộ codebase, sửa đổi tệp, chạy lệnh và tự động hóa quy trình phát triển. Công cụ này cũng hỗ trợ nhiều mô hình AI và mô hình cục bộ, mang lại cho nhà phát triển sự linh hoạt và quyền kiểm soát cao hơn trong quá trình xây dựng phần mềm.
Điều kiện tiên quyết để cài đặt OpenCode
Trước khi cài đặt OpenCode, hãy đảm bảo hệ thống của bạn đáp ứng các yêu cầu cơ bản. Các điều kiện tiên quyết cụ thể tùy thuộc vào việc bạn định dùng ứng dụng máy tính hay giao diện dựa trên terminal, nhưng chuẩn bị đúng môi trường sẽ giúp quá trình cài đặt diễn ra suôn sẻ.
Dành cho Desktop
Hệ điều hành: macOS / Windows / Linux
OpenCode cung cấp ứng dụng máy tính cho các hệ điều hành phổ biến, cho phép nhà phát triển cài đặt và sử dụng công cụ trong môi trường họ ưa thích. Hãy đảm bảo hệ thống đang dùng hệ điều hành tương thích, như macOS (Apple Silicon hoặc Intel), Windows (x64) hoặc Linux (.deb, .rpm).
Quyền cài đặt ứng dụng: Bạn có thể cần quyền quản trị viên hoặc quyền cấp hệ thống để tải xuống và cài đặt phần mềm trên thiết bị. Điều này đặc biệt quan trọng trong môi trường làm việc hoặc môi trường IT được quản lý, nơi quyền cài đặt có thể bị hạn chế.
Kết nối internet ổn định: Cần có kết nối internet ổn định để tải OpenCode, cài đặt bản cập nhật và kết nối với các mô hình AI तथा dịch vụ được hỗ trợ trong quá trình thiết lập và sử dụng.
Dành cho Terminal/TUI
Quyền truy cập terminal: Có thể cài đặt và sử dụng OpenCode trực tiếp từ dòng lệnh. Hãy bảo đảm bạn có thể sử dụng một ứng dụng terminal, chẳng hạn như Terminal trên macOS, Command Prompt hoặc PowerShell trên Windows, hay shell Linux.
Một phương thức cài đặt: OpenCode hỗ trợ nhiều phương thức cài đặt để phù hợp với các hệ điều hành và sở thích khác nhau của nhà phát triển. Hãy chọn trình quản lý gói hoặc công cụ cài đặt phù hợp nhất với môi trường của bạn, chẳng hạn như npm, curl, brew, Scoop, Chocolatey hoặc WSL.
Kỹ năng dòng lệnh cơ bản: Việc quen thuộc với các lệnh terminal thông dụng có thể giúp quá trình cài đặt và sử dụng hằng ngày dễ dàng hơn nhiều. Không cần có kiến thức chuyên sâu, nhưng bạn nên hiểu cách điều hướng và thực thi lệnh cơ bản.
Cách cài đặt OpenCode Desktop?
Cài đặt OpenCode Desktop là một quy trình đơn giản, chỉ cần vài bước để đưa ứng dụng vào hoạt động. Hãy thực hiện theo các bước sau.
Bước 1: Tải OpenCode Desktop
Truy cập trang tải xuống chính thức của OpenCode và chọn phiên bản ứng dụng dành cho Windows hoặc macOS. Trình cài đặt sẽ tự động được tải về hệ thống của bạn. Để bảo đảm an toàn và tính xác thực, hãy chắc chắn bạn tải từ nguồn chính thức.
Bước 2: Chạy trình cài đặt
Tìm tệp trình cài đặt đã tải xuống rồi nhấp đúp để bắt đầu cài đặt. Làm theo hướng dẫn trên màn hình để hoàn tất thiết lập.
Bước 3: Hoàn tất cài đặt
Tiếp tục theo các lời nhắc thiết lập khi chúng xuất hiện và chọn thư mục cài đặt mong muốn khi được hỏi. Sau đó, để trình cài đặt hoàn tất quy trình thiết lập trên hệ thống của bạn.
Bước 4: Khởi chạy OpenCode Desktop
Sau khi cài đặt xong, hãy mở OpenCode Desktop từ Start Menu hoặc lối tắt trên màn hình nền. Sau đó, tạo dự án mới hoặc mở một thư mục hiện có để bắt đầu làm việc. Khi không gian làm việc đã được tải, bạn có thể tương tác với trợ lý AI để tạo mã, gỡ lỗi hoặc xây dựng tính năng ngay trong dự án của mình.
Cách cài đặt OpenCode Terminal/TUI trên Mac?
Bạn có thể cài đặt trực tiếp OpenCode Terminal (TUI) trên Mac bằng các trình quản lý gói chính thức hoặc một lệnh cài đặt một dòng. Công cụ này dành cho các nhà phát triển thích làm việc trong terminal thay vì giao diện đồ họa. Hãy thực hiện các bước sau để cài đặt OpenCode TUI trên Mac.
Bước 1: Chọn phương thức cài đặt OpenCode Terminal
Truy cập trang tải xuống chính thức của OpenCode và chuyển đến mục OpenCode Terminal. Tại đây có nhiều tùy chọn cài đặt, gồm curl, Homebrew, npm và bun. Hãy chọn phương thức phù hợp nhất với môi trường phát triển của bạn và sao chép lệnh cài đặt tương ứng.
Bước 2: Mở ứng dụng Terminal trên Mac
Khởi chạy ứng dụng Terminal trên máy Mac. Bạn có thể mở ứng dụng từ Applications > Utilities > Terminal hoặc nhanh chóng tìm bằng Spotlight Search. Đây là nơi bạn chạy lệnh cài đặt OpenCode.
Bước 3: Cài đặt OpenCode Terminal
Dán lệnh cài đặt sau vào Terminal rồi nhấn Enter:
curl -fsSL https://opencode.ai/install | bashChờ quá trình cài đặt hoàn tất. OpenCode sẽ tải các tệp cần thiết và tự động thiết lập CLI.
Bước 4: Khởi chạy giao diện Terminal của OpenCode
Sau khi cài đặt hoàn tất, hãy chạy lệnh OpenCode trong Terminal để khởi động Giao diện người dùng Terminal (TUI). Giao diện tương tác sẽ mở ngay trong cửa sổ terminal, cho phép bạn kết nối với nhà cung cấp AI, cấu hình cài đặt và bắt đầu làm việc với OpenCode.
Cách cài đặt Terminal/TUI OpenCode trên Windows?
OpenCode hỗ trợ nhiều phương thức cài đặt trên Windows, gồm WSL, npm và bun. Để có khả năng tương thích và trải nghiệm tốt nhất, tài liệu chính thức khuyến nghị sử dụng Windows Subsystem for Linux (WSL). Các bước dưới đây sử dụng phương thức cài đặt WSL. Nếu đã cài đặt WSL, bạn có thể bỏ qua bước đầu tiên.
Bước 1: Cài đặt WSL (khuyến nghị)
Mở PowerShell với quyền Quản trị viên, sau đó chạy lệnh sau:
wsl --installLệnh này kích hoạt Windows Subsystem for Linux (WSL) và cài đặt Ubuntu theo mặc định. Sau khi cài đặt hoàn tất, hãy khởi động lại máy tính. Lần đầu mở Ubuntu, Windows sẽ tự động hoàn tất việc thiết lập môi trường Linux.
Bước 2: Mở WSL và cài đặt OpenCode
Khởi chạy terminal WSL của bạn (chẳng hạn như Ubuntu) từ menu Start của Windows. Nếu đây là lần đầu bạn mở terminal, hãy hoàn tất thiết lập ban đầu. Sau đó chạy lệnh sau để cài đặt OpenCode:
curl -fsSL https://opencode.ai/install | bashChờ quá trình cài đặt hoàn tất rồi mới tiếp tục.
Bước 3: Xác minh cài đặt
Sau khi cài đặt hoàn tất, hãy chạy lệnh sau:
opencodeNếu Terminal/TUI OpenCode khởi chạy thành công, quá trình cài đặt đã hoàn tất và bạn có thể bắt đầu sử dụng OpenCode để lập trình với sự hỗ trợ của AI.
Cách tích hợp API bên ngoài vào OpenCode?
Một trong những ưu điểm chính của OpenCode là khả năng kết nối với các nhà cung cấp mô hình AI bên ngoài thông qua việc tích hợp API. Bằng cách thêm khóa API của riêng mình, bạn có thể truy cập các mô hình ngôn ngữ khác nhau và chọn mô hình phù hợp nhất với quy trình lập trình của mình.
Tích hợp API bên ngoài vào OpenCode (các bước chung)
Dưới đây là các bước để tích hợp API bên ngoài vào OpenCode:imi
Bước 1: Tạo tài khoản và tạo khóa API
Trước tiên, hãy tạo tài khoản với nhà cung cấp AI bạn muốn dùng, chẳng hạn như Kimi hoặc một dịch vụ được hỗ trợ khác. Sau khi thiết lập tài khoản, hãy chuyển đến trang quản lý khóa API của nhà cung cấp và tạo khóa API mới. Hãy bảo mật khóa này vì bạn sẽ cần nó để kết nối nhà cung cấp với OpenCode.
Bước 2: Mở menu kết nối nhà cung cấp
Khởi chạy OpenCode và mở không gian làm việc của bạn. Trong giao diện lệnh, hãy chạy lệnh sau:
/connectLệnh này mở menu kết nối nhà cung cấp, nơi bạn có thể thêm và quản lý các dịch vụ AI bên ngoài.
Bước 3: Thêm khóa API của bạn
Chọn nhà cung cấp bạn muốn sử dụng trong danh sách các tùy chọn hiện có. Khi được nhắc, hãy dán khóa API đã tạo trước đó và xác nhận kết nối. OpenCode sẽ lưu trữ khóa một cách an toàn và dùng khóa này để xác thực các yêu cầu gửi đến nhà cung cấp đã chọn.
┌ API key
│
│ your_api_key_here
│
└ enterBước 4: Xem các mô hình hiện có
Sau khi kết nối nhà cung cấp, hãy chạy lệnh sau để xem tất cả các mô hình có sẵn thông qua API đó:
/modelsOpenCode sẽ hiển thị danh sách các mô hình được hỗ trợ cùng tên và tùy chọn cấu hình của chúng.
Bước 5: Chọn một mô hình và bắt đầu sử dụng
Chọn mô hình bạn muốn làm việc từ danh sách có sẵn. Sau khi được chọn, OpenCode sẽ định tuyến các yêu cầu của bạn qua mô hình đó, cho phép bạn tạo mã, gỡ lỗi ứng dụng và thực hiện các tác vụ phát triển khác bằng API đã kết nối. Bạn có thể chuyển sang mô hình khác sau này nếu nhu cầu thay đổi.
Tích hợp Kimi API vào OpenCode
OpenCode hỗ trợ nhiều nhà cung cấp AI, cho phép nhà phát triển kết nối các mô hình bên ngoài bằng khóa API để linh hoạt hơn. Một trong những lựa chọn mạnh mẽ nhất là Kimi API.
Kimi API, do Nền tảng Mở Moonshot AI cung cấp, cho phép truy cập các mô hình ngôn ngữ Kimi tiên tiến qua giao diện tương thích với OpenAI. API này có thể dễ dàng tích hợp vào các công cụ lập trình, ứng dụng và quy trình làm việc dựa trên AI bằng khóa API bảo mật. Nền tảng cung cấp nhiều mô hình Kimi được tối ưu cho các tác vụ lập trình, suy luận và hiểu ngữ cảnh dài.
Hãy làm theo các bước sau để tích hợp Kimi API vào OpenCode.
Bước 1: Tạo tài khoản Moonshot AI và tạo khóa API
Truy cập Nền tảng Mở Kimi AI và đăng nhập vào tài khoản của bạn.
Từ bảng điều khiển, chuyển đến Khóa API rồi nhấp vào Tạo khóa API.
Sau khi khóa được tạo (bắt đầu bằng
sk-), hãy sao chép ngay và lưu trữ an toàn. Khóa chỉ được hiển thị một lần và dùng để xác thực các yêu cầu giữa OpenCode và Moonshot AI.
Bước 2: Kết nối Moonshot AI với OpenCode
Mở không gian làm việc OpenCode và chạy:
/connectTrình đơn kết nối nhà cung cấp sẽ xuất hiện. Tìm Moonshot AI (hoặc Kimi) trong danh sách các nhà cung cấp tích hợp sẵn rồi chọn. OpenCode sẽ yêu cầu bạn nhập khóa API.
Khi được nhắc, dán khóa API bạn đã tạo từ bảng điều khiển Moonshot AI rồi nhấn Enter:
┌ API key
│ sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
│
└ enterSau khi xác minh, OpenCode sẽ lưu thông tin xác thực một cách an toàn vào ~/.local/share/opencode/auth.json và liên kết thông tin này với cấu hình nhà cung cấp Moonshot AI của bạn.
Lưu ý: OpenCode lưu khóa API riêng với tệp cấu hình chính để bảo mật. Lệnh
/connectxử lý việc lưu trữ thông tin xác thực, còn hành vi của nhà cung cấp được cấu hình trongopencode.json.
Bước 3: Cấu hình nhà cung cấp trong opencode.json (nếu cần)
Nếu gặp lỗi No endpoints found sau khi kết nối, hoặc cần tùy chỉnh thiết lập nhà cung cấp, hãy thêm cấu hình Moonshot AI vào tệp opencode.json của bạn:
{"$schema": "https://opencode.ai/config.json","provider": {"moonshotai": {"name": "Moonshot AI","options": {"baseURL": "https://api.moonshot.ai/v1"},"models": {"kimi-k3": {"name": "Kimi K3"},"kimi-k2.7-code": {"name": "Kimi K2.7 Code"}}}}}Lưu tệp và khởi động lại OpenCode để áp dụng các thay đổi.
Bước 4: Xem các mô hình Kimi có sẵn
Sau khi kết nối nhà cung cấp, hãy chạy:
/modelsOpenCode sẽ hiển thị tất cả mô hình có sẵn thông qua tài khoản Moonshot AI của bạn, bao gồm:
| Mô hình | Mô tả |
|---|---|
| kimi-k3 | Mô hình chủ lực mới nhất với cửa sổ ngữ cảnh 1M token, khả năng lập trình và suy luận nâng cao |
| kimi-k2.7-code | Mô hình chuyên biệt cho lập trình với ngữ cảnh 256K và chế độ suy nghĩ |
| kimi-k2.7-code-highspeed | Biến thể tốc độ cao của mô hình lập trình, cho đầu ra nhanh hơn |
| kimi-k2.6 | Mô hình đa dụng với ngữ cảnh 256K, có chế độ suy nghĩ và không suy nghĩ |
Bước 5: Chọn một mô hình Kimi và bắt đầu lập trình
Chọn moonshotai/kimi-k3 và đặt làm mô hình đang hoạt động. Sau khi được chọn, OpenCode sẽ dùng mô hình Kimi đã chọn để tạo mã, gỡ lỗi, tái cấu trúc mã và thực hiện các tác vụ phát triển khác có hỗ trợ AI.
Bạn có thể chuyển sang một mô hình khác bất cứ lúc nào thông qua cùng trình đơn chọn mô hình.
Mẹo: Nếu gặp vấn đề với chế độ Tác tử/Công cụ (chẳng hạn lỗi xác thực JSON Schema), đây là vấn đề tương thích đã biết giữa các yêu cầu schema nghiêm ngặt của Moonshot AI và định dạng tham số công cụ của OpenCode. Hãy cân nhắc dùng chế độ Trò chuyện để đạt độ ổn định tốt nhất, hoặc cài plugin
opencode-moonshot-compatibilityđể tự động xử lý khả năng tương thích temperature.
Lợi ích khi sử dụng Kimi API
Kimi API được thiết kế để hỗ trợ quy trình phát triển hiện đại, giúp các nhóm chuyển từ ý tưởng sang triển khai hiệu quả hơn. Ngoài khả năng tạo mã, API này có thể hiểu nhiều loại dữ liệu đầu vào, thích ứng với yêu cầu dự án và tự động hóa các tác vụ kỹ thuật thường lệ. Dưới đây là một số lợi ích chính:
Chuyển dữ liệu đầu vào đa phương thức thành sản phẩm triển khai thực tế
Kimi API có thể diễn giải thông tin từ nhiều định dạng, gồm bản thiết kế mẫu, sơ đồ kiến trúc, lưu đồ và video. API sử dụng ngữ cảnh này để hiểu yêu cầu dự án rồi chuyển thành thông số kỹ thuật hoặc mã có chức năng. Nhờ đó, các nhóm có thể đi từ ý tưởng đến triển khai với ít bước chuyển đổi thủ công hơn.
Xử lý tác vụ lập trình dài hạn và kỹ thuật phức tạp
Kimi API giúp OpenCode xử lý các tác vụ lập trình quy mô lớn cần lập kế hoạch, tính nhất quán và tinh chỉnh. Công cụ này hữu ích khi xây dựng tính năng, tái cấu trúc mã và giải quyết các vấn đề kỹ thuật phức tạp.
Suy luận để giải quyết vấn đề bằng các lệnh gọi công cụ nhiều bước
Kimi API có thể suy luận qua các tác vụ nhiều bước và gọi công cụ khi cần. Điều này hỗ trợ gỡ lỗi, phân tích mã và các quy trình không thể hoàn thành chỉ trong một phản hồi.
Cách khắc phục sự cố khi cài đặt OpenCode？
Việc cài đặt OpenCode thường khá đơn giản, nhưng người dùng có thể gặp các lỗi thiết lập phổ biến do môi trường không tương thích, phần phụ thuộc hoặc cấu hình. Dưới đây là hướng dẫn rõ ràng, thiết thực giúp bạn khắc phục nhanh chóng và hiệu quả những lỗi cài đặt thường gặp nhất.
Không tìm thấy lệnh: opencode
Nếu gặp lỗi này, nghĩa là hệ thống không thể tìm thấy tệp thực thi OpenCode trong PATH của bạn. Điều này thường xảy ra khi quá trình cài đặt chưa hoàn tất hoặc biến môi trường chưa được thiết lập đúng.
Để khắc phục, trước tiên hãy kiểm tra việc cài đặt và bảo đảm thư mục chứa tệp nhị phân đã được thêm vào PATH hệ thống. Nếu cài qua npm, hãy kiểm tra đường dẫn npm bin toàn cục và cập nhật cấu hình shell tương ứng. Khởi động lại terminal sau khi chỉnh sửa thường sẽ giải quyết được vấn đề.
Phiên bản Node.js quá cũ
Chỉ phương thức cài đặt qua npm mới yêu cầu môi trường Node.js — tập lệnh cài đặt và các trình quản lý gói (Homebrew, Scoop, Chocolatey) sẽ cài tệp nhị phân độc lập, không cần Node.js.
Nếu bạn cài qua npm và gặp lỗi phiên bản, hãy kiểm tra phiên bản hiện tại bằng node --version rồi nâng cấp Node.js bằng trình quản lý phiên bản như nvm. Sau khi nâng cấp, hãy cài đặt lại OpenCode để bảo đảm tương thích với môi trường chạy đã cập nhật.
Lỗi quyền của npm
Lỗi quyền thường xảy ra khi npm cố cài đặt các gói toàn cục mà không có quyền ghi phù hợp.
Thay vì dùng sudo, hãy cấu hình một thư mục npm toàn cục riêng trong thư mục chính và cập nhật thiết lập PATH. Cách này giúp việc cài đặt an toàn và ổn định hơn. Sau khi khắc phục quyền, hãy chạy lại lệnh cài đặt để hoàn tất thiết lập.
Sự cố mạng/tường lửa
Trong các mạng bị hạn chế hoặc môi trường doanh nghiệp, việc cài đặt OpenCode có thể thất bại do quyền truy cập npm registry bị chặn hoặc tốc độ tải xuống chậm.
Để khắc phục, hãy chuyển sang npm registry khác hoặc dùng phương thức cài đặt trực tiếp như curl hay tải tệp nhị phân. Đồng thời, hãy bảo đảm tường lửa cho phép lưu lượng Node.js và npm, vì các kết nối bị chặn thường làm gián đoạn quá trình cài đặt gói.
Sự cố hiển thị TUI
Nếu OpenCode mở được nhưng hiển thị lỗi, lệch bố cục hoặc văn bản bị nhiễu, nguyên nhân thường là do khả năng tương thích của terminal.
Hãy dùng trình giả lập terminal hiện đại hỗ trợ hiển thị màu thực và Unicode, như Windows Terminal, WezTerm hoặc iTerm2. Cập nhật thiết lập terminal hoặc chuyển sang môi trường khác thường sẽ khắc phục ngay các vấn đề hiển thị.
Kết luận
Cài đặt và cấu hình OpenCode đúng cách giúp bảo đảm hoạt động trơn tru trên các hệ thống khác nhau, đồng thời giảm nguy cơ gặp lỗi thiết lập phổ biến. Khi các phần phụ thuộc, thiết lập terminal và kết nối API được quản lý đúng, người dùng có thể nhanh chóng xử lý sự cố và duy trì môi trường phát triển ổn định. Việc tích hợp các dịch vụ bên ngoài như Kimi API còn tăng tính linh hoạt nhờ cho phép truy cập các mô hình nâng cao trong quy trình làm việc.