Bỏ qua nội dung chính

Cách Cài Đặt và Sử Dụng OpenCode: Hướng Dẫn Toàn Diện

BlogsOpenCodeAITerminalCLIKhoảng 14 phút

Cách Cài Đặt và Sử Dụng OpenCode: Hướng Dẫn Toàn Diện

OpenCode là một agent lập trình AI mã nguồn mở mang sức mạnh trí tuệ nhân tạo trực tiếp đến terminal của bạn. Khác với các công cụ lập trình AI truyền thống chỉ hoạt động trong trình soạn thảo hoặc trình duyệt, OpenCode cung cấp giao diện trên terminal, ứng dụng desktop và tiện ích mở rộng IDE — tất cả được thiết kế nhằm giúp bạn tăng năng suất làm việc như một lập trình viên. Hướng dẫn toàn diện này sẽ đưa bạn đi qua tất cả những điều cần biết để cài đặt, cấu hình và sử dụng OpenCode một cách hiệu quả.

OpenCode là gì?

OpenCode là trợ lý lập trình được hỗ trợ bởi AI giúp bạn:

  • Viết code nhanh hơn với khả năng tạo và hoàn thành mã thông minh
  • Gỡ lỗi hiệu quả bằng cách phân tích lỗi và gợi ý cách khắc phục
  • Hiểu cấu trúc code thông qua các truy vấn ngôn ngữ tự nhiên
  • Thêm tính năng với việc lập kế hoạch và thực hiện tự động
  • Xem xét code với phân tích và đề xuất do AI hỗ trợ
  • Tự động hóa quy trình làm việc bằng các agent AI và công cụ tùy chỉnh

OpenCode hỗ trợ nhiều nhà cung cấp LLM bao gồm Anthropic, OpenAI, Google và các nhà cung cấp khác, mang lại cho bạn khả năng linh hoạt chọn các mô hình phù hợp nhất với nhu cầu.

Yêu Cầu Hệ Thống

Điều Kiện Tiên Quyết

Trước khi cài đặt OpenCode, đảm bảo bạn đã có:

  1. Trình giả lập terminal hiện đại (để dùng TUI):

  2. Node.js (cho cài đặt npm/bun/pnpm/yarn):

    • Khuyến nghị Node.js v18 trở lên

  3. Khóa API cho các nhà cung cấp LLM:

    • Khóa API Anthropic (cho các mô hình Claude)
    • Khóa API OpenAI (cho các mô hình GPT)
    • Hoặc các khóa từ nhà cung cấp được hỗ trợ khác

Các Phương Pháp Cài Đặt

Phương Pháp 1: Script Cài Đặt (Khuyến nghị)

Cách nhanh nhất để cài đặt OpenCode là dùng script cài đặt chính thức:

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

Phương pháp này hoạt động trên macOS, Linux và Windows (với Git Bash hoặc WSL).

Phương Pháp 2: Dùng Trình Quản Lý Gói Node.js

Dùng npm:

npm install -g opencode-ai

Dùng Bun:

bun install -g opencode-ai

Dùng pnpm:

pnpm install -g opencode-ai

Dùng Yarn:

yarn global add opencode-ai

Phương Pháp 3: Dùng Homebrew (macOS & Linux)

brew install opencode

Phương Pháp 4: Dùng Paru (Arch Linux)

paru -S opencode-bin

Phương Pháp 5: Cài Đặt Riêng cho Windows

Dùng Chocolatey:

choco install opencode

Dùng Scoop:

scoop bucket add extras
scoop install extras/opencode

Dùng Mise:

mise use -g github:sst/opencode

Phương Pháp 6: Docker

Dùng trong môi trường container:

docker run -it --rm ghcr.io/sst/opencode

Phương Pháp 7: Tải File Binary

Bạn có thể tải trực tiếp file binary đã được biên dịch sẵn từ trang GitHub Releases.

Kiểm Tra Cài Đặt

