
전용 AI 중대 구축, WorkBuddy에서 B.AI 모델 연동 완전 도해 튜토리얼

빠르게 변화하는 개발 환경에서 WorkBuddy는 유연한 워크플로우 오케스트레이션과 강력한 시스템 레벨 통합 능력을 바탕으로 수많은 개발자의 데스크톱에서 없어서는 안 될 '생산성 허브'로 자리매김했습니다. 이는 파편화된 개발 도구들을 하나로 모으는 것을 넘어선 전담 지능형 미들웨어 역할을 하여, 개발자가 컨텍스트 전환 없이 몰입된 환경에서 최상위 AI 기능을 직접 활용할 수 있게 합니다. 이를 통해 일상 업무 수행 시 발생하는 마찰을 크게 줄이고 핵심 에너지가 고부가가치 사고와 창작 활동으로 완전히 돌아갈 수 있도록 돕습니다.
다양한 개발자들이 B.AI의 고성능 모델 매트릭스와 시스템 레이어 인프라를 일상 개발 워크플로우에 더 효율적으로 도입할 수 있도록 본 가이드에서는 WorkBuddy 데스크톱에 B.AI 커스텀 모델을 추가하는 방법을 상세히 안내합니다. 설정 전에 WorkBuddy 계정, B.AI API Key, 그리고 현재 계정에서 실제 사용 가능한 모델 ID를 준비해 주세요. 이어 간단한 설정 절차만 따라주시면 로컬 환경에서 최고 수준의 원활한 AI 협업 경험을 바로 활용하실 수 있습니다.
일. 시작하기 전
1단계: WorkBuddy 설치
WorkBuddy 공식 다운로드 페이지로 이동하여 시스템 환경에 맞는 설치 파일을 선택하세요.이미 WorkBuddy를 설치한 사용자는 이 단계를 건너뛰어도 됩니다. '모델' 또는 '모델 추가' 옵션이 보이지 않으면 먼저 '업데이트 확인'을 선택하여 버전을 최신화해 주세요.
Windows
공식 페이지에서는 현재 Windows x64(ARM64 호환) 설치 패키지를 제공하며, Windows 10 이상의 버전이 필요합니다. 설치 프로그램을 다운로드한 후 더블클릭하고 대화상자의 안내에 따라 설치를 완료한 뒤 WorkBuddy를 실행합니다.
주의: 시스템이 설치를 차단하면 먼저 패키지 출처가 공식 페이지인지 확인한 후 팝업 창에서 애플리케이션 이름과 발행자 정보를 검토하세요. Windows 보안 설정을 비활성화하거나 무시하지 마십시오.
macOS
공식 페이지에서는 현재 Apple 실리콘용과 Intel용 .dmg 파일을 각각 제공하고 있으며, macOS 12.0 이상이 필요합니다.
- M1, M2, M3, M4 등 Apple 실리콘 탑재 기기에는 Apple 실리콘용을 선택하세요.
- Intel 프로세서 기기는 Intel용을 선택하세요.
.dmg 파일을 연 후 WorkBuddy를 '응용 프로그램(Applications)' 폴더로 드래그 앤 드롭하고, 응용 프로그램 폴더에서 실행합니다. 칩setType이 궁금할 경우 '이 Mac에 대해'의 '칩' 또는 '프로세서' 항목을 확인하세요.
기타 시스템 안내
현재 WorkBuddy 데스크톱은 Windows 및 macOS만 지원하며, Linux는 아직 지원하지 않습니다. 또한 모바일 및 HarmonyOS 환경의 기능 범위가 상이하므로 본 가이드의 모든 조작은 데스크톱 기준으로 진행됩니다.
2단계: WorkBuddy 로그인
최초 실행 시 '로그인'을 클릭하고 클라이언트에 표시된 방식에 따라 인증을 완료하세요. 글로벌 버전 공식 문서에는 Google 및 GitHub OAuth가 명시되어 있습니다. 현재 클라이언트에서 위챗 QR코드 스캔이나 기타 경로가 표시될 경우 실제 클라이언트의 옵션을 우선으로 하세요.
3단계: B.AI API Key 발급
B.AI에 먼저 로그인한 후 좌측 내비게이션 바에서 API 관리 또는 API Key 관리 페이지로 이동합니다. 'API Key 생성'을 클릭한 후 식별하기 쉬운 이름(예: WorkBuddy)을 지정하세요. B.AI의 공식 제한 사항으로 인해 완성된 Key는 생성 성공 시 한 번만 노출되므로, 반드시 생성 직후 복사하여 안전하게 보관해야 합니다.

