Cài đặt goose và cấu hình Provider tùy chỉnh

goose là trợ lý AI đa năng chạy trên máy tính của bạn. Ngoài lập trình, nó còn có thể tìm kiếm, viết nội dung, tự động hóa và sắp xếp dữ liệu. Bạn có thể sử dụng goose qua ứng dụng máy tính, terminal hoặc API; phiên bản máy tính và phiên bản terminal dùng chung một cấu hình mô hình. Công cụ này phù hợp để xử lý các tác vụ lập trình lặp lại, đồng thời có thể kết nối với GitHub, cơ sở dữ liệu và tệp.

Chuẩn bị trước khi cài đặt

goose cung cấp hai cách cài đặt là Desktop và CLI. Desktop là phiên bản máy tính có giao diện cửa sổ, còn CLI là phiên bản được sử dụng bằng cách nhập lệnh trong terminal. Cả hai dùng chung cấu hình cốt lõi, bao gồm Provider và mô hình. Có thể hiểu Provider là cấu hình kết nối dùng để “cho goose biết cần sử dụng dịch vụ mô hình nào”.

Muốn có cửa sổ

goose Desktop

Tải zip cho macOS
Hoặc dùng brew cask
Trên Linux, dùng gói cài đặt

Chỉ cần terminal

goose CLI

download_cli.sh
Hoặc Homebrew CLI
Sau đó chạy goose session

Windows

Chọn môi trường trước

Git Bash hoặc MSYS2
Cũng có thể dùng PowerShell
Nếu không tìm thấy lệnh, hãy thêm vào PATH

Trên macOS, bạn có thể tải xuống hoặc dùng Homebrew. Phiên bản máy tính cho Linux sử dụng gói cài đặt dành cho từng bản phân phối. Trên Windows, trước tiên hãy kiểm tra các môi trường terminal được liệt kê.

Trước khi bắt đầu, hãy chuẩn bị ID mô hình trong danh sách mô hình hiện tại. ID mô hình là tên mà dịch vụ mô hình dùng để nhận diện một mô hình cụ thể; khi sử dụng, bạn cần sao chép đầy đủ ID này.

Cài đặt và khởi chạy lần đầu

Nếu bạn muốn có giao diện cửa sổ

Trên macOS có hai cách cài đặt:

Tải xuống từ trang cài đặt. Trang này có bản dành cho macOS Silicon và macOS Intel. Sau khi tải xuống, hãy giải nén tệp zip rồi chạy chương trình bên trong.
Hoặc sử dụng Homebrew:

brew install --cask block-goose

Lệnh này tải xuống cùng một ứng dụng và cũng có thể hỗ trợ xử lý việc cập nhật.

Nếu bạn dùng Apple Mac M3 nhưng không thấy cửa sổ sau khi mở ứng dụng, hãy kiểm tra xem ~/.config có quyền đọc và ghi hay không. goose cần dùng thư mục này để ghi nhật ký.

Với phiên bản máy tính cho Linux, hãy tải xuống từ trang cài đặt. Các định dạng được liệt kê gồm DEB (Ubuntu/Debian), RPM (RHEL/Fedora) và Flatpak. Trên Debian hoặc Ubuntu, hãy tải tệp DEB, mở thư mục chứa tệp đó, chạy sudo dpkg -i (filename).deb, rồi mở goose từ trình đơn ứng dụng. Thay (filename) bằng tên tệp thực tế.

Với phiên bản máy tính cho Windows, hãy tải xuống từ trang cài đặt, giải nén tệp zip rồi chạy chương trình bên trong.

Nếu bạn chỉ cần terminal

Trên macOS và Linux, hãy chạy:

curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash

Nếu không muốn thực hiện cấu hình tương tác trong quá trình cài đặt, hãy thêm CONFIGURE=false ở phía trước:

curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash

Trên macOS, bạn cũng có thể chạy:

brew install block-goose-cli

Để cập nhật CLI đã cài đặt, hãy dùng:

goose update

Trên Windows, bạn cần một trong ba môi trường sau: Git Bash (được cung cấp cùng Git for Windows và được đánh dấu là lựa chọn khuyến nghị), MSYS2 hoặc PowerShell có sẵn trên Windows 10/11. Với Git Bash và MSYS2, hãy sử dụng cùng lệnh download_cli.sh ở trên. Với PowerShell, trước tiên hãy tải tập lệnh xuống rồi chạy:

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1" -OutFile "download_cli.ps1"
.\download_cli.ps1

Nếu có thông báo cho biết goose không nằm trong PATH, hãy làm theo trang cài đặt để thêm ~/.local/bin hoặc %USERPROFILE%\.local\bin vào cấu hình của shell hiện tại, sau đó mở lại terminal. PATH là tập hợp các thư mục mà terminal dùng để tìm chương trình. Nếu chưa thêm thư mục vào PATH, bạn có thể không chạy được chương trình bằng cách nhập trực tiếp tên của nó dù chương trình đã được cài đặt.