Sau khi cài đặt, kiểm tra xem có hoạt động không:

opencode --version

Bạn sẽ thấy phiên bản hiển thị.

Cấu Hình Ban Đầu

Kết Nối với OpenCode Zen (Khuyến nghị cho Người Mới)

OpenCode Zen là danh sách các mô hình được kiểm tra và xác nhận bởi team OpenCode. Đây là cách dễ nhất để bắt đầu.

  1. Khởi động OpenCode:
cd /path/to/your/project
opencode
  1. Chạy lệnh connect trong TUI:
/connect

  1. Chọn "opencode" trong danh sách nhà cung cấp

  2. Truy cập URL xác thực: opencode.ai/auth

  3. Đăng nhập và thêm thông tin thanh toán (hoặc dùng tín dụng miễn phí nếu có)

  4. Sao chép khóa API và dán vào terminal khi được yêu cầu

Kết Nối với Các Nhà Cung Cấp Khác

Bạn cũng có thể kết nối OpenCode với các nhà cung cấp LLM khác:

Dùng lệnh /connect:

/connect

Chọn nhà cung cấp bạn muốn (Anthropic, OpenAI, Google, v.v.) rồi làm theo hướng dẫn xác thực.

Dùng xác thực CLI:

opencode auth login

Lệnh này sẽ hướng dẫn bạn cấu hình khóa API cho các nhà cung cấp có trên Models.dev.

Xem danh sách nhà cung cấp đã cấu hình:

opencode auth list

hoặc phiên bản ngắn hơn:

opencode auth ls

Đăng xuất khỏi nhà cung cấp:

opencode auth logout

Thiết Lập Ngữ Cảnh Dự Án

Sau khi cấu hình nhà cung cấp, khởi tạo OpenCode cho dự án của bạn:

  1. Đi đến thư mục dự án:
cd /path/to/your/project
  1. Khởi động OpenCode:
opencode
  1. Chạy lệnh init:
/init

Lệnh này sẽ phân tích cấu trúc dự án và tạo file AGENTS.md trong thư mục gốc. File này giúp OpenCode hiểu mô hình lập trình, framework và kiến trúc dự án.

Mẹo: Commit file AGENTS.md lên Git. Điều này giúp giữ sự nhất quán trong đội và cải thiện khả năng hiểu dự án của OpenCode qua thời gian.

Sử Dụng Giao Diện Terminal (TUI)

TUI của OpenCode mang lại trải nghiệm tương tác ngay trong terminal của bạn.

Khởi Động TUI

Chỉ cần chạy:

opencode

Hoặc với các tùy chọn:

# Tiếp tục phiên làm việc trước
opencode --continue

# Tiếp tục một phiên cụ thể
opencode --session <session-id>

# Bắt đầu với câu hỏi
opencode --prompt "Explain this codebase"

# Dùng một mô hình cụ thể
opencode --model anthropic/claude-sonnet-4-5

# Dùng một agent cụ thể
opencode --agent plan

Điều Hướng Cơ Bản trong TUI

  • Cuộn: Dùng bánh xe chuột hoặc phím mũi tên
  • Chuyển đổi chế độ: Nhấn Tab để chuyển giữa Plan mode và Build mode
  • Chạy lệnh: Gõ / để mở bảng lệnh
  • Tìm file: Dùng @ để tìm tên file gần đúng trong dự án
  • Thoát: Nhấn Ctrl+C hoặc dùng lệnh /exit

Đặt Câu Hỏi

Bạn có thể hỏi OpenCode các câu hỏi về codebase:

How is authentication handled in @packages/functions/src/api/index.ts

Dùng ký hiệu @ để chỉ định file cụ thể. OpenCode sẽ phân tích file đó và cung cấp giải thích chi tiết.

Thêm Tính Năng

OpenCode ưu việt trong việc thêm tính năng mới qua quy trình hai bước:

Bước 1: Plan Mode

  1. Chuyển sang Plan mode bằng cách nhấn Tab
  2. Mô tả yêu cầu:
When a user deletes a note, we'd like to flag it as deleted in the database.
Then create a screen that shows all the recently deleted notes.
From this screen, the user can undelete a note or permanently delete it.
  1. Xem lại kế hoạch đề xuất
  2. Phản hồi, chỉnh sửa:
We'd like to design this new screen using a design I've used before.
[Image #1] Take a look at this image and use it as a reference.

Mẹo: Bạn có thể kéo thả hình ảnh vào terminal. OpenCode sẽ quét và phân tích chúng.

Bước 2: Build Mode

  1. Chuyển sang Build mode bằng cách nhấn Tab lần nữa
  2. Phê duyệt việc thực thi:
Sounds good! Go ahead and make the changes.

OpenCode sẽ triển khai tính năng, tạo và chỉnh sửa file cần thiết.

Thay Đổi Trực Tiếp

Với các thay đổi đơn giản, bạn có thể bỏ qua bước lên kế hoạch:

We need to add authentication to the /settings route.
Take a look at how this is handled in the /notes route
in @packages/functions/src/notes.ts and implement the same logic
in @packages/functions/src/settings.ts

Hoàn Tác và Làm Lại Thay Đổi

Gặp lỗi? Dùng lệnh hoàn tác:

/undo

Lệnh này sẽ trả lại thay đổi gần nhất và cho phép bạn chỉnh sửa lại lời nhắc.

Để làm lại thay đổi đã hoàn tác:

/redo

Bạn có thể chạy /undo nhiều lần để hoàn tác nhiều lần thay đổi.

Lệnh CLI

OpenCode cung cấp CLI mạnh mẽ cho việc truy cập tự động và lập trình.

Chạy Prompt Trực Tiếp

Chạy OpenCode không tương tác:

opencode run "Explain how closures work in JavaScript"

Thích hợp cho scripting, tự động hóa hoặc trả lời nhanh mà không khởi chạy TUI.

Quản Lý Mô Hình

Liệt kê các mô hình có sẵn:

opencode models

Lọc theo nhà cung cấp:

opencode models anthropic

Làm mới cache mô hình (khi có mô hình mới):

opencode models --refresh

Hiển thị thông tin chi tiết về mô hình bao gồm chi phí:

opencode models --verbose

Khởi Động Server Không Giao Diện

Khởi động server HTTP để truy cập API:

opencode serve

Với cổng tùy chỉnh:

opencode serve --port 3000

Dùng để tích hợp OpenCode vào ứng dụng web hoặc tăng tốc độ phản hồi trong script (tránh khởi động lạnh MCP server).

Kết Nối Với Server

Mở một terminal chạy server:

opencode serve

Ở terminal khác, kết nối để thực thi nhanh hơn:

opencode run --attach http://localhost:4096 "Explain async/await in JavaScript"

Quản Lý Agents

Tạo agent tùy chỉnh mới:

opencode agent create

Hệ thống sẽ hướng dẫn bạn tạo agent với prompt và cấu hình công cụ tùy chỉnh.

Tích Hợp GitHub

Cài đặt agent GitHub để tự động hóa kho mã:

opencode github install

Thiết lập workflows GitHub Actions cho xem xét code tự động và xử lý issues.

Nâng Cấp OpenCode

Nâng cấp lên phiên bản mới nhất:

opencode upgrade

Hoặc phiên bản cụ thể:

opencode upgrade v0.1.48

Chỉ định phương pháp cài đặt nếu cần:

opencode upgrade --method brew

Cấu Hình

OpenCode hỗ trợ cấu hình linh hoạt qua các file config JSON.

Vị Trí Config

File config được hợp nhất với nhau (không ghi đè), cho phép bạn có cấu hình toàn cục, theo dự án và tùy chỉnh.

  1. Config toàn cục: ~/.config/opencode/opencode.json

    • Dùng cho theme, nhà cung cấp, phím tắt, cài đặt chung

  2. Config dự án: opencode.json trong thư mục gốc dự án

    • Dùng cho nhà cung cấp, agent hoặc cài đặt riêng dự án
    • Có thể commit lên Git an toàn

  3. Đường dẫn Config tùy chỉnh: Thiết lập qua biến môi trường OPENCODE_CONFIG

  4. Thư mục Config tùy chỉnh: Thiết lập qua biến môi trường OPENCODE_CONFIG_DIR

Ví Dụ Cấu Hình Cơ Bản

Tạo file config với cấu trúc sau:

{
  "$schema": "https://opencode.ai/config.json",
  
  // Chọn theme
  "theme": "opencode",
  
  // Mô hình chính sử dụng
  "model": "anthropic/claude-sonnet-4-5",
  
  // Mô hình nhỏ cho tác vụ nhẹ
  "small_model": "anthropic/claude-haiku-4-5",
  
  // Tự động cập nhật
  "autoupdate": true
}

Cấu Hình Nhà Cung Cấp

Cấu hình khóa API trực tiếp trong config:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    },
    "openai": {
      "options": {
        "apiKey": "{env:OPENAI_API_KEY}"
      }
    }
  }
}