설정 전 필수 확인 사항:
- 사전 점검: 설정 전에 계정 잔액이 충분한지, 그리고 해당 API Key가 목표 모델 호출 권한을 가지고 있는지 반드시 확인하세요.
- 모델 ID 획득: 모델 ID는 B.AI의 GET /v1/models 응답 결과 또는 현재 콘솔 목록을 기준 삼아야 하며, 다른 튜토리얼의 예제 이름만으로 추측하면 안 됩니다.
- 프로토콜 호환성: WorkBuddy 커스텀 모델은 OpenAI Chat Completions 프로토콜을 사용하므로, 목표 모델도 해당 엔드포인트를 오픈해야 합니다. Anthropic Messages 전용 또는 OpenAI Responses 전용 설정은 직접 입력할 수 없습니다.
주의: 문서, 스크린샷, 채팅 기록 또는 공개 저장소에서 완성된 Key를 누설하지 마십시오. Key 유출이 의심되면 즉시 기존 Key를 삭제하고 새 Key를 생성한 뒤 WorkBuddy 설정을 업데이트하세요.
이. 인터페이스를 통한 B.AI API 설정
1단계: 커스텀 모델 설정 열기
WorkBuddy를 실행하고 좌측 하단 프로필 아바타를 클릭하여 '설정'을 선택하세요.

좌측 메뉴에서 '모델'을 선택한 후 '모델 추가'를 클릭합니다.

현재 목록에 이미 다른 커스텀 모델이 있다면 '모델 추가'를 클릭해 새로운 설정을 추가해야 하며, 무작정 기존 매개변수를 덮어쓰지 않도록 주의하세요. 기존 B.AI 모델을 수정하려면 해당 모델 옆의 연필 아이콘만 클릭하면 됩니다. 수정하면서도 이전 버전을 유지하려면 완전히 새로운 모델로서 설정을 새로 추가해야 합니다.
2단계: 연결 파라미터 입력
'공급자(Provider)' 드롭다운에서 '사용자 정의(Custom)'를 선택하고 팝업 창에 관련 정보를 입력합니다.

입력 요령은 다음과 같습니다:

URL과 '사용자 정의 프로토콜'은 반드시 쌍으로 설정해야 합니다:

WorkBuddy 공식 문서에 따르면, '사용자 정의 프로토콜'이 꺼져 있을 때는 클라이언트가 표준 OpenAI Chat Completions 규칙에 따라 입력한 URL 끝에 자동으로 /chat/completions 경로를 붙입니다. 반면 해당 스위치가 켜져 있으면 클라이언트는 작성한 전체 URL로 직접 요청을 보내며 경로 추가 작업을 생략합니다. 두 방식을 혼용하지 마십시오. /v1/chat/completions/chat/completions처럼 중복 결합하면 일반적으로 404 에러가 반환됩니다.
3단계: 모델 능력 설정
'고급 설정'의 스위치는 모델 능력을 선언하는 용도로만 사용되며, 체크해도 기본적으로 지원하지 않는 모델에 능력이 자동 부여되지 않습니다. 실제 상황에 맞춰 아래 원칙을 참고하여 설정하세요.

입력·출력 상한선을 정확히 알 수 없다면 '제공업체 기본값 사용'을 그대로 유지하세요. 공식 문서나 실제 테스트 없이 모든 기능을 무조건 활성화하지 마십시오.
4단계: 설정 저장
URL, API Key, 모델 ID를 모두 확인한 후 '저장'을 클릭합니다. 신규 모델이 '저장된 모델' 목록에 나타나야 합니다.

