Chạy Chatwoot Captain trên một endpoint tương thích OpenAI tùy chỉnh.

Câu trả lời nhanh: ba cấu hình Captain trong Super Admin.

Trên Chatwoot tự host hiện tại, cài đặt LLM của Captain là các config cài đặt, không phải biến .env; file .env.example đi kèm nói rõ điều này và trỏ bạn tới Super Admin, App Configs, Captain. Ba giá trị quan trọng: CAPTAIN_OPEN_AI_API_KEY nhận key gateway, CAPTAIN_OPEN_AI_MODEL nhận id model, và CAPTAIN_OPEN_AI_ENDPOINT nhận host endpoint. Giá trị endpoint có một điểm cần chú ý: đưa nó không kèm hậu tố /v1. Bộ khởi tạo của Chatwoot tự xây API base bằng cách cắt dấu gạch chéo cuối rồi nối thêm /v1, và mô tả của chính config này cho thấy mặc định là https://api.openai.com/ đúng theo hình dạng đó. Với APIsRouter, nhập https://api.apisrouter.com và để Chatwoot tự suy ra https://api.apisrouter.com/v1. Các config này được đọc khi app khởi động, nên hãy khởi động lại Chatwoot sau khi thay đổi chúng.

CAPTAIN_OPEN_AI_API_KEY:  sk-YOUR-APISROUTER-KEY
CAPTAIN_OPEN_AI_MODEL:    claude-haiku-4-5-20251001
CAPTAIN_OPEN_AI_ENDPOINT: https://api.apisrouter.com
                          (no /v1 -- Chatwoot appends it)

then restart the Chatwoot processes

Captain làm gì với model đã cấu hình.

Chatwoot (khoảng 34K star trên GitHub) là nền tảng hỗ trợ khách hàng mã nguồn mở hàng đầu, và Captain là lớp AI của nó: một AI agent trả lời hội thoại khách hàng từ các bài viết trung tâm trợ giúp và FAQ của bạn, một copilot soạn câu trả lời và tóm tắt luồng cho agent con người, và các tính năng tri thức có căn cứ tài liệu đằng sau cả hai. Trên các bản cài tự host nơi Captain khả dụng, tất cả chạy qua model được cấu hình ở trên. Bên dưới, Chatwoot cấu hình SDK agent của nó một lần lúc khởi động: key, API base được suy ra, và model mặc định. Mọi tính năng Captain sau đó nói chat completions chuẩn tới base URL đó, và id model đi kèm dưới dạng một chuỗi trơn. Chatwoot có giữ một bảng ánh xạ tiền tố tên model (claude-, gemini-, deepseek-) nhưng dùng nó để gán nhãn telemetry, không phải định tuyến, nên một id Claude hoặc DeepSeek đặt làm CAPTAIN_OPEN_AI_MODEL vẫn đi tới endpoint đã cấu hình của bạn như bất kỳ chuỗi nào khác. Traffic hỗ trợ có hồ sơ chi phí đặc trưng: nhiều hội thoại, lượt ngắn, và câu trả lời có căn cứ được lắp ráp từ các bài viết đã truy xuất. Điều đó khiến chi phí theo từng hội thoại là con số quan trọng, và nó bị chi phối bởi token đầu vào từ context đã truy xuất. Một id nhanh xử lý tốt tầng trợ lý, với việc nâng cấp lên một id mạnh hơn chỉ là một thay đổi cấu hình khi bạn muốn copilot soạn bản nháp tốt hơn.

Cài đặt đầy đủ và chi tiết lúc khởi động.

Mở console Super Admin trên bản cài của bạn, vào App Configs và chọn Captain, rồi điền ba giá trị. Nếu Chatwoot của bạn có trước cấu hình endpoint (nó xuất hiện vào khoảng thời kỳ v4.4 giữa năm 2025), hãy nâng cấp trước; trên các bản cũ hơn chỉ có key và model tồn tại và endpoint bị hardcode. Vì bộ khởi tạo đọc các config này trong lúc app khởi động, thay đổi có hiệu lực sau khi khởi động lại các tiến trình web và worker. Điều đó cũng nghĩa là một giá trị sai không thất bại lúc lưu; nó thất bại ở request Captain đầu tiên sau khi khởi động lại, điều đáng biết trước khi bạn debug sai chỗ. Captain cũng có một phía embedding: CAPTAIN_EMBEDDING_MODEL (mặc định text-embedding-3-small) cấp năng lượng cho tìm kiếm tài liệu trên nội dung trung tâm trợ giúp của bạn, và nó giải quyết đối chiếu với cùng endpoint đã cấu hình. Nếu bạn trỏ lại endpoint vào một gateway, hãy xác nhận id embedding bạn cấu hình ở đó là một id endpoint thực sự phục vụ; nếu không, hãy để các tính năng tài liệu ở cấu hình hiện có và xác thực chúng riêng biệt sau khi chuyển đổi.

# Chatwoot will call <endpoint>/v1/chat/completions
curl -s https://api.apisrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $APISROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-haiku-4-5-20251001",
       "messages":[{"role":"user","content":"ping"}]}'

Chọn model cho tự động hóa hỗ trợ.

Vòng lặp đánh giá hiệu quả: chạy một tuần trên một id nhanh, xuất số liệu sử dụng, rồi chạy các đội nặng-copilot trên một id mạnh hơn và so sánh tỷ lệ chấp nhận bản nháp thay vì cảm tính. Cả hai ứng viên đều tính phí qua cùng key, nên so sánh đến kèm giá cả.