Khuyến nghị dùng biến môi trường để bảo mật. Cú pháp {env:TÊN_BIẾN}.

Dùng Tham Chiếu File

Bạn cũng có thể tham chiếu đến file chứa dữ liệu nhạy cảm:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

Lệnh Tùy Chỉnh

Định nghĩa các lệnh tùy chỉnh cho các tác vụ lặp đi lặp lại:

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Run full test suite with coverage report and show any failures.\nFocus on failing tests and suggest fixes.",
      "description": "Chạy kiểm thử với báo cáo coverage",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5"
    },
    "component": {
      "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
      "description": "Tạo component mới"
    }
  }
}

Dùng lệnh tùy chỉnh trong TUI bằng cách gõ /test hoặc /component MyComponent.

Agents Tùy Chỉnh

Tạo agent chuyên biệt:

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Xem xét code tập trung vào bảo mật, hiệu suất, khả năng bảo trì",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "Bạn là người xem xét code. Tập trung vào bảo mật, hiệu suất và khả năng bảo trì.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Cấu Hình Quyền Hạn

Điều khiển những gì OpenCode có thể làm mà không cần hỏi:

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

Yêu cầu người dùng phê duyệt cho thao tác chỉnh sửa và bash.

Bộ Định Dạng Code

Cấu hình định dạng code tự động:

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "prettier": {
      "disabled": false
    },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

Cài Đặt TUI

Tùy chỉnh giao diện terminal:

{
  "$schema": "https://opencode.ai/config.json",
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    }
  }
}

Tính Năng Nâng Cao

Chia Sẻ Cuộc Hội Thoại

Chia sẻ cuộc trò chuyện với nhóm:

/share

Lệnh này tạo link chia sẻ và sao chép vào clipboard. Mặc định cuộc hội thoại không được chia sẻ.

Cấu hình hành vi chia sẻ:

{
  "share": "manual"  // "manual", "auto", hoặc "disabled"
}

MCP Servers

Model Context Protocol (MCP) servers mở rộng khả năng OpenCode:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
    }
  }
}

Hướng Dẫn và Quy Tắc

Cung cấp các hướng dẫn đặc thù dự án:

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    ".cursor/rules/*.md"
  ]
}

OpenCode sẽ dùng những file này để hiểu tiêu chuẩn và quy ước code của bạn.

Biến Môi Trường

Cấu hình OpenCode qua biến môi trường:

# Tự động chia sẻ phiên làm việc
export OPENCODE_AUTO_SHARE=true

# Đường dẫn config tùy chỉnh
export OPENCODE_CONFIG=/path/to/config.json

