Hướng dẫn agent mã nguồn goose: cài đặt, nguồn mô hình, cấu hình API và chi phí

goose là một tác nhân AI lập trình mã nguồn mở (Apache-2.0), có thể đọc tệp, sửa tệp và chạy lệnh trong terminal hoặc ứng dụng desktop. Bắt đầu chỉ cần ba bước: cài đặt, chọn nguồn mô hình (provider) và mở một phiên làm việc để giao nhiệm vụ. Bản thân nó miễn phí; chi phí đến từ mô hình bạn kết nối. Bài hướng dẫn này dựa trên tài liệu chính thức ngày 1 tháng 10 năm 2026, trình bày cách cài đặt, ba hướng trả phí, cách kết nối với endpoint tương thích OpenAI (bao gồm bẫy /v1 thường gặp nhất) và các thao tác phổ biến. Phiên bản mới nhất là v1.52.0, phát hành ngày 23 tháng 9 năm 2026.

Trước hết cần làm rõ tên gọi. Trang này nói về tác nhân lập trình trên goose-docs.ai, với kho mã tại aaif-goose/goose, trước đây là block/goose, đã chuyển sang Agentic AI Foundation của Linux Foundation vào tháng 4 năm 2026. Nó không phải là goose.ai — đó là một dịch vụ suy luận được vận hành trên hạ tầng của nhà cung cấp khác, và giá của dịch vụ đó cũng không liên quan đến dự án này. Hiện goose chưa có giao diện tiếng Trung phồn thể; tên menu bên dưới được viết theo nguyên bản tiếng Anh.

cài đặt

Nhà phát triển cung cấp bản desktop (goose Desktop) và bản dòng lệnh (goose CLI), cả hai dùng chung một cấu hình.

# goose Desktop(macOS)
brew install --cask block-goose

# goose CLI（macOS / Linux / Windows 的 Git Bash）
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash

# 只安裝、先不進入設定
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash

# 或用 Homebrew 裝 CLI
brew install block-goose-cli

Windows có thể tải bản desktop từ trang chính thức; với CLI, nên chạy cùng một lệnh cài đặt trong Git Bash (PowerShell cũng được). Tên gói Homebrew vẫn là block-goose, do việc đổi tên chưa được truyền đầy đủ sang gói cài đặt, không có nghĩa dự án vẫn thuộc Block.

Khởi động lần đầu: chọn nguồn mô hình

Lần đầu mở goose Desktop sẽ xuất hiện màn hình chào mừng; CLI sẽ tự động vào chế độ cấu hình (sau này muốn thay đổi có thể chạy goose configure). Trang cài đặt liệt kê ba lựa chọn:

• OpenRouter Login — đăng nhập bằng tài khoản OpenRouter và tự động cấu hình mô hình.
• Tetrate Agent Router Service Login — đăng nhập bằng Tetrate; tài liệu nêu rằng lần đầu xác thực tự động qua goose sẽ nhận $10 credit miễn phí, áp dụng cho cả người dùng mới và hiện tại.
• Manual Configuration — tự chọn provider và nhập khóa. Để kết nối endpoint tương thích OpenAI (chẳng hạn Kunavo), hãy chọn mục này.

Ba hướng trả phí, hãy chọn đúng trước khi cấu hình

Mô tả về hướng ACP lấy từ tài liệu ACP providers của goose; tài liệu cũng nhắc rằng session ID của ACP khác với của goose, nên các trường telemetry có thể không khớp. Nếu bạn đã có gói đăng ký và chỉ muốn tiết kiệm chi phí API, hãy xem hướng này trước.

Kết nối endpoint tương thích OpenAI: không thêm /v1 vào Host URL

Đây là chỗ khiến nhiều người mắc kẹt nhất. goose không nhận một base URL hoàn chỉnh mà tách thành “máy chủ” và “đường dẫn”. Theo tài liệu providers, OPENAI_HOST là “URL endpoint tùy chỉnh (mặc định api.openai.com)”, OPENAI_BASE_PATH là “đường dẫn request được thêm sau máy chủ (mặc định v1/chat/completions)”, và khi kết nối proxy, bạn phải đặt OPENAI_HOST thành “địa chỉ gốc của proxy (không có đường dẫn)”. Với Kunavo:

# goose Desktop → Settings → Models → Configure providers → OpenAI
API Key           sk-kn-...
Host URL          https://api.kunavo.com      ← 只寫網域，不加 /v1
Organization ID   （留空）
Project           （留空）

# 或用環境變數（CLI 也讀）
export OPENAI_API_KEY=sk-kn-...
export OPENAI_HOST=https://api.kunavo.com
# OPENAI_BASE_PATH 不要設：預設就是 v1/chat/completions

Trong goose Desktop, vị trí là Settings → Models → Configure providers → OpenAI; trong CLI là goose configure → Configure Providers → OpenAI. Organization ID và Project dành cho tài khoản OpenAI riêng, có thể để trống. Nếu Host URL được viết là https://api.kunavo.com/v1, request sẽ thành /v1/v1/chat/completions; chính tài liệu cũng nói “404 thường có nghĩa OPENAI_BASE_PATH không phù hợp với proxy của bạn” — đó là lỗi đường dẫn, không phải lỗi khóa. Ngược lại, nếu xuất hiện 401 “No api key passed in”, nghĩa là khóa không được đọc, chẳng hạn bạn ghi khóa vào config.yaml (goose sẽ bỏ qua tệp đó).

Một cách gọn gàng hơn là để nó trở thành một provider riêng trong danh sách. goose đọc các tệp định nghĩa JSON trong thư mục custom_providers; Kunavo cung cấp một tệp được tạo từ bảng giá theo thời gian thực, chỉ chứa các mô hình hỗ trợ tool calling và chỉ ghi tên biến của khóa, không chứa khóa:

# macOS / Linux:goose 會讀這個資料夾裡所有 JSON
mkdir -p ~/.config/goose/custom_providers
curl -fsSL https://kunavo.com/goose/kunavo.json \
  -o ~/.config/goose/custom_providers/kunavo.json

# 檔案裡只有變數名稱，金鑰另外設定
export KUNAVO_API_KEY=sk-kn-...
goose session start --provider kunavo

Thư mục trên Windows là %APPDATA%\Block\goose\config\custom_providers\. Sau khi đặt tệp vào đó, Kunavo sẽ xuất hiện trong mục Configure providers của goose Desktop; khóa API có thể được lưu trong kho khóa của hệ thống thay vì biến môi trường. Theo mã nguồn của goose, các mô hình có ID bắt đầu bằng gpt-5 hoặc gpt-6 sẽ dùng /v1/responses, các mô hình khác dùng /v1/chat/completions; Kunavo cung cấp cả hai. Bạn cũng có thể tạo thủ công: Configure providers → Add Custom Provider, chọn loại OpenAI Compatible và điền https://api.kunavo.com/v1 vào API URL. Trang hướng dẫn cấu hình đầy đủ bằng tiếng Anh nằm tại goose integration guide.

Nói rõ một cách trung thực: Cấu hình trên được tổng hợp từ tài liệu và mã nguồn của goose. Kunavo chưa thực sự dùng goose với các endpoint của mình — chưa thử phiên làm việc, truyền dữ liệu dạng luồng hay vòng gọi công cụ và nhận kết quả. Hãy giữ lại cách kết nối hiện đang hoạt động của bạn và trước tiên thử giao cho goose một nhiệm vụ nhỏ có đọc và ghi tệp.

Các thao tác thường dùng

• Mở phiên làm việc: goose session (có thể đặt tên bằng -n 名稱), sau đó dùng goose session --resume -n 名稱 để tiếp tục; goose session list liệt kê lịch sử.
• Chuyển chế độ cấp quyền: Nhập /mode trong phiên làm việc; có thể chọn auto, approve, chat hoặc smart_approve. Nếu muốn goose hỏi bạn trước mỗi bước, hãy dùng approve.
• Chọn mô hình: goose configure không cho phép nhập tên mô hình tùy chỉnh; với ID không có trong danh sách, hãy nhập trong goose Desktop hoặc đặt GOOSE_MODEL trong config.yaml.
• Tệp hướng dẫn dự án: Theo mặc định, goose đọc .goosehints và AGENTS.md (được điều khiển bởi CONTEXT_FILE_NAMES). Hãy ghi các quy tắc của dự án vào những tệp này để có thể mang theo khi chuyển sang tác nhân khác.
• Đừng chọn mô hình không hỗ trợ gọi công cụ: Tài liệu cho biết các mô hình đó “chỉ có thể thực hiện hoàn tất hội thoại”, và các tiện ích mở rộng cũng phải được tắt.

Một phiên làm việc tốn khoảng bao nhiêu?

Dưới đây là phép tính token để minh họa, không phải chi phí nhiệm vụ được đo thực tế và cũng không phải mức trần hóa đơn. Giả sử một phiên làm việc của tác nhân gửi tổng cộng 400.000 token đầu vào không được lưu trong bộ nhớ đệm qua nhiều lượt và nhận 25.000 token đầu ra (tác nhân gửi lại ngữ cảnh ở mỗi lượt nên lượng đầu vào đặc biệt lớn). Đơn giá được lấy từ mức giá hiện tại cho mỗi triệu token trong bảng giá Kunavo.

Về bộ nhớ đệm: tài liệu của goose cho biết khi dùng Claude thông qua các nhà cung cấp Anthropic, Amazon Bedrock, Databricks, OpenRouter và LiteLLM, goose sẽ tự động thêm dấu cache_control của Anthropic. Claude dùng qua nhà cung cấp OpenAI chung không nằm trong danh sách này, nên goose sẽ không thêm các dấu đó. Vì vậy, bảng trên giả định không có chiết khấu bộ nhớ đệm; đây là cách ước tính thận trọng. Số tiền trong bảng giá Kunavo là mức sàn tính phí, không phải mức trần: khi nhà cung cấp thượng nguồn báo chi phí, số tiền trên hóa đơn là giá trị cao hơn giữa “số tiền theo bảng giá” và “chi phí thượng nguồn × hệ số cộng thêm áp dụng”.

Thanh toán tại Đài Loan

Kunavo dùng hình thức nạp tiền trả trước, trừ phí theo token và không có phí hàng tháng. Mức nạp tối thiểu là $10, thanh toán qua Stripe; tại Đài Loan có thể dùng thẻ tín dụng (Visa, Mastercard, American Express, JCB, UnionPay), Apple Pay, Google Pay và Link; JKO Pay và LINE Pay không nằm trong danh sách khả dụng. Xem hướng dẫn thanh toán, sau đó tạo tài khoản và tạo khóa. Nếu muốn so sánh các proxy khác, hãy xem goose alternatives và goose vs Claude Code bằng tiếng Anh.

Câu hỏi thường gặp

Đã kiểm chứng vào ngày 1 tháng 10 năm 2026: tài liệu về cài đặt goose, nhà cung cấp, nhà cung cấp ACP, lệnh CLI và biến môi trường (nhánh main của aaif-goose/goose), cùng thông tin phiên bản và trạng thái lưu trữ từ GitHub API. Kunavo chưa thực sự dùng goose để chạy thử các endpoint của mình; giá được lấy từ bảng giá cập nhật trực tiếp, và mọi ví dụ về số tiền đều là phép tính token nhằm mục đích minh họa.