Chatwoot Captain을 커스텀 OpenAI 호환 엔드포인트에서 실행하기.

빠른 답: Super Admin의 Captain 설정 세 개.

현재 셀프 호스팅 Chatwoot에서 Captain의 LLM 설정은 .env 변수가 아니라 설치 설정입니다; 제공되는 .env.example이 명시적으로 그렇게 말하며 Super Admin, App Configs, Captain으로 안내합니다. 중요한 값은 세 가지입니다: CAPTAIN_OPEN_AI_API_KEY가 게이트웨이 키를, CAPTAIN_OPEN_AI_MODEL이 모델 id를, CAPTAIN_OPEN_AI_ENDPOINT가 엔드포인트 호스트를 받습니다. 엔드포인트 값에는 한 가지 까다로운 점이 있습니다: /v1 접미사 없이 넘겨야 합니다. Chatwoot의 초기화 코드는 끝의 슬래시를 제거하고 /v1을 붙여 API base를 직접 만들며, 설정 자체의 설명도 기본값을 정확히 그 형태인 https://api.openai.com/으로 보여줍니다. APIsRouter의 경우 https://api.apisrouter.com을 입력하면 Chatwoot가 https://api.apisrouter.com/v1을 도출합니다. 이 설정들은 앱이 부팅될 때 읽히므로, 바꾼 뒤에는 Chatwoot를 재시작하세요.

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이 설정된 모델로 하는 일.

Chatwoot(GitHub에서 약 3.4만 스타)는 선두적인 오픈소스 고객지원 플랫폼이며, Captain은 그 AI 레이어입니다: 여러분의 헬프센터 문서와 FAQ로부터 고객 대화에 답하는 AI 에이전트, 사람 상담원을 위해 답변 초안을 쓰고 스레드를 요약하는 코파일럿, 그리고 둘 뒤의 문서 기반 지식 기능. Captain을 사용할 수 있는 셀프 호스팅 설치에서는 이 모든 것이 위에서 설정한 모델을 통해 실행됩니다. 내부적으로, Chatwoot는 부팅 시 agents SDK를 한 번 설정합니다: 키, 도출된 API base, 기본 모델. 그러면 모든 Captain 기능이 그 base URL에 표준 chat completions로 말하며, 모델 id는 그냥 문자열로 이동합니다. Chatwoot는 모델 이름 접두어(claude-, gemini-, deepseek-)의 맵을 유지하지만, 라우팅이 아니라 텔레메트리 라벨링에만 씁니다. 따라서 CAPTAIN_OPEN_AI_MODEL로 설정된 Claude나 DeepSeek id도 다른 어떤 문자열과 마찬가지로 여러분이 설정한 엔드포인트로 갑니다. 고객지원 트래픽은 독특한 비용 프로필을 가집니다: 많은 대화, 짧은 턴, 검색된 문서로 조립된 근거 있는 답변. 그래서 대화당 비용이 중요한 숫자이며, 검색된 컨텍스트에서 나오는 입력 토큰이 그것을 지배합니다. 빠른 id가 어시스턴트 티어를 잘 처리하며, 코파일럿이 더 나은 초안을 쓰게 하고 싶을 때는 설정 하나만 바꾸면 더 강한 id로 승격할 수 있습니다.

전체 설정과 부팅 시점의 세부 사항.

여러분의 설치에서 Super Admin 콘솔을 열고, App Configs로 가서 Captain을 선택한 다음, 세 값을 채우세요. 여러분의 Chatwoot가 엔드포인트 설정(2025년 중반 v4.4 무렵 도입)보다 오래된 버전이라면 먼저 업그레이드하세요; 이전 버전에는 키와 모델만 있었고 엔드포인트는 하드코딩되어 있었습니다. 초기화 코드가 애플리케이션 부팅 중에 이 설정들을 읽으므로, 변경 사항은 웹과 워커 프로세스를 재시작한 뒤에 적용됩니다. 이는 또한 잘못된 값이 저장 시점에 실패하지 않는다는 뜻입니다; 재시작 후 첫 Captain 요청에서 실패하므로, 엉뚱한 곳에서 디버깅하기 전에 알아두면 좋습니다. Captain에는 임베딩 쪽도 있습니다: CAPTAIN_EMBEDDING_MODEL(기본값 text-embedding-3-small)이 여러분의 헬프센터 콘텐츠에 대한 문서 검색을 구동하며, 같은 설정된 엔드포인트에 대해 해석됩니다. 엔드포인트를 게이트웨이로 다시 지정한다면, 거기서 설정하는 임베딩 id를 엔드포인트가 실제로 서빙하는지 확인하세요; 그렇지 않다면 문서 기능은 기존 설정에 남겨두고 전환 후 별도로 검증하세요.

# 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"}]}'

고객지원 자동화를 위한 모델 선택.

작동하는 평가 루프: 빠른 id로 일주일 실행하고 사용량 수치를 내보낸 다음, 코파일럿 사용이 많은 팀은 더 강한 id로 실행해 감으로 초안 채택률을 비교하세요, 느낌이 아니라. 두 후보 모두 같은 키로 청구되므로, 비교는 이미 가격이 매겨진 채로 도착합니다.