리스트에 표시되지 않으면 저장 팝업이 여전히 열려 있는지, 필드 오류가 있는지, 모델 셀렉터가 새로고침되었는지, 클라이언트 버전은 어떠한지 순차적으로 확인하세요. 필요시 WorkBuddy를 완전히 종료한 뒤 재실행합니다. 리스트에 모델이 나타났다고 해서 B.AI 호출이 성공한 것은 아니며, 설정이 단지 저장되었음을 의미할 뿐이므로 이후 검증 단계를 반드시 거쳐야 합니다.
삼. 모델 선택 및 설정 검증
1단계: B.AI 커스텀 모델 선택
'새 작업 만들기' 화면으로 돌아가 입력창 근처의 모델 셀렉터를 열고 커스텀 모델 그룹에서 방금 추가한 모델을 선택하세요. 테스트 기간 중 'Auto' 모드는 선택하지 마십시오. Auto 모드는 다른 모델을 할당할 수 있으므로 본 요청이 B.AI를 사용했는지 입증할 수 없습니다.

2단계: 일반 대화 검증
도구 의존성이 없는 간단한 질문을 하나 보내보세요:
반드시 다음 문장만 Reply하세요: B.AI 일반 대화 테스트 성공
정상적인 응답을 받으면 WorkBuddy가 설정을 정상적으로 읽고 있고, Key, URL, 모델 ID 중 적어도 하나는 텍스트 호출을 완료할 수 있음을 의미합니다.
실패할 경우 '현재 모델 → API Key → URL 및 프로토콜 스위치 → 모델 ID → 잔여량 및 권한' 순서로 점검하세요. 모델에게 '너는 누구인가'라고 물어 라우팅 성공 여부를 판단하지 마십시오. 모델이 스스로를 소개하는 것은 진입 증명 자료로 사용할 수 없습니다.
3단계: 도구 호출 검증
먼저 테스트용으로만 사용하는 폴더를 생성하고 프라이버시 정보가 포함되지 않은 텍스트 파일 1~2개를 넣은 뒤, WorkBuddy에서 해당 폴더를 workspace로 선택하고 읽기 작업에만 필요한 권한만 부여한 후 다음 명령어를 전송하세요:
현재 작업 공간의 텍스트 파일을 읽어오고, 파일 이름을 나열한 후 각 파일 내용을 한 문장으로 요약하세요. 어떤 파일도 수정, 이동, 삭제하지 마십시오.
WorkBuddy가 파일 읽기 도구 호출을 표시하고 파일 요약을 정확히 반환할 때初めて 도구 호출 체인에 문제가 없음을 보장합니다. 채팅은 되지만 파일 읽기가 안 되면 도구 호출 설정, 모델의 도구 호출 능력, B.AI 엔드포인트 지원 여부, workspace 권한을 점검하세요.
4단계: B.AI 호출 기록 대조
B.AI 콘솔에서 사용량 또는 호출 기록을 제공하는 경우 최근 요청 시간, 모델 ID, 요청 횟수, 토큰 소비량을 확인하여 방금 진행한 테스트 데이터와 일치하는지 반드시 검증하세요.
전체 연결 과정이 완벽하게 작동하는지 확보하려면 다음 세 단계의 성공 상태를 하나씩 점검해 주십시오:

사. 자주 묻는 질문
1. 커스텀 모델 진입점을 찾을 수 없다면?
아직 로그인하지 않았거나, 클라이언트 버전이 낮거나, 데스크톱 전용 모델 설정이 아닌 곳을 열고 있을 수 있습니다. 먼저 로그인한 뒤 '설정' → '모델'로 이동하세요. 여전히 진입점이 보이지 않으면 '업데이트 확인'을 통해 클라이언트를 최신화한 후 재시작합니다. 문제가 지속될 경우 '도움말 및 피드백'을 통해 버전 번호와 스크린샷을 제출하세요.
2. Windows 또는 macOS에서 설치하거나 실행하지 못한다면?
먼저 시스템 버전이 요구 사항을 충족하는지, 설치 파일이 공식 페이지에서 내려받았는지, 다운받은 아키텍처가 맞는지 확인하세요. 시스템 제공 보안 설정 절차에 따라 차단을 처리하시고, 보안 기능을 끄거나 신뢰할 수 없는 이미지 저장소를 사용하지 마십시오.
3. 저장했는데 모델이 표시되지 않나요?
먼저 '저장된 모델' 목록에 해당 항목이 있는지 확인하시고, 설정을 닫은 후 모델 셀렉터를 다시 여세요. 여전히 표시되지 않으면 WorkBuddy를 완전히 종료하고 재실행하신 뒤 클라이언트 업데이트 여부를 점검하세요.
4. 401, 403, 404, 429 오류가 발생한다면 원인 및 해결 방법은?

