Kết nối API mô hình AI trên Android: kiểm tra văn bản, ảnh và công cụ
Cấu hình nhà cung cấp, API Base URL, API Key và model ID trong FoneClaw; kiểm tra riêng văn bản, ảnh và công cụ Android để xác định đúng lớp lỗi.
- FoneClaw cho phép dùng mô hình mặc định miễn phí hoặc cấu hình mô hình trực tuyến tương thích. Gói thuê bao ứng dụng trò chuyện không đồng nghĩa với quyền truy cập và thanh toán API.
- Cấu hình sẵn của nhà cung cấp giúp thiết lập thuận tiện hơn, nhưng bạn vẫn cần kiểm tra API Base URL, API Key và model ID. Tùy chọn hỗ trợ ảnh và gọi công cụ phải khớp với khả năng thật của mô hình cùng endpoint.
- Hãy thử riêng một yêu cầu văn bản, một ảnh không nhạy cảm và một công cụ chỉ đọc trạng thái Android. Văn bản trả lời được chưa chứng minh mô hình hiểu ảnh hoặc gọi công cụ thành công.
- Lỗi xác thực, endpoint, vòng đời mô hình và quyền Android cần xử lý ở các lớp khác nhau. Sau khi đổi mô hình, kiểm tra lại cấu hình và kết quả tác vụ cũ trước khi lặp hành động gửi hoặc ghi dữ liệu.
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 trê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 trực tuyến 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; các công cụ Android được bật thực hiện thao tác trong phạm vi quyền, trạng thái ứng dụng và chính sách phê duyệt đang áp dụng.
Bạn không cần hai ứng dụng trò chuyện tự phối hợp với nhau. Khi endpoint tương thích được cấu hình, mô hình đó trở thành lớp suy luận bên trong FoneClaw. Tuy nhiên, tài khoản hoặc gói thuê bao của ứng dụng trò chuyện không tự bảo đảm quyền gọi API: hãy kiểm tra quyền truy cập, thanh toán và mô hình được cung cấp trong tài khoản API riêng.
| Đường dùng mô hình | 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 | Mở 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 nhà cung cấp, mô hình hoặc endpoint riêng | API Base URL, API Key, model ID và mạng ổn định | Kết nối mô hình không tự cấp quyền Android hoặc hỗ trợ mọi ứng dụng |
Nếu muốn hiểu sâu hơn lớp thực thi sau khi mô hình lập kế hoạch, bài AI agent điều khiển điện thoại Android: từ ý định đến hành động giải thích đường đi từ yêu cầu đến công cụ, quyền và kết quả trên điện thoại.
Hiểu cấu hình nhà cung cấp, API Base URL, API Key và model ID
Cấu hình sẵn của nhà cung cấp giúp bạn bắt đầu thuận tiện hơn, nhưng không thay thế tài khoản API hoặc việc kiểm tra tính tương thích. API Base URL, API Key và model ID liên quan với nhau nhưng không thay thế nhau. Nếu một trường sai, FoneClaw có thể không gọi được dịch vụ hoặc không chọn đúng mô hình.
API Base URL là địa chỉ gốc của endpoint tương thích, cho FoneClaw biết cần gửi yêu cầu đến đâu. Một số nhà cung cấp hỗ trợ giao thức tương thích kiểu OpenAI nhưng vẫn dùng địa chỉ riêng. Tài liệu Gemini API về tương thích OpenAI minh họa sự phân biệt này: cách gọi có thể tương thích, nhưng endpoint và tên mô hình vẫn do nhà cung cấp quy định. Đừng dùng lẫn Base URL giữa các dịch vụ.
API Key là khóa xác thực yêu cầu. Tài liệu xác thực API của OpenAI giải thích vai trò của khóa trong xác thực. Với bất kỳ nhà cung cấp nào, hãy giữ khóa riêng tư: không đưa khóa thật vào ảnh chụp màn hình, trò chuyện công khai hoặc ghi chú không được bảo vệ; thay khóa nếu nghi ngờ bị lộ.
model ID là định danh chính xác mà endpoint chấp nhận. Nó có thể là tên mô hình, tên phiên bản hoặc tên triển khai. Khóa đúng nhưng model ID sai vẫn có thể gây lỗi; tên hiển thị trong ứng dụng trò chuyện cũng chưa chắc là định danh API cần dùng.
| Trường hoặc tùy chọn | Nghĩa thực tế | Điều cần kiểm tra |
|---|---|---|
| Cấu hình sẵn của nhà cung cấp | Hỗ trợ thiết lập thông tin kết nối | Vẫn đối chiếu endpoint và quyền tài khoản |
| API Base URL | Địa chỉ gốc của dịch vụ tương thích | Đúng đường dẫn và giao thức, không có khoảng trắng thừa |
| API Key | Xác thực yêu cầu với nhà cung cấp | Khóa còn hiệu lực và có quyền truy cập |
| model ID | Chọn mô hình mà endpoint cung cấp | Định danh chính xác, có trong tài khoản đang dùng |
| Hỗ trợ ảnh | Cấu hình cách sử dụng đầu vào hình ảnh | Mô hình và endpoint thực sự hỗ trợ hiểu ảnh |
| Hỗ trợ gọi công cụ | Cấu hình khả năng gửi yêu cầu công cụ có cấu trúc | Mô hình và endpoint hỗ trợ định dạng gọi công cụ tương thích |
Khi cần minh họa cấu hình, dùng ký hiệu thay thế như API_KEY_CUA_BAN hoặc MODEL_ID_CUA_NHA_CUNG_CAP. 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 và khả năng trong FoneClaw
Trước khi mở FoneClaw, hãy chuẩn bị endpoint tương thích, API Key còn hiệu lực và model ID chính xác. Nếu nhà cung cấp có nhiều vùng hoặc nhiều đường API, chọn đúng bộ thông tin cho tài khoản của bạn. Đừng đoán Base URL bằng cách ghép chuỗi khi đã có tài liệu cấu hình.
- Mở phần cấu hình mô hình trong FoneClaw trên Android.
- Giữ mô hình mặc định miễn phí nếu muốn thử nhanh, hoặc chọn cấu hình mô hình trực tuyến tương thích.
- Chọn cấu hình sẵn của nhà cung cấp nếu phù hợp, rồi đối chiếu API Base URL với tài liệu của dịch vụ.
- Nhập API Key riêng của bạn. Không đọc to hoặc chia sẻ ảnh chứa khóa để nhờ sửa lỗi.
- Nhập model ID đúng theo endpoint, giữ nguyên các ký tự và tên phiên bản cần thiết.
- Đặt tùy chọn hỗ trợ ảnh và gọi công cụ theo khả năng được nhà cung cấp xác nhận cho mô hình đó.
- Lưu cấu hình, chọn mô hình đang dùng và bắt đầu bằng yêu cầu văn bản không nhạy cảm.
Trong FoneClaw, các cấu hình sẵn và tùy chọn hỗ trợ ảnh, công cụ giúp bạn khai báo cách dùng mô hình. Bật tùy chọn không tạo thêm khả năng thị giác hoặc gọi công cụ cho một mô hình vốn không hỗ trợ. Cấu hình mô hình cũng không tự mở quyền Android hoặc bật mọi công cụ. Bạn có thể xem phạm vi cấu hình và thao tác trên trang tính năng FoneClaw; dự án FoneClaw Android cung cấp thêm thông tin về ứng dụng.
Nếu đang cân nhắc nhiều mô hình 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 lựa chọn và phân luồng mô hình.
Kiểm tra riêng văn bản, ảnh và công cụ Android
Sau khi lưu cấu hình, đừng bắt đầu bằng tác vụ nhạy cảm. Một câu trả lời văn bản chỉ chứng minh đường gửi và nhận văn bản đã hoạt động cho yêu cầu đó. Nó chưa chứng minh mô hình hiểu ảnh, gọi công cụ đúng định dạng hoặc thực hiện được thao tác Android.
- Thử văn bản: hỏi “Tóm tắt trong một câu vì sao cần kiểm tra người nhận trước khi gửi tin nhắn.” Kết quả cần thấy là câu trả lời liên quan đến yêu cầu, không có lỗi xác thực hoặc không tìm thấy mô hình.
- Thử ảnh: nếu mô hình hỗ trợ thị giác, chọn một ảnh không nhạy cảm rồi yêu cầu mô tả một chi tiết nhìn thấy được. Đối chiếu câu trả lời với chính ảnh đó; phản hồi chung chung không chứng minh ảnh đã được xử lý.
- Thử công cụ: nếu mô hình và endpoint hỗ trợ gọi công cụ, bật một công cụ chỉ đọc trạng thái phù hợp, chẳng hạn kiểm tra âm lượng hoặc trạng thái Bluetooth. Yêu cầu đọc trạng thái, không thay đổi cài đặt, rồi đối chiếu kết quả với điện thoại.
FoneClaw tối ưu ảnh lớn được chọn và xử lý đúng hướng ảnh để chuẩn bị đầu vào, nhưng việc hiểu nội dung vẫn cần mô hình thị giác tương thích. Chỉ gửi phần ảnh cần thiết; mô hình trực tuyến có thể nhận ngữ cảnh bạn cung cấp, nên không mặc định rằng toàn bộ xử lý nằm trên điện thoại.
Ở phép thử công cụ, mô hình trong FoneClaw diễn giải yêu cầu và đề xuất lời gọi; công cụ Android thực thi theo trạng thái ứng dụng, quyền và chính sách phê duyệt hiện tại. Nếu công cụ bị chặn vì thiếu quyền, đó là lớp Android cần xử lý, không phải bằng chứng khóa API sai. Một kế hoạch viết bằng văn bản cũng không chứng minh công cụ đã chạy.
Sửa lỗi xác thực, mô hình, ảnh, công cụ và quyền Android
Lỗi “không chạy” có thể nằm ở khóa API, endpoint, model ID, mạng, khả năng mô hình hoặc quyền hệ thống. Đọc thông báo lỗi theo lớp trước khi đổi nhiều thiết lập cùng lúc.
| Triệu chứng | Nguyên nhân có thể | Cách xử lý |
|---|---|---|
| 401 hoặc lỗi xác thực | Khóa sai, hết hiệu lực, thiếu quyền truy cập hoặc định dạng xác thực không đúng | Kiểm tra tài khoản và yêu cầu xác thực của nhà cung cấp; thay khóa nếu cần, không chia sẻ khóa thật |
| 404 hoặc không tìm thấy endpoint, mô hình | Sai Base URL, đường dẫn hoặc model ID; tài khoản không có mô hình đó | Đối chiếu endpoint và danh sách mô hình thực tế của tài khoản |
| Thông báo mô hình ngừng cung cấp | Định danh đã bị ngừng phục vụ theo lịch của nền tảng | Kiểm tra vòng đời và mô hình thay thế, không sửa quyền Android để xử lý lỗi này |
| Timeout | Mạng gián đoạn, dịch vụ chậm hoặc yêu cầu quá lớn | Thử văn bản ngắn trên mạng ổn định, kiểm tra trạng thái nhà cung cấp trước khi thử lại |
| Văn bản được nhưng ảnh thất bại | Mô hình không hỗ trợ thị giác, endpoint không nhận định dạng ảnh hoặc tùy chọn chưa phù hợp | Kiểm tra hỗ trợ ảnh của cả mô hình và endpoint, thử một ảnh nhỏ không nhạy cảm |
| Mô hình trả lời nhưng không gọi công cụ | Thiếu hỗ trợ gọi công cụ, định dạng không tương thích hoặc tùy chọn chưa đúng | Đối chiếu tài liệu nhà cung cấp và cấu hình hỗ trợ công cụ |
| Công cụ được gọi nhưng thao tác Android bị chặn | Công cụ chưa bật, thiếu quyền hoặc trạng thái ứng dụng chưa phù hợp | Kiểm tra công cụ và quyền theo ngữ cảnh, rồi thử lại một thao tác chỉ đọc |
| Hành động chờ phê duyệt | Chính sách đang áp dụng yêu cầu người dùng xem lại | Kiểm tra nội dung và mục tiêu, chỉ xác nhận khi đúng; không coi đây là lỗi kết nối |
401 thường liên quan đến xác thực, còn 404 có thể liên quan endpoint hoặc mô hình; thông báo cụ thể tùy nhà cung cấp. Một mô hình được thông báo sắp ngừng dùng chưa nhất thiết đã ngừng phục vụ. Hãy đọc trạng thái và ngày hiệu lực thay vì suy từ một nhãn duy nhất.
Quyền API và quyền Android là hai lớp riêng. Khóa đúng không cấp quyền truy cập tài nguyên điện thoại; quyền Android đã cấp cũng không sửa được model ID sai. Nếu nguyên nhân là gián đoạn dịch vụ tạm thời, bài Khi mô hình trợ lý AI trên Android bị gián đoạn: cách thử lại, đổi mô hình và tiếp tục an toàn hướng dẫn cách xử lý mà không lặp tác động đã xảy ra.
Chọn mô hình và kiểm tra vòng đời API
Khi dùng mô hình tùy chỉnh cho tác nhân điện thoại, đừng chọn chỉ vì tên nổi tiếng. Hãy xem khả năng hiểu yêu cầu, xử lý ảnh nếu cần, gọi công cụ có cấu trúc, nhận ra dữ kiện còn thiếu, chi phí và dữ liệu được gửi đến nhà cung cấp. Mô hình phù hợp vẫn cần endpoint tương thích và kiểm tra trên tác vụ của bạn.
Một ví dụ bảo trì API có mốc cụ thể: tài liệu vòng đời mô hình của Anthropic ghi nhận claude-sonnet-4-5-20250929 được đánh dấu không còn khuyến nghị dùng từ ngày 30/9/2026, với ngày dự kiến ngừng phục vụ 30/11/2026; mô hình thay thế được khuyến nghị là claude-sonnet-5-5. Trạng thái không còn khuyến nghị vẫn cho phép mô hình hoạt động, khác với ngừng phục vụ, khi yêu cầu sẽ thất bại.
Các mốc này áp dụng cho nền tảng do Anthropic vận hành; nền tảng đối tác có thể dùng lịch khác. Tên mô hình thay thế cũng không chứng minh endpoint của bạn cung cấp nó. Đặc biệt, API Messages gốc của Anthropic không được mặc định là tương thích với cấu hình endpoint kiểu OpenAI trong FoneClaw. Hãy kiểm tra giao thức, cách xác thực và định danh mà dịch vụ đang dùng hỗ trợ.
Nếu đang cân nhắc nhà cung cấp cụ thể, 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 lựa chọn, còn Grok có điều khiển điện thoại Android được không? giải thích cách tách suy luận của mô hình khỏi thực thi Android. Sau mỗi lần đổi nhà cung cấp hoặc mô hình, thực hiện lại ba phép thử văn bản, ảnh và công cụ phù hợp; không suy ra khả năng mới từ lần thử của mô hình cũ.
Thử lại cấu hình và tiếp tục hành động có kiểm soát
Sau khi kết nối ổn, bắt đầu bằng một yêu cầu chỉ đọc trạng thái điện thoại. Mô hình trong FoneClaw hiểu yêu cầu và lập kế hoạch; công cụ được bật thực hiện bước hỗ trợ trong phạm vi quyền và chính sách phê duyệt đang áp dụng. Không phải mọi công cụ đều luôn yêu cầu xác nhận, nên hãy kiểm tra cấu hình thực tế trước tác vụ có tác động.
Nếu đang tiếp tục một tác vụ bị ngắt, kiểm tra kết quả cũ trước khi chạy lại. Mở lịch để xem sự kiện đã tồn tại chưa; kiểm tra đúng tài khoản thư để biết thư đã gửi chưa. Nội dung trả lời trong cuộc trò chuyện hoặc thông báo timeout không đủ để kết luận hành động chưa xảy ra. Chỉ tiếp tục bước còn thiếu để tránh gửi hoặc ghi dữ liệu lần nữa.
Khi chưa rõ bước nào đã hoàn tất, bài Gỡ lỗi và khôi phục tác nhân điện thoại Android: checklist, nguyên nhân gốc và cách chạy lại an toàn giúp phân loại trạng thái trước khi thử lại. Bạn có thể đối chiếu các nhóm khả năng trên trang tính năng FoneClaw và xem lựa chọn cài đặt trên trang Tải FoneClaw cho Android.