# Goose

Nguồn: https://docs.aicentos.com/vi/clients/goose

Language: vi

> Dùng aicentos trong Goose —— khai báo provider tương thích OpenAI tùy chỉnh

Goose là agent lập trình mã nguồn mở của Block, hỗ trợ hai cách trỏ đến một endpoint tương thích OpenAI: tái sử dụng provider `openai` tích hợp sẵn và ghi đè host, hoặc khai báo một provider tùy chỉnh độc lập. Khuyến nghị cách sau, thông tin endpoint tập trung hơn, cũng tiện để giữ đồng thời nhiều bộ cấu hình.

## Chuẩn bị

Trước tiên, tạo một Key riêng cho Goose tại trang "API Key" trong Console (khuyến nghị đặt tên `goose` để dễ theo dõi mức sử dụng):

* Console: [https://aicentos.com](https://aicentos.com)
* Tạo Key: [https://aicentos.com/keys](https://aicentos.com/keys)
* Nạp tiền khi hết số dư: [https://aicentos.com/wallet](https://aicentos.com/wallet)

## Cấu hình cần điền

| Trường                  | Giá trị                                          |
| ----------------------- | ------------------------------------------------ |
| File provider tùy chỉnh | `~/.config/goose/custom_providers/aicentos.json` |
| engine                  | `openai`                                         |
| base\_url               | `https://aicentos.com/v1/chat/completions`       |
| api\_key\_env           | `AICENTOS_API_KEY`                               |
| Mô hình                 | tên mô hình trong "Model Square" của Console     |

## Các bước thiết lập

### 1. Thiết lập biến môi trường API Key

```bash
export AICENTOS_API_KEY="sk-API-Key-của-bạn"
```

Ghi vào `~/.zshrc` hoặc `~/.bashrc` để lưu lâu dài. **Đừng ghi key vào config.yaml**, trang chính thức khuyến nghị rõ ràng dùng biến môi trường hoặc keychain hệ thống.

### 2. Khai báo provider tùy chỉnh

Tạo mới `~/.config/goose/custom_providers/aicentos.json` (trên Windows là `%APPDATA%\Block\goose\config\custom_providers\`):

```json
{
  "name": "aicentos",
  "engine": "openai",
  "display_name": "aicentos",
  "description": "Các mô hình do aicentos tích hợp",
  "api_key_env": "AICENTOS_API_KEY",
  "base_url": "https://aicentos.com/v1/chat/completions",
  "models": [
    {
      "name": "gpt-4o",
      "context_limit": 128000
    }
  ],
  "supports_streaming": true,
  "dynamic_models": true
}
```

Các trường bắt buộc là `name`, `engine`, `display_name`, `base_url`, `models`, trong đó `engine` nhận giá trị `openai` / `anthropic` / `ollama`.

Tên mô hình lấy "Model Square" của Console làm chuẩn, có thể tham khảo [Các mô hình hỗ trợ](https://docs.aicentos.com/vi/billing/models-list).

### 3. Đặt làm mặc định trong config.yaml

Sửa `~/.config/goose/config.yaml`:

```yaml
GOOSE_PROVIDER: aicentos
GOOSE_MODEL: gpt-4o
```

Khi khởi động, Goose sẽ quét thư mục `custom_providers/` và tự động đăng ký, sau đó cũng có thể chuyển đổi trong giao diện đồ hoạ.

## Kiểm tra

Trước dùng phiên không tương tác để xác minh:

```bash
goose run -t "Trả lời trong một câu: 1+1 bằng mấy"
```

Trả về bình thường nghĩa là kết nối thành công.

## Lưu ý

* **`base_url` phải ghi đến đường dẫn đầy đủ** (ở đây có `/v1/chat/completions`), khác với cách viết của phần lớn client. Nếu cần chỉ định đường dẫn tường minh, bản mới còn hỗ trợ trường `base_path`, độ ưu tiên của nó cao hơn việc phân tích URL.
* **Biến môi trường có độ ưu tiên cao hơn config.yaml**. Nếu trong shell đã export `OPENAI_HOST`, nó sẽ âm thầm ghi đè cấu hình trong file, khi xử lý sự cố chạy `env | grep -i openai` trước.
* Chỉ khi đã chọn provider, Goose mới khởi động bình thường. Nếu đã ghi cấu hình trong `config.yaml` nhưng chưa từng chạy `goose configure`, có thể báo `No provider configured` — đây là hiểu lầm phổ biến, mục cấu hình vốn là định dạng YAML, không phải `.env`.
* Khi `dynamic_models: true`, Goose sẽ gọi `/v1/models` của endpoint để kéo danh sách mô hình; nếu chỉ muốn hiển thị các mô hình chỉ định, xoá trường này hoặc đặt thành `false`.
* Một cách làm đơn giản khác là tái sử dụng provider tích hợp sẵn: đặt `GOOSE_PROVIDER: openai` trong config.yaml, rồi dùng `OPENAI_HOST` cộng `OPENAI_BASE_PATH` để ghép endpoint. Cách này đỡ tốn công hơn, nhưng liên kết chặt với biến môi trường hơn, dễ dính vấn đề ghi đè nêu trên.
* Thứ tự xử lý sự cố: tên provider có khớp hoàn toàn với tên file JSON không → `base_url` có chứa đường dẫn đầy đủ không → biến môi trường có hiển thị không → số dư có đủ không.

## Liên kết liên quan

* Tài liệu Provider tùy chỉnh: [https://block.github.io/goose/docs/api/providers/custom](https://block.github.io/goose/docs/api/providers/custom)