매번 하나의 요소만 변경 후 일반 대화로 재검증하면 원인 파악에 유리합니다.
5. "model not found" 메시지가 나온다면 어떻게 하나요?
GET /v1/models 엔드포인트를 다시 호출하거나 현재 콘솔 목록을 확인하여 정확한 id를 복제하세요. 표시 이름, 별칭, 혹은 타 튜토리얼의 버전 정보는 입력하지 마십시오. 해당 모델이 Chat Completions 엔드포인트를 오픈하고 있는지도 함께 확인하셔야 합니다.
6. 계속 로딩되거나 타임아웃, 연결 실패 시 조치 방법은?
먼저 네트워크에서 https://api.b.ai 접근이 가능한지 확인하고 짧은 질문으로 테스트해 보세요. 그다음 URL, 프록시 또는 기업 네트워크 정책, B.AI 서비스 상태, 입력 파일 크기 과다 여부를 점검하세요. 문제가 지속된다면 발생 시간, WorkBuddy 버전, 전체 오류 메시지 및 요청 ID를 기록한 후 공식 지원팀에 문의하시기 바랍니다.
7. 채팅은 되는데 파일 읽기가 되지 않는다면?
'모델 능력 → Tool Calling 스위치 → 작업 공간 → 파일 권한' 순서대로 점검하세요. 일단 일반 텍스트 파일로 테스트하시고, 시스템 디렉토리, 보호 대상 디렉토리 또는 민감 파일을 직접 선택하지 마십시오.
8. 시스템이 여전히 기본 내장 모델을 호출하는 이유는 무엇인가요?
모델 셀렉터를 확인하여 'Auto' 상태가 아니며, 구성한 B.AI 커스텀 모델이 명확히 선택되었는지 확인하세요. 짧은 질문을 하나 전송한 후 B.AI 콘솔에서 호출 시간과 사용량 데이터를 대조해 보시기 바랍니다. 여전히 의문이 든다면 새 대화 작업을 만들어 재테스트하기를 권장합니다.
9. 앱을 종료한 뒤 다음번에는 어떻게 실행하나요?
Windows는 시작 메뉴 또는 바탕화면 바로가기로 실행할 수 있으며, macOS는 응용 프로그램 폴더 또는 Launchpad에서 실행할 수 있습니다. 재실행 후에도 커스텀 모델이 보이지 않으면 현재 계정이 로그인 상태인지 먼저 확인한 뒤 '설정' → '모델'로 이동해 저장된 모델 목록을 점검하세요.
10. 컴퓨터를 바꾸면 재설계가 필요한가요?
재구성하기를 권장합니다. WorkBuddy 인터페이스에서 커스텀 모델은 로컬 .workbuddy/models.json 파일에 기록된다고 안내하고 있으며, 동일 계정으로 로그인했더라도 API Key와 모델 설정이 자동으로 동기화된다고 가정하면 안 됩니다. 새 컴퓨터에서는 모델을 다시 추가하고 두 가지 검증 절차를 모두 통과시키셔야 하며, 키를 채팅, 공개 클라우드 저장소, 또는 암호화되지 않은 문서로 전송하지 마십시오.
참고 자료:
- WorkBuddy 공식 다운로드 페이지
- WorkBuddy 공식 모델 설정 문서
- WorkBuddy Windows 설치 가이드
- WorkBuddy macOS 설치 가이드
- B.AI API 레퍼런스
- B.AI API Key 발급 가이드