• AI 에이전트 티어는 물량 작업입니다: 검색된 문서에 근거한 답변, 월 수천 건의 대화. claude-haiku-4-5-20251001, gpt-5.4-mini, gemini-3.5-flash는 근거 있는 답변의 규율을 잃지 않으면서 대화당 비용을 평평하게 유지합니다.
• 코파일럿 티어는 스레드 전체를 읽고 사람을 위한 답변 초안을 쓰는데, 여기서 어조와 판단력이 드러납니다. 초안 품질이 상담원 생산성을 좌우할 때는 claude-sonnet-4-6이 자연스러운 다음 단계입니다.
• 다국어 고객지원 데스크는 실제 언어 조합으로 deepseek-v4-pro와 gemini-3.5-flash를 테스트해야 합니다; 근거 있는 답변 품질은 영어 벤치마크가 시사하는 것보다 언어마다 더 크게 갈립니다.
• 대화당 비용은 이론이 아니라 측정 가능합니다: 대화당 토큰 곱하기 월간 대화 수, 사용량 로그에서 바로.
• 설치당 하나의 모델이 모든 Captain 기능을 서빙하므로, 지배적인 워크로드에 맞춰 고르고 일주일치 실제 사용량을 읽은 뒤 다시 검토하세요.

사용한 만큼 지불 · 공식 요금보다 저렴

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

Chatwoot Captain에 특유한 실패 패턴.

/v1 이중 접미사가 고전적인 사례입니다. Chatwoot가 여러분이 입력한 것에 /v1을 붙이므로, https://api.apisrouter.com/v1을 붙여넣으면 게이트웨이에서 404가 나는 /v1/v1/chat/completions에 대한 요청이 만들어집니다. /v1 없이 호스트만 입력하세요. 무시된 것처럼 보이는 설정 변경은 재시작 규칙 때문입니다. agents SDK는 설치 설정으로부터 부팅 시 한 번만 구성됩니다; Super Admin에서 편집만 하고 재시작하지 않으면 실행 중인 모든 프로세스에 예전 값이 그대로 남습니다. 오래된 가이드는 잘못된 표면을 가리킵니다. 이전 Chatwoot 버전의 튜토리얼은 환경 변수나 레거시 OpenAI 통합을 통해 OPENAI_API_KEY를 설정합니다; 현재 버전에서는 Super Admin의 Captain 설정이 그 표면이며, .env.example도 그렇게 말합니다. 전환 후 Captain의 첫 답변에서 나오는 model-not-found는 CAPTAIN_OPEN_AI_MODEL의 id 오타입니다; 게이트웨이의 /v1/models 목록이 권위 있는 철자입니다. 인증 오류는 키와 엔드포인트 설정이 짝이 맞지 않는다는 뜻입니다. 그리고 채팅 답변은 정상인데 문서 검색이나 검색 기반 답변이 나빠졌다면, 같은 엔드포인트에 대해 해석되는 별도의 모델인 임베딩 설정을 살펴보세요.

어떤 사람들이 게이트웨이를 통해 Chatwoot Captain을 쓰는가.

• 별도의 벤더 계정과 결제 관계 없이 코파일럿에서 Claude 수준의 초안 작성을 원하는 셀프 호스팅 고객지원 팀.
• AI 에이전트가 대부분의 대화에 답하는 고물량 데스크 — 대화당 비용이 자동화가 수지에 맞는지를 결정하며, 빠른 카탈로그 id가 그 숫자를 정직하게 유지합니다.
• 브랜드나 지역별로 Chatwoot 하나씩 운영하며, 각 설치를 자체 키로 계측해 고객지원 AI 비용이 브랜드별로 스스로 보고되게 하는 팀.
• 실제 트래픽으로 고객지원 모델을 비교하는 운영자: 각 후보는 마이그레이션이 아니라 설정 값 하나와 재시작 한 번입니다.
• 특정 벤더의 결제 수단에 접근할 수 없는 개발자. 카드 없이 충전만으로 사용할 수 있어 프로바이더별 가입 의존성이 사라집니다.

엔드포인트 검증 및 첫 대화 디버깅.

먼저 Chatwoot 바깥에서 검증하세요: 여러분의 키로 모델을 나열하고, CAPTAIN_OPEN_AI_MODEL에 설정한 정확한 id로 채팅 완성 하나를 실행해 보세요. 이것들이 통과하면 게이트웨이 쪽은 증명된 것이고 나머지는 모두 Chatwoot 쪽입니다. 그런 다음 재시작하고 첫 Captain 상호작용을 지켜보세요. 인증 실패는 키 설정을, model-not-found는 모델 설정을, 404 형태의 오류는 엔드포인트 설정에 붙여넣은 /v1을 가리킵니다. Captain 기능이 아예 나타나지 않는다면, 그것은 엔드포인트 설정이 아니라 여러분 설치 티어의 가용성과 라이선스 문제입니다. 대화가 흐르기 시작하면 APIsRouter 콘솔에서 요청별 모델, 토큰 수, 지출을 볼 수 있습니다. 고객지원 AI는 매달 누적되는 예산 항목이며, 설치당 키 하나가 사용량 로그를 재무팀이 계속 요구하는 데스크별 비용 보고서로 바꿔줍니다.

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

자주 묻는 질문