Kết nối API mô hình AI với tác nhân Android trong FoneClaw
Cách dùng mô hình mặc định miễn phí hoặc cấu hình API Base URL, API Key và model ID trong FoneClaw, rồi kiểm tra một thao tác Android có quyền và phê duyệt.
- FoneClaw có hai đường dùng mô hình: dùng mô hình mặc định miễn phí hoặc cấu hình một mô hình tương thích bằng API Base URL, API Key và model ID.
- API Base URL xác định endpoint dịch vụ tương thích, API Key xác thực yêu cầu, còn model ID chọn đúng mô hình của nhà cung cấp; không bao giờ đưa khóa thật vào ảnh chụp hoặc ví dụ công khai.
- Kết nối model thành công mới chứng minh lớp suy luận hoạt động; thao tác Android vẫn cần công cụ được hỗ trợ, quyền theo ngữ cảnh, phê duyệt và kết quả hiển thị trong FoneClaw.
- FoneClaw hiện bổ sung quản lý từng công cụ, tùy chỉnh phê duyệt, phục hồi quyền và xử lý lỗi để kiểm tra phone action an toàn hơn.
Dùng mô hình mặc định hoặc kết nối API riêng
Câu trả lời ngắn cho kết nối API mô hình AI với tác nhân Android: trong FoneClaw, bạn có thể bắt đầu bằng mô hình mặc định miễn phí hoặc cấu hình một mô hình tương thích bằng API Base URL, API Key và model ID. Cả hai đường đều nằm trong FoneClaw. Mô hình giúp hiểu yêu cầu và lập kế hoạch; FoneClaw mới là runtime phone agent thực hiện các thao tác Android được hỗ trợ.
Điểm này rất quan trọng. Bạn không cần tưởng tượng hai ứng dụng tiêu dùng đang tự phối hợp với nhau. Khi một endpoint tương thích được cấu hình, model đó trở thành lớp suy luận bên trong FoneClaw Agent. Sau đó FoneClaw kiểm tra công cụ, quyền Android, phê duyệt theo rủi ro và kết quả hiển thị trước khi một hành động thật xảy ra trên điện thoại.
| Đường dùng model | Khi nào nên dùng | Điều cần chuẩn bị | Ranh giới |
|---|---|---|---|
| Mô hình mặc định miễn phí | Bắt đầu nhanh, thử tác vụ cơ bản, không muốn tự quản API Key | Cài FoneClaw và kiểm tra tác vụ ít rủi ro | Không cần endpoint riêng, nhưng vẫn phải tuân theo quyền và công cụ được hỗ trợ |
| Mô hình tương thích qua API | Muốn dùng provider, model hoặc endpoint riêng | API Base URL, API Key, model ID và mạng ổn định | Kết nối model không tự cấp quyền Android hoặc hỗ trợ mọi app |
Nếu bạn muốn hiểu sâu hơn lớp thực thi sau khi model đã lập kế hoạch, bài Điều khiển điện thoại bằng AI agent trên Android giải thích rõ đường đi từ yêu cầu đến công cụ, quyền và kết quả trên điện thoại.
API Base URL, API Key và model ID là gì
Ba trường cấu hình thường gây nhầm lẫn nhất là API Base URL, API Key và model ID. Chúng liên quan với nhau, nhưng không thay thế nhau. Nếu một trong ba sai, FoneClaw có thể không gọi được model, hoặc gọi được dịch vụ nhưng không chọn đúng mô hình bạn muốn dùng.
API Base URL là địa chỉ endpoint gốc của dịch vụ model tương thích. Nó cho FoneClaw biết yêu cầu nên gửi đến đâu. Một số nhà cung cấp hỗ trợ thư viện hoặc giao thức tương thích kiểu OpenAI nhưng vẫn dùng base URL riêng. tài liệu Gemini API về tương thích OpenAI là một ví dụ: nhà cung cấp có thể hỗ trợ cách gọi quen thuộc, nhưng endpoint và model name vẫn thuộc về họ. Vì vậy, đừng dùng lẫn Base URL của provider này cho provider khác.
API Key là khóa xác thực. Nó chứng minh yêu cầu được gửi từ tài khoản có quyền dùng dịch vụ. tài liệu xác thực API của OpenAI mô tả cách API key được dùng để xác thực request. Với bất kỳ provider nào, quy tắc an toàn giống nhau: không dán khóa thật vào ảnh chụp màn hình, không gửi khóa trong chat công khai, không lưu trong ghi chú không bảo vệ và xoay khóa nếu nghi ngờ bị lộ.
model ID là tên mô hình mà provider yêu cầu. Nó có thể trông giống một chuỗi ngắn, một phiên bản model hoặc một tên triển khai. Một API Key đúng nhưng model ID sai vẫn có thể tạo lỗi. Một Base URL đúng nhưng thiếu model ID cũng chưa đủ để biết cần gọi model nào.
| Trường | Nghĩa thực tế | Lỗi thường gặp |
|---|---|---|
| API Base URL | Endpoint gốc của dịch vụ model tương thích | Sai đường dẫn, thiếu HTTPS, dùng URL của provider khác |
| API Key | Khóa xác thực request | Dán thiếu ký tự, dùng khóa hết hạn, để lộ khóa trong ví dụ |
| model ID | Tên model mà provider chấp nhận | Gõ sai tên, dùng model không bật trong tài khoản, nhầm phiên bản |
Khi cần viết ví dụ nội bộ, hãy dùng placeholder như API_KEY_CUA_BAN hoặc MODEL_ID_CUA_PROVIDER. Không dùng khóa thật, kể cả trong tài liệu nhóm nhỏ.
Cấu hình mô hình trong FoneClaw từng bước
Trước khi mở FoneClaw, hãy chuẩn bị thông tin từ provider: endpoint tương thích, API Key còn hiệu lực và model ID chính xác. Nếu provider có nhiều vùng, nhiều đường API hoặc nhiều phiên bản model, hãy chọn đúng bộ tương thích với tài khoản của bạn. Đừng đoán Base URL bằng cách ghép chuỗi thủ công nếu provider đã có tài liệu cấu hình riêng.
- Mở FoneClaw trên điện thoại Android và vào phần cấu hình Agent hoặc model.
- Chọn giữ mô hình mặc định miễn phí nếu bạn chỉ muốn thử nhanh, hoặc chọn cấu hình endpoint tương thích nếu bạn muốn dùng model riêng.
- Nhập API Base URL từ provider. Ưu tiên HTTPS và kiểm tra không có khoảng trắng thừa ở đầu hoặc cuối.
- Nhập API Key. Không đọc to khóa, không chụp màn hình chứa khóa và không gửi khóa cho người khác để sửa hộ.
- Nhập model ID đúng theo provider. Nếu provider phân biệt chữ hoa, dấu gạch hoặc phiên bản, hãy giữ nguyên.
- Lưu cấu hình và chọn model đó làm model đang dùng trong FoneClaw.
- Chạy kiểm tra kết nối bằng một yêu cầu không nhạy cảm trước khi thử thao tác Android.
Theo dự án FoneClaw Android, FoneClaw là Android phone agent và hỗ trợ cấu hình model bên trong luồng sản phẩm của mình. Điều người dùng cần nhớ là cấu hình model chỉ thay đổi lớp suy luận. Nó không tự mở quyền Android, không bật mọi công cụ và không biến một provider thành ứng dụng điều khiển điện thoại.
Nếu bạn đang cân nhắc nhiều model cho phone agent thay vì chỉ thiết lập một endpoint, bài Kimi K3, DeepSeek V4 và GLM-5.2: chọn mô hình cho phone agent phù hợp hơn cho phần so sánh và routing.
Kiểm tra kết nối model trước khi điều khiển điện thoại
Sau khi lưu cấu hình, đừng bắt đầu bằng tác vụ nhạy cảm. Một kết nối model thành công chỉ chứng minh FoneClaw có thể gửi yêu cầu đến model và nhận phản hồi. Nó chưa chứng minh công cụ Android chạy đúng, quyền đã sẵn sàng hoặc hành động có tác động đã được phê duyệt.
Hãy kiểm tra theo ba nấc. Nấc đầu tiên là yêu cầu suy luận thuần: “Tóm tắt trong một câu vì sao cần kiểm tra quyền trước khi gửi tin nhắn.” Nếu phản hồi đến đúng, endpoint, API Key và model ID có khả năng đã hoạt động. Nấc thứ hai là yêu cầu lập kế hoạch không thực thi: “Nếu tôi muốn tạo nhắc việc, hãy nêu các bước cần kiểm tra.” Mục tiêu là xem model có hiểu ranh giới công cụ và phê duyệt không.
Nấc thứ ba mới là thao tác Android ít rủi ro, chẳng hạn mở một app không nhạy cảm hoặc chuẩn bị một bản nháp chưa gửi. Lúc này FoneClaw phải đi qua lớp công cụ, trạng thái thiết bị, quyền nếu cần và kết quả hiển thị. Nếu thao tác dừng vì thiếu quyền, đó không phải lỗi model API; đó là ranh giới Android cần xử lý đúng.
Một bài kiểm tra tốt nên ghi lại bốn điều: model có phản hồi không, phản hồi có đúng ý định không, công cụ Android có được gọi trong phạm vi hỗ trợ không, và kết quả có hiển thị rõ cho người dùng không. Chỉ khi cả bốn đều ổn, bạn mới nên mở rộng sang tác vụ có phê duyệt như gửi nội dung, chỉnh cài đặt hoặc workflow nhiều bước.
Sửa lỗi 401, 404, timeout, model và quyền Android
Lỗi cấu hình thường bị trộn vào nhau. Người dùng thấy “không chạy” nhưng không biết lỗi nằm ở API Key, Base URL, model ID, mạng, công cụ Android hay quyền hệ thống. Cách sửa nhanh hơn là đọc triệu chứng theo lớp.
| Triệu chứng | Nguyên nhân có thể | Cách xử lý |
|---|---|---|
| 401 hoặc lỗi xác thực | API Key sai, hết hạn, không có quyền gọi endpoint, hoặc thiếu định dạng xác thực provider yêu cầu | Tạo khóa mới nếu cần, dán lại cẩn thận, kiểm tra tài khoản provider và không chia sẻ khóa thật |
| 404 hoặc không tìm thấy endpoint | API Base URL sai, thiếu phần đường dẫn tương thích, dùng endpoint của provider khác | Đối chiếu tài liệu provider, kiểm tra HTTPS, bỏ khoảng trắng và không tự đoán đường API |
| Model không tồn tại | model ID sai, model chưa bật cho tài khoản hoặc nhầm tên phiên bản | Sao chép model ID đúng từ provider và thử một model đơn giản hơn nếu có |
| Timeout | Mạng yếu, endpoint chậm, model quá nặng hoặc request quá dài | Thử mạng ổn định hơn, rút ngắn prompt, chọn model nhanh hơn hoặc kiểm tra trạng thái provider |
| Model trả lời được nhưng phone action không chạy | Model API ổn nhưng công cụ Android chưa hỗ trợ, chưa bật hoặc thiếu quyền | Kiểm tra công cụ trong FoneClaw, cấp quyền theo ngữ cảnh và thử tác vụ ít rủi ro hơn |
| Hành động dừng ở bước phê duyệt | Chính sách FoneClaw yêu cầu người dùng xem lại trước tác động bên ngoài | Đọc nội dung, kiểm tra mục tiêu và xác nhận nếu đúng; không coi đây là lỗi tốc độ |
401 thường liên quan đến xác thực, nhưng từng provider có thể đặt thông báo lỗi khác nhau. 404 thường gợi ý sai đường endpoint, nhưng cũng có thể do provider không bật đường tương thích đó cho tài khoản của bạn. Timeout không nhất thiết là FoneClaw lỗi; nó có thể là model chậm, mạng yếu hoặc request quá lớn.
Quan trọng nhất: API access và Android permission là hai thế giới riêng. Một API Key đúng không cấp quyền đọc danh bạ, mở app, gửi tin hoặc đổi cài đặt trên điện thoại. Ngược lại, một quyền Android đã cấp cũng không sửa được model ID sai. Tách hai lớp này giúp bạn sửa lỗi nhanh hơn và an toàn hơn.
Chọn mô hình cho thao tác Android
Khi dùng mô hình tùy chỉnh cho tác nhân điện thoại, đừng chọn chỉ vì model đó nổi tiếng. Phone agent cần một model biết hiểu yêu cầu ngắn, lập kế hoạch rõ, gọi công cụ có cấu trúc, nhận ra khi thiếu dữ kiện và dừng đúng lúc trước hành động có rủi ro. Tốc độ quan trọng, nhưng tốc độ không thay thế độ ổn định.
Hãy đánh giá theo năm tiêu chí. Một là độ trễ: model có phản hồi đủ nhanh cho thao tác điện thoại không? Hai là độ tin cậy khi làm nhiều bước: model có giữ mục tiêu ban đầu không? Ba là khả năng làm việc với công cụ: model có xuất ra ý định và tham số đủ rõ không? Bốn là chi phí: tác vụ lặp lại có phù hợp ngân sách không? Năm là dữ liệu: bạn có chấp nhận dữ liệu yêu cầu được gửi đến provider đó không?
Nếu bạn đang cân nhắc DeepSeek, Grok hoặc các provider cụ thể, hãy đọc theo từng trường hợp thay vì gom thành một bảng thắng thua. Bài DeepSeek, trợ lý AI và điều khiển điện thoại Android: có thể và không thể làm gì giúp hiểu một hướng provider cụ thể, còn Grok có điều khiển điện thoại Android được không? giải thích cách tách model reasoning khỏi runtime Android.
Kết luận thực dụng: model càng hợp workflow, FoneClaw càng ít phải hỏi lại hoặc phục hồi lỗi. Nhưng model không tự thực hiện Android action. FoneClaw vẫn là lớp quản trị công cụ, quyền, phê duyệt và kết quả.
Biến model đã kết nối thành hành động điện thoại có kiểm soát
Sau khi model kết nối ổn, hãy biến nó thành một hành động điện thoại có kiểm soát bằng quy trình hẹp. Người dùng đưa yêu cầu, model trong FoneClaw lập kế hoạch, FoneClaw chọn công cụ Android được hỗ trợ, kiểm tra quyền, hiển thị bước quan trọng, yêu cầu phê duyệt nếu hành động có tác động, rồi xác minh kết quả.
FoneClaw hiện bổ sung quản lý từng công cụ, tùy chỉnh phê duyệt, phục hồi quyền và xử lý lỗi tốt hơn. Những cải tiến này giúp người dùng không phải chỉ “bật tất cả” hoặc “tắt tất cả”. Bạn có thể thử một công cụ ít rủi ro trước, rồi mới mở rộng sang gửi nội dung, lịch, mail hoặc workflow nhiều bước. Nếu muốn dùng phiên bản hiện tại, hãy bắt đầu từ trang Tải FoneClaw cho Android.
FoneClaw hỗ trợ hơn 100 công cụ tích hợp cho các thao tác Android được quản trị. Các công cụ này là phần biến kế hoạch thành hành động, nhưng từng hành động vẫn phải nằm trong phạm vi hỗ trợ, quyền và chính sách. Bạn có thể xem các nhóm khả năng trên trang tính năng FoneClaw.
Bài kiểm tra an toàn đầu tiên nên là một việc có thể xem lại: mở app, tạo bản nháp, đọc trạng thái được phép hoặc chuẩn bị nhắc việc. Khi bạn thấy model hiểu đúng, công cụ chạy đúng, quyền được hướng dẫn đúng và kết quả hiển thị rõ, lúc đó cấu hình model mới thật sự sẵn sàng cho phone-agent workflow hằng ngày.