Hướng dẫn cấu hình Goose với Beeknoee

Goose là gì?

Goose là AI coding agent mã nguồn mở do Block phát triển, nay đã được trao cho Linux Foundation (Agentic AI Foundation) nên trung lập, không thuộc sở hữu công ty nào. Goose chạy được cả ở terminal (CLI) lẫn ứng dụng desktop, tự đọc/sửa/chạy code và gọi được công cụ ngoài qua MCP.

💡 Goose nhận bất kỳ endpoint OpenAI-compatible nào, nên dùng Beeknoee được ngay — kể cả tính năng tự tải danh sách model.

Yêu cầu

• macOS, Linux hoặc Windows
• API Key từ Beeknoee Platform

📌 Bước 1: Tạo API Key

1. Truy cập https://platform.beeknoee.com/api-keys
2. Đăng nhập bằng tài khoản Google
3. Nhấn "Tạo API Key"
4. Copy API Key (dạng sk-bee-xxxx...)

⚠️ API key chỉ hiển thị 24 giờ đầu — copy và lưu ngay!

📌 Bước 2: Cài đặt Goose

Tải bản CLI hoặc Desktop tại trang chủ Goose. Sau khi cài, kiểm tra:

goose --version

📌 Bước 3: Cấu hình Beeknoee

Goose có hai cách. Cách 1 nhanh hơn, cách 2 linh hoạt hơn.

Cách 1: Dùng provider OpenAI có sẵn (khuyên dùng)

Goose đã có sẵn provider openai; chỉ cần trỏ nó về Beeknoee bằng biến môi trường:

export OPENAI_API_KEY="sk-bee-YOUR_API_KEY"
export OPENAI_HOST="https://platform.beeknoee.com"
export OPENAI_BASE_PATH="v1/chat/completions"

$env:OPENAI_API_KEY = "sk-bee-YOUR_API_KEY"
$env:OPENAI_HOST = "https://platform.beeknoee.com"
$env:OPENAI_BASE_PATH = "v1/chat/completions"

[System.Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-bee-YOUR_API_KEY", "User")
[System.Environment]::SetEnvironmentVariable("OPENAI_HOST", "https://platform.beeknoee.com", "User")
[System.Environment]::SetEnvironmentVariable("OPENAI_BASE_PATH", "v1/chat/completions", "User")

⚠️ Chú ý cách chia đôi URL. Goose tách riêng host và đường dẫn: OPENAI_HOST chỉ là tên miền (không có /v1), còn OPENAI_BASE_PATH là phần đường dẫn (không có dấu / ở đầu). Đây là điểm khác với hầu hết công cụ khác vốn chỉ cần một Base URL kết thúc bằng /v1.

Rồi chạy:

goose configure

Chọn Configure Providers → OpenAI → chọn model bạn muốn dùng.

Cách 2: Khai báo custom provider (khi cần nhiều cấu hình riêng)

Chạy:

goose configure

Chọn Custom Providers → Add A Custom Provider, rồi điền:

Hoặc tạo thẳng file JSON:

Tạo file beeknoee.json:

{
  "name": "beeknoee",
  "engine": "openai",
  "display_name": "Beeknoee",
  "description": "Beeknoee AI Proxy",
  "api_key_env": "BEEKNOEE_API_KEY",
  "base_url": "https://platform.beeknoee.com/v1/chat/completions",
  "models": [
    { "name": "deepseek/deepseek-v3.2", "context_limit": 128000 }
  ],
  "supports_streaming": true,
  "requires_auth": true
}

Rồi đặt biến môi trường BEEKNOEE_API_KEY bằng API key của bạn.

🔴 Đây là chỗ dễ sai nhất. Ở custom provider, base_url phải là URL ĐẦY ĐỦ kèm /chat/completions, không phải chỉ /v1 như các công cụ khác. Điền thiếu sẽ báo lỗi 404.

💡 File cấu hình mới có hiệu lực từ phiên Goose tiếp theo — thoát và mở lại goose.

📌 Bước 4: Sử dụng

cd /path/to/your/project
goose session

Một số lệnh hay dùng:

Models khuyên dùng với Goose

💡 Model ID chính xác và giá theo thời gian thực xem tại trang Các Mô Hình AI — ấn nút Copy ID.

🆓 Models miễn phí qua BeeSynapse

Khi đã kết nối email tại trang BeeSynapse Integrations, hệ thống tự động ưu tiên free quota:

Bạn không cần đổi cấu hình — Beeknoee tự route qua free quota trước, hết quota mới trừ VNĐ.

Xử lý lỗi

Lỗi 404 khi gọi model

Kiểm tra lại cách chia URL — đây là lỗi hay gặp nhất với Goose:

• Dùng provider OpenAI: OPENAI_HOST = https://platform.beeknoee.com (không /v1), OPENAI_BASE_PATH = v1/chat/completions (không có / đầu)
• Dùng custom provider: base_url = https://platform.beeknoee.com/v1/chat/completions (đầy đủ)

"Unauthorized" hoặc "Invalid API key"

• Kiểm tra biến môi trường đã được nạp chưa:

  echo $OPENAI_API_KEY
  

• Key phải bắt đầu bằng sk-bee-
• Kiểm tra key chưa bị thu hồi tại API Keys

Goose không thấy custom provider vừa tạo

• Thoát hẳn Goose và mở lại — cấu hình chỉ nạp khi khởi động phiên mới
• Kiểm tra file JSON đúng cú pháp (thiếu dấu phẩy là hỏng cả file)

Model suy luận bị timeout

Model reasoning có thể "nghĩ" hơn 120 giây. Đảm bảo supports_streaming để true trong cấu hình. Xem Error Handling.

So sánh với các agent khác

HOÀN TẤT! 🎉

Cần hỗ trợ thêm? Sử dụng Support Chat (góc dưới phải trên platform) hoặc liên hệ qua email.