# Thư mục config tùy chỉnh
export OPENCODE_CONFIG_DIR=/path/to/config-dir

# Tắt tự động cập nhật
export OPENCODE_DISABLE_AUTOUPDATE=true

# Tắt plugin mặc định
export OPENCODE_DISABLE_DEFAULT_PLUGINS=true

# Bật các mô hình thử nghiệm
export OPENCODE_ENABLE_EXPERIMENTAL_MODELS=true

# Bật tìm kiếm web Exa
export OPENCODE_ENABLE_EXA=true

Tính Năng Thử Nghiệm

Bật tính năng thử nghiệm:

export OPENCODE_EXPERIMENTAL=true

Các tính năng thử nghiệm cụ thể:

# Bật khám phá icon
export OPENCODE_EXPERIMENTAL_ICON_DISCOVERY=true

# Tắt tự động copy khi chọn trong TUI
export OPENCODE_EXPERIMENTAL_DISABLE_COPY_ON_SELECT=true

# Giới hạn độ dài đầu ra lệnh bash
export OPENCODE_EXPERIMENTAL_BASH_MAX_OUTPUT_LENGTH=10000

# Thiết lập timeout mặc định cho lệnh bash (ms)
export OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS=30000

Các Thực Hành Tốt Nhất

Prompt Hiệu Quả

  1. Cụ thể: Cung cấp chỉ dẫn rõ ràng, chi tiết
  2. Dùng ngữ cảnh: Tham chiếu file bằng @ để hiểu rõ hơn
  3. Cung cấp ví dụ: Cho ví dụ mẫu về yêu cầu
  4. Chia nhỏ: Tác vụ phức tạp tốt hơn khi chia theo bước

Làm Việc Với Dự Án Lớn

  1. Dùng /init: Giúp OpenCode hiểu cấu trúc dự án
  2. Tham chiếu file cụ thể: Dùng @ để giới hạn ngữ cảnh
  3. Dùng Plan mode: Xem xét kế hoạch trước khi thực thi
  4. Thay đổi từng phần: Làm các thay đổi nhỏ dễ xử lý

Tối Ưu Chi Phí

  1. Dùng mô hình nhỏ: Cấu hình small_model cho tác vụ nhẹ
  2. Lập kế hoạch trước khi xây dựng: Giảm số lần chỉnh sửa
  3. Lệnh tùy chỉnh: Định nghĩa quy trình hiệu quả cho tác vụ phổ biến
  4. Giám sát sử dụng: Kiểm tra dashboard nhà cung cấp để theo dõi chi phí

Thực Hành An Ninh

  1. Không bao giờ commit khóa API: Dùng biến môi trường
  2. Dùng quyền hạn: Cấu hình permission để yêu cầu phê duyệt thao tác nhạy cảm
  3. Rà soát thay đổi: Luôn đánh giá các thay đổi do OpenCode đề xuất
  4. Dùng khóa riêng: Tạo khóa API riêng cho OpenCode với giới hạn phù hợp

Khắc Phục Sự Cố

Vấn Đề Cài Đặt

Vấn đề: Lệnh không tìm thấy sau khi cài đặt

Giải pháp:

  • Kiểm tra cài đặt: which opencode
  • Kiểm tra PATH: echo $PATH
  • Thử chạy với đường dẫn đầy đủ: ~/.local/bin/opencode
  • Cài lại bằng phương pháp khác

Vấn Đề Xác Thực

Vấn đề: Khóa API không được nhận diện

Giải pháp:

  • Kiểm tra khóa đúng: opencode auth list
  • Kiểm tra biến môi trường: echo $ANTHROPIC_API_KEY
  • Đăng nhập lại: opencode auth login

Vấn Đề Hiệu Năng

Vấn đề: Thời gian phản hồi chậm

Giải pháp:

  • Dùng opencode serve để tăng tốc
  • Chuyển sang mô hình nhanh hơn
  • Dùng cửa sổ ngữ cảnh nhỏ hơn
  • Tắt công cụ không dùng trong cấu hình

Vấn Đề TUI

Vấn đề: Hiển thị terminal lỗi

Giải pháp:

  • Dùng terminal emulator hiện đại (WezTerm, Alacritty, ...)
  • Kiểm tra terminal hỗ trợ màu 24-bit
  • Thử theme khác
  • Tắt tăng tốc cuộn nếu gặp vấn đề

Vấn Đề Mô Hình

Vấn đề: Không tìm thấy mô hình

Giải pháp:

  • Làm mới danh sách mô hình: opencode models --refresh
  • Kiểm tra nhà cung cấp đã cấu hình: opencode auth list
  • Xác nhận định dạng tên mô hình: provider/model
  • Kiểm tra nhà cung cấp có mô hình đó hay không

Tích Hợp OpenCode Vào Quy Trình Làm Việc

Phát Triển Hàng Ngày

  1. Buổi sáng: Chạy /init để đồng bộ với code mới nhất
  2. Phát triển tính năng: Dùng Plan mode để thiết kế, Build mode để thực thi
  3. Gỡ lỗi: Hỏi câu hỏi về lỗi với tham chiếu file
  4. Xem xét code: Dùng agent code reviewer tùy chỉnh
  5. Tài liệu: Tạo docs bằng lệnh tùy chỉnh

Hợp Tác Nhóm

  1. Chia sẻ config: Commit opencode.json và AGENTS.md lên Git
  2. Chia sẻ cuộc hội thoại: Dùng /share để thảo luận
  3. Lệnh tùy chỉnh: Định nghĩa lệnh riêng cho nhóm trong config dự án
  4. Agent nhất quán: Dùng định nghĩa agent chia sẻ cho đồng bộ

Tích Hợp CI/CD

  1. Agent GitHub: Cài đặt để tự động review PR
  2. Kiểm thử: Dùng lệnh test tùy chỉnh trong CI
  3. Chất lượng code: Cấu hình formatter và quyền hạn

Kết Luận

OpenCode đại diện cho một mô hình mới trong phát triển hỗ trợ bởi AI khi đưa khả năng AI mạnh mẽ trực tiếp vào terminal của bạn. Với cấu hình linh hoạt, hỗ trợ đa nhà cung cấp LLM và giao diện TUI thân thiện, nó được thiết kế giúp tăng hiệu suất mà không làm gián đoạn quy trình làm việc hiện tại.

Điểm Chính:

  • Cài đặt qua script hoặc trình quản lý gói yêu thích
  • Cấu hình khóa API qua /connect hoặc opencode auth login
  • Khởi tạo dự án với /init để hiểu bối cảnh tốt hơn
  • Dùng Plan mode cho tính năng phức tạp, Build mode cho thay đổi trực tiếp
  • Tùy chỉnh với file config, lệnh và agent
  • Tận dụng lệnh CLI cho tự động hóa và scripting
  • Thực hành an ninh tốt với khóa API và quyền hạn

Bước Tiếp Theo:

  • Khám phá tài liệu OpenCode cho tính năng nâng cao
  • Tham gia cộng đồng OpenCode Discord
  • Tùy chỉnh giao diện với theme và phím tắt
  • Thử nghiệm các nhà cung cấp LLM và mô hình khác nhau
  • Tích hợp OpenCode vào quy trình nhóm bạn

Sẵn sàng tăng tốc quy trình phát triển?
Khám phá giải pháp hosting AI tối ưu của LightNode để triển khai ứng dụng AI với GPU chuyên dụng và hạ tầng có thể mở rộng.

OpenCode là mã nguồn mở và liên tục phát triển. Hãy đóng góp dự án, báo lỗi hoặc chia sẻ trải nghiệm để giúp OpenCode ngày càng hoàn thiện hơn. Chúc bạn lập trình vui vẻ!

Tập trung giới thiệu máy chủ VPS toàn cầu.