Cline

Cline là tác tử lập trình trong IDE, có thể đọc tệp dự án, thực thi lệnh và sửa mã sau khi được cho phép. Cấu hình OpenAI Compatible Provider để Cline dùng điểm vào tương thích Chat Completions của AGTCloud.

Hướng dẫn này dành cho tiện ích mở rộng Cline trong IDE. Mức hỗ trợ gọi công cụ, đầu vào hình ảnh, Computer Use và độ dài ngữ cảnh khác nhau giữa các mô hình; chọn mô hình mà API Key hiện tại nhìn thấy và hỗ trợ Chat Completions cùng gọi công cụ.

Chuẩn bị

Trước khi bắt đầu, hãy đảm bảo bạn đã:

Cài trình soạn thảo tương thích VS Code hoặc JetBrains IDE được hỗ trợ;
Đăng ký và đăng nhập AGTCloud;
Tạo token trên trang API Keys;
Sao chép ID mô hình mà token hiện tại có thể dùng và hỗ trợ Chat Completions từ danh mục mô hình;
Chuẩn bị dự án thử nghiệm không chứa mã nhạy cảm.

Cài đặt Cline

Chọn phương thức cài đặt cho IDE của bạn. Cline còn có CLI, SDK và Kanban; các cách dùng đó không nằm trong hướng dẫn này.

Áp dụng cho VS Code, Cursor, Windsurf, VSCodium và các trình soạn thảo tương tự:

Mở kho tiện ích mở rộng hoặc nhấn Ctrl/Cmd + Shift + X;
Tìm Cline;
Chọn tiện ích mở rộng Cline chính thức và nhấn cài đặt;
Nhấn biểu tượng Cline trên thanh hoạt động hoặc chạy Cline: Open In New Tab từ bảng lệnh.

Windsurf và VSCodium dùng Open VSX, với quy trình cài đặt tương tự.

Nếu lần mở đầu có lời nhắc cấp quyền hoặc khởi tạo Cline, hoàn tất theo giao diện phiên bản hiện tại. Xem tài liệu cài đặt Cline chính thức để biết cách cài khác.

Cấu hình AGTCloud

Mở API Configuration

Mở bảng Cline, nhấn biểu tượng cài đặt rồi vào API Configuration. Vị trí cài đặt có thể khác đôi chút theo IDE và phiên bản Cline.

Chọn Provider tương thích

Trong API Provider, chọn OpenAI Compatible. Không chọn Provider OpenAI tích hợp sẵn.

Điền thông tin kết nối

Trường Cline	Giá trị
`API Provider`	`OpenAI Compatible`
`Base URL`	`https://api.agtcloud.cn/v1`
`OpenAI Compatible API Key`	`your-api-key`
`Model ID` hoặc `Model`	`MODEL_ID`
`Custom Headers`	Để trống theo mặc định

Thay your-api-key và MODEL_ID bằng token và ID mô hình của bạn.

Kiểm tra và lưu

Nếu phiên bản hiện tại có nút Verify, kiểm tra kết nối trước. Sau khi đạt, nhấn Done hoặc nút lưu của giao diện hiện tại để hoàn tất cấu hình.

Base URL phải chứa /v1

OpenAI Compatible Provider của Cline cần API Base URL đầy đủ. Dùng https://api.agtcloud.cn/v1, không chỉ điền API Origin và không thêm /v1 nữa để tạo thành /v1/v1.

Chọn và cấu hình mô hình

MODEL_ID là giá trị giữ chỗ cần thay thế, không phải tên mô hình thực tế. Sao chép ID mô hình mà API Key hiện tại nhìn thấy và hỗ trợ Chat Completions cùng gọi công cụ từ danh mục mô hình.

Model Configuration của Cline có thể cung cấp tùy chọn nâng cao như Context Window, Max Output Tokens, Image Support, Computer Use, Input Price và Output Price. Giữ mặc định khi kết nối lần đầu; chỉ điều chỉnh khi biết giới hạn và khả năng thực tế của mô hình đích.