• Tầng AI agent là công việc khối lượng lớn: câu trả lời có căn cứ trên các bài viết đã truy xuất, hàng nghìn hội thoại mỗi tháng. claude-haiku-4-5-20251001, gpt-5.4-mini, và gemini-3.5-flash giữ chi phí mỗi hội thoại ổn định mà không mất kỷ luật căn cứ.
• Tầng copilot đọc toàn bộ luồng và soạn câu trả lời cho con người, nơi giọng điệu và phán đoán bộc lộ. claude-sonnet-4-6 là bước nâng cấp tự nhiên khi chất lượng bản nháp thúc đẩy năng suất agent.
• Bàn hỗ trợ đa ngôn ngữ nên thử deepseek-v4-pro và gemini-3.5-flash trên hỗn hợp ngôn ngữ thực của họ; chất lượng trả lời có căn cứ biến đổi qua các ngôn ngữ nhiều hơn benchmark tiếng Anh gợi ý.
• Chi phí theo từng hội thoại là đo được, không phải lý thuyết: token mỗi hội thoại nhân với hội thoại mỗi tháng, thẳng từ log sử dụng.
• Một model phục vụ mọi tính năng Captain theo từng bản cài, nên hãy chọn cho khối lượng công việc chi phối và xem lại sau khi đọc một tuần dữ liệu sử dụng thực.

Trả theo mức sử dụng · thấp hơn giá chính thức

Selected models are priced below official list prices. Exact input, output, cache, and per-request prices are shown for each model.

Các kiểu lỗi đặc thù của Chatwoot Captain.

Hậu tố /v1 kép là lỗi kinh điển. Vì Chatwoot nối thêm /v1 vào bất cứ gì bạn nhập, dán https://api.apisrouter.com/v1 tạo ra request nhắm vào /v1/v1/chat/completions, thứ trả về 404 tại gateway. Nhập host không kèm /v1. Thay đổi config có vẻ bị bỏ qua là quy tắc khởi động lại. SDK agent được cấu hình một lần lúc khởi động từ các config cài đặt; sửa chúng trong Super Admin mà không khởi động lại để giá trị cũ vẫn sống trong mọi tiến trình đang chạy. Hướng dẫn cũ trỏ vào sai bề mặt. Tutorial từ các phiên bản Chatwoot trước đó cấu hình OPENAI_API_KEY qua biến môi trường hoặc tích hợp OpenAI cũ; trên các phiên bản hiện tại, các config Captain trong Super Admin là bề mặt, và .env.example nói rõ điều đó. Model-not-found trên câu trả lời đầu tiên của Captain sau một lần đổi là một id gõ sai trong CAPTAIN_OPEN_AI_MODEL; danh sách /v1/models của gateway là cách viết có thẩm quyền. Lỗi xác thực nghĩa là key và endpoint config không thuộc về nhau. Và nếu tìm kiếm bài viết hoặc căn cứ tài liệu giảm sút trong khi chat trả lời bình thường, hãy xem config embedding, một model riêng biệt giải quyết đối chiếu với cùng endpoint.

Ai định tuyến Chatwoot Captain qua một gateway.

• Đội hỗ trợ tự host muốn chất lượng soạn thảo cỡ Claude trong copilot mà không cần một tài khoản vendor và quan hệ billing riêng.
• Bàn khối lượng cao nơi AI agent trả lời hầu hết hội thoại, và chi phí theo từng hội thoại quyết định tự động hóa có đáng hay không; các id catalog nhanh giữ con số đó trung thực.
• Đội chạy một Chatwoot cho mỗi thương hiệu hoặc khu vực, đo lường từng bản cài với key riêng để chi phí AI hỗ trợ tự báo cáo theo từng thương hiệu.
• Nhà vận hành so sánh model hỗ trợ trên traffic thực: mỗi ứng viên là một giá trị config và một lần khởi động lại, không phải một cuộc di dời.
• Lập trình viên không có quyền truy cập billing của một vendor cụ thể. Truy cập dựa trên nạp tiền không yêu cầu thẻ loại bỏ phụ thuộc đăng ký theo từng provider.

Xác minh endpoint và debug hội thoại đầu tiên.

Xác minh bên ngoài Chatwoot trước: liệt kê model bằng key của bạn và chạy một lần chat completion nhắm đúng id bạn đặt trong CAPTAIN_OPEN_AI_MODEL. Nếu chúng qua, nửa gateway đã được chứng minh và mọi thứ khác nằm ở phía Chatwoot. Sau đó khởi động lại và theo dõi tương tác Captain đầu tiên. Lỗi xác thực chỉ tới config key; model-not-found chỉ tới config model; lỗi dạng 404 chỉ tới một /v1 bị dán vào config endpoint. Nếu các tính năng Captain đơn giản là không xuất hiện, đó là khả dụng và cấp phép theo tầng bản cài của bạn, không phải cấu hình endpoint. Khi hội thoại chảy qua, console APIsRouter hiển thị model theo từng request, số lượng token, và chi tiêu. AI hỗ trợ là một dòng ngân sách cộng dồn hàng tháng, và một key cho mỗi bản cài biến log sử dụng thành báo cáo chi phí theo từng bàn hỗ trợ mà đội tài chính của bạn vẫn hỏi.

curl -s https://api.apisrouter.com/v1/models \
  -H "Authorization: Bearer $APISROUTER_API_KEY" | head -50

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