Phiên bản CLI vào ngày 2026-10-09 là 1.54.0. Theo mặc định, tập lệnh cài đặt đặt chương trình trong ~/.local/bin. Bạn có thể thay đổi thư mục này bằng biến môi trường GOOSE_BIN_DIR. Sau khi thay đổi, tập lệnh sẽ không tự động ghi vào cấu hình shell và terminal sẽ thông báo rằng thư mục đó không nằm trong PATH. Hãy thêm thư mục đó vào PATH hoặc chạy chương trình bằng đường dẫn đầy đủ.

Trong lần sử dụng đầu tiên, goose sẽ yêu cầu bạn cấu hình Provider. Bạn có thể tạm bỏ qua các nhà cung cấp tích hợp sẵn và thêm Provider tùy chỉnh theo phần tiếp theo. Trong terminal, hãy chuyển đến thư mục bạn muốn làm việc rồi chạy:

goose session

Lấy thông số kết nối từ OmniProxy

Hãy chuẩn bị địa chỉ, khóa và tên mô hình từ OmniProxy của bạn. Ví dụ về Provider tùy chỉnh đặt base_url tại /v1/chat/completions, vì vậy phần này cũng sử dụng định dạng đó:

API URL:  https://your-omniproxy-origin.example/v1/chat/completions
API Key:  <YOUR_OMNIPROXY_API_KEY>
Models:   Sao chép từ danh sách mô hình hiện tại của OmniProxy; phân tách nhiều mô hình bằng dấu phẩy tiếng Anh

Hãy sao chép nguyên vẹn tên mô hình từ danh sách hiện tại của OmniProxy, bao gồm cả dấu gạch chéo. Hai ID dùng để đối chiếu trong tài liệu nhà cung cấp vào ngày 2026-10-09 là grok-4.7 của Grok và gpt-6-luna trong tài liệu OpenAI. gpt-6-luna hỗ trợ Chat Completions; trong Chat Completions, tính năng gọi hàm chỉ được hỗ trợ khi reasoning_effort là none. Không sao chép những tên không có trong danh sách.

Điền cấu hình công cụ

Provider tùy chỉnh sử dụng định dạng tương thích với OpenAI, Anthropic hoặc Ollama. Có thể hiểu định dạng tương thích là công cụ gửi yêu cầu theo một giao diện chung nhất định. Khi kết nối với OmniProxy, hãy chọn OpenAI Compatible.

Phiên bản máy tính

Nhấp vào nút ở góc trên bên trái để mở thanh bên.
Nhấp vào Settings.
Nhấp vào Models.
Nhấp vào Configure providers.
Nhấp vào Add Custom Provider ở cuối cửa sổ.
Trong Provider Type, chọn OpenAI Compatible. Bạn có thể đặt Display Name là OmniProxy. Trong API URL, nhập địa chỉ ở phần trước. Nếu cần khóa, hãy đánh dấu tùy chọn yêu cầu API Key rồi nhập khóa OmniProxy. Trong Available Models, nhập tên mô hình; nếu có nhiều mô hình, hãy phân tách bằng dấu phẩy tiếng Anh.
Nhấp vào Create Provider.

Hiện tại, phiên bản máy tính không cho phép định nghĩa tiêu đề yêu cầu tùy chỉnh trong cửa sổ này. Nếu cần tiêu đề yêu cầu, hãy sửa tệp cấu hình sau khi tạo Provider.

Terminal

Chạy:

goose configure

Chọn Custom Providers, sau đó chọn Add A Custom Provider. Trong API Type, chọn OpenAI Compatible, rồi làm theo lời nhắc để nhập tên, API URL, xác định có cần khóa hay không, tên mô hình và khả năng hỗ trợ phản hồi truyền phát.

Khi cấu hình thủ công trên Windows, nếu kho khóa báo lỗi, hãy chọn không lưu vào keyring khi được hỏi, sau đó chuyển sang dùng biến môi trường. Tiếp theo, chạy lại goose configure. Keyring là kho lưu trữ bảo mật nhỏ mà hệ thống dùng để lưu khóa.

Tệp cấu hình

Các thư mục được cung cấp là:

macOS và Linux: ~/.config/goose/custom_providers/
Windows: %APPDATA%\Block\goose\config\custom_providers\

Bạn có thể tạo tệp dựa trên ví dụ sau. Hãy thay tên, địa chỉ và mô hình bằng giá trị của bạn. Đặt khóa trong biến môi trường được chỉ định bởi api_key_env; không ghi khóa thật trực tiếp vào tệp:

{
  "name": "omniproxy",
  "engine": "openai",
  "display_name": "OmniProxy",
  "api_key_env": "OMNIPROXY_API_KEY",
  "base_url": "https://your-omniproxy-origin.example/v1/chat/completions",
  "models": [
    { "name": "grok-4.7", "context_limit": 128000 },
    { "name": "gpt-6-luna", "context_limit": 128000 }
  ],
  "supports_streaming": true,
  "requires_auth": true
}

Với context_limit, hãy giữ lại một giá trị số như trong ví dụ. Ngữ cảnh thực tế phụ thuộc vào mô hình và OmniProxy; không coi con số trong ví dụ này là giới hạn chính thức của mô hình. Trước khi sử dụng, hãy chạy:

export OMNIPROXY_API_KEY="<YOUR_OMNIPROXY_API_KEY>"

Sau khi chuyển đến thư mục làm việc, hãy chạy:

goose session --provider omniproxy --model grok-4.7

Thay giá trị của --model bằng ID đầy đủ trong danh sách. goose session không có lệnh con start. Bạn cũng có thể đặt --provider và --model thông qua các biến môi trường GOOSE_PROVIDER và GOOSE_MODEL. Ngay cả khi cổng kết nối không xác thực khóa, OMNIPROXY_API_KEY vẫn phải có giá trị; đó có thể là một chuỗi giữ chỗ chỉ dùng trên máy cục bộ. Trong thử nghiệm ngày 2026-10-09, cấu hình này đã đọc được tệp.

Cửa sổ

Settings

Settings trong thanh bên
Trang Models
Add Custom Provider

Terminal

goose configure

Chọn Custom Providers
Sau đó chọn thêm
Chọn loại OpenAI Compatible

Tệp

custom_providers

Trên macOS và Linux, nằm trong ~/.config
Trên Windows, nằm trong APPDATA
base_url phải theo ví dụ chính thức

Cả ba cách đều ghi cùng một loại cấu hình. Với loại Provider, hãy chọn OpenAI Compatible.

Xác minh bằng một tác vụ thực tế

Hãy chuyển đến một thư mục có tệp thông thường rồi chạy goose session như ở phần trước. Yêu cầu goose đọc dòng đầu tiên của tệp bạn chỉ định. Công cụ cần trả về nội dung của tệp, thay vì chỉ hiển thị rằng cấu hình đã được lưu.

Để đọc tệp hoặc thực thi lệnh, phiên làm việc cần có phần mở rộng Developer. Có thể hiểu phần mở rộng Developer là mô-đun công cụ cho phép goose xử lý tệp cục bộ và lệnh. Cấu hình mặc định thường đã bao gồm phần mở rộng này. Nếu goose trả lời rằng nó không có công cụ xử lý tệp, hãy thêm vào lệnh:

--with-builtin developer

Không thêm đồng thời --no-profile, vì tham số đó sẽ tắt các phần mở rộng mặc định.

Trong thử nghiệm ngày 2026-10-09 với goose 1.54.0, công cụ đã đọc được dòng đầu tiên của tệp được chỉ định. Phản hồi đầu tiên có thể mất khoảng một phút.

Sau đó, hãy kiểm tra nguồn và tên mô hình trong nhật ký gọi của OmniProxy.

Khởi động

Có thể vào phiên

goose session
Provider là mục vừa thêm
Tên mô hình có trong danh sách

Tác vụ

Nó thực sự đã thực hiện

Ví dụ: liệt kê thư mục hiện tại
Xem phản hồi của nó
Đừng chỉ kiểm tra thông báo lưu thành công

Nhật ký

Có thể thấy trên gateway

Địa chỉ phải theo ví dụ trong tài liệu
Không ghi khóa vào kho mã
ID mô hình khớp với danh sách

Sau khi lưu Provider, bạn vẫn cần dùng một phiên làm việc thực tế để xác minh.

Lỗi thường gặp

Không tìm thấy lệnh goose: thêm thư mục cài đặt vào PATH theo hướng dẫn trên trang cài đặt, sau đó mở lại terminal.
Phiên bản máy tính không hiển thị cửa sổ trên M3: kiểm tra quyền đọc và ghi của ~/.config.
Keyring gặp lỗi: không lưu khóa vào keyring; hãy chuyển sang dùng biến môi trường.
Mô hình không có trong danh sách: trong phiên bản máy tính, bạn có thể chọn Use custom model để nhập tên mô hình theo cách thủ công. goose configure không thể nhập tên mô hình tùy chỉnh; khi dùng terminal, hãy chuyển sang phiên bản máy tính hoặc sửa trực tiếp GOOSE_MODEL trong cấu hình.
Không kết nối được với địa chỉ: xác nhận API URL kết thúc bằng /v1/chat/completions như trong ví dụ và OmniProxy đang chạy.
goose cho biết không thể đọc tệp: thêm phần mở rộng Developer và không sử dụng --no-profile.
Trả về unsupported Responses role: system: địa chỉ thường không có vấn đề. Hãy đổi sang một ID đầy đủ khác trong danh sách mô hình.

Tài liệu tham khảo chính thức

Xem hướng dẫn cài đặt tại Install goose. Xem cách cấu hình Provider tùy chỉnh tại goose providers. Các ID mô hình dùng trong ví dụ có tại trang mô hình xAI và GPT-6 Luna.

Thay thế mọi chỗ giữ chỗ bằng giá trị từ cấu hình OmniProxy của riêng bạn. Không bao giờ công bố khóa thật.

Kết quả được lưu hoặc mã HTTP 200 đơn lẻ không chứng minh khả năng tương thích đầy đủ của Agent. Hãy kiểm tra nguồn và mô hình trong bản ghi lệnh gọi của OmniProxy.

Nguồn chính thức · goose ↗