Thiết lập nâng cao không tạo ra khả năng của mô hình

Bật hỗ trợ hình ảnh hoặc Computer Use trong Cline không bổ sung khả năng đó cho mô hình không hỗ trợ. Trường giá chủ yếu dùng để ước tính mức sử dụng cục bộ trong Cline, không đại diện cho kết quả tính phí cuối cùng của AGTCloud.

Khởi chạy và kiểm tra kết nối

Mở dự án thử nghiệm

Dùng dự án không chứa mã nhạy cảm và xác nhận có README.md có thể đọc an toàn.

Giữ phê duyệt tự động ở trạng thái tắt

Không bật Auto Approve trong lần kiểm tra đầu. Khi Cline chuẩn bị đọc tệp, chạy lệnh hoặc sửa mã, kiểm tra thao tác trước rồi quyết định có cho phép không.

Gửi tác vụ chỉ đọc

Trong ô nhập Cline, gửi:

Hãy đọc README.md và tóm tắt mục đích dự án thành ba ý. Không sửa bất kỳ tệp nào.

Kiểm tra kết quả

Nếu Cline đọc tệp và trả về tóm tắt bình thường, không có thay đổi trái phép, kết nối cơ bản đã được thiết lập. Bước này phát sinh mức sử dụng API thông thường.

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

Hiện tượng	Kiểm tra trước	Cách xử lý
Tiện ích mở rộng Cline không xuất hiện	Nguồn cài đặt, tương thích IDE và trạng thái khởi động lại	Xác nhận đã cài tiện ích Cline chính thức, tải lại hoặc khởi động lại IDE
Kết nối `Verify` thất bại	Mạng và Base URL	Xác nhận máy cục bộ truy cập được AGTCloud và dùng `https://api.agtcloud.cn/v1` đầy đủ
Trả về `401`	Nội dung API Key và trạng thái token	Sao chép API Key hợp lệ, xác nhận không có khoảng trắng thừa
Trả về `403`	Quyền token, quyền mô hình và trạng thái tài khoản	Kiểm tra trạng thái token và phạm vi mô hình của tài khoản trong bảng điều khiển
Trả về `404`	Base URL, `/v1` lặp và ID mô hình	Xác nhận không có `/v1/v1`, sao chép lại ID mô hình đầy đủ
Báo Model Not Found	Mô hình mà Key hiện tại nhìn thấy và hỗ trợ giao thức	Chọn mô hình mà API Key nhìn thấy và hỗ trợ Chat Completions
Hội thoại hoạt động nhưng công cụ thất bại	Khả năng gọi công cụ và cấu hình nâng cao	Đổi sang mô hình hỗ trợ gọi công cụ, kiểm tra cấu hình ngữ cảnh và giới hạn đầu ra
Hình ảnh hoặc Computer Use thất bại	Khả năng thực tế của mô hình	Không chỉ dựa vào tùy chọn Cline; dùng phạm vi hỗ trợ thực tế của mô hình đích
Kết quả bất thường hoặc kết nối ngắt	Proxy mạng, tham số mô hình và giới hạn ngữ cảnh	Khôi phục cấu hình nâng cao mặc định trước, rồi kiểm tra proxy, tường lửa và giới hạn ngữ cảnh

Nếu chưa xác định được vấn đề, ghi lại thời gian yêu cầu, ID mô hình, trạng thái HTTP và lỗi đã loại thông tin nhạy cảm, rồi xem Lỗi và khắc phục sự cố. Không gửi API Key đầy đủ.

Khuyến nghị bảo mật

Không ghi API Key vào tệp dự án, kho Git, ảnh chụp màn hình, nhật ký hoặc cấu hình dùng chung;
Không kiểm tra lần đầu trong dự án chứa thông tin xác thực của môi trường production, dữ liệu riêng tư hoặc mã nguồn chưa công bố;
Giữ Auto Approve tắt trong lần đầu, xác nhận từng thao tác trước khi cho phép thực thi;
Trên thiết bị dùng chung, xóa API Key đã lưu trong Cline sau khi dùng.