작성자 주: OpenBot에는 ‘모델 선택’ 화면이 없어요. 모델은 .env와 테넌트 패키지의 model.yaml에 설정합니다. 이 글에서는 환경 변수 세 줄과 YAML 한 줄을 수정해 APIYI에 연결하고, 컴퓨터 도구 3개만 먼저 허용한 뒤 ‘웹페이지 열기 + 파일 읽기 + 감사 로그 확인’으로 동작을 검증하는 방법을 설명해요.
CopilotKit의 OpenBot을 클론하고 .env.example을 열어봤어요. 프런트엔드 화면도 이리저리 살펴봤지만 ‘모델 제공업체 선택’ 드롭다운은 끝내 찾지 못했죠. OpenAI 공식 결제 카드는 없고 APIYI의 종량제 요금으로 claude-opus-5-5를 사용하고 싶은데, 모델을 어디에 설정해야 하는지조차 모르겠다면요?
결론부터 말하면 OpenBot에는 ‘모델 선택’ 스위치가 없어요. 모델은 .env와 테넌트 패키지의 model.yaml에 설정합니다. APIYI 연결을 위해 코드를 수정할 필요는 없어요. 환경 변수 세 줄과 YAML 한 줄만 바꾸면 됩니다. 수정한 뒤에는 컴퓨터 도구 3개만 먼저 허용하고, 검증을 마친 후 필요에 따라 추가로 허용하세요.
이 글은 ‘원클릭 실행’ 가이드가 아니에요. OpenBot은 템플릿이기 때문에 실행하려면 Docker, Bun 1.4+, CopilotKit Intelligence 프로젝트, 모델 키가 필요해요. 이 글에서 사전 준비 사항도 자세히 설명합니다. 또한 GitHub에는 OpenBot이라는 이름의 프로젝트가 두 개 있는데, 이 글에서는 CopilotKit의 OpenBot을 다뤄요.
이 글에서 얻을 수 있는 것: 세 곳의 설정을 직접 수정하고, 도구 3개로 시작해 ‘웹페이지 열기 + 파일 읽기 + 감사 로그 확인’으로 동작을 검증할 수 있어요. 400, 401, 모델을 찾을 수 없음, 도구가 호출되지 않음, 시작 거부 등 자주 발생하는 문제를 확인할 수 있는 표도 준비했어요.
OpenBot의 모델은 화면에서 설정하지 않아요
OpenBot은 제품이 아니라 템플릿이에요
CopilotKit/OpenBot은 MIT 라이선스의 오픈소스 저장소로, 2026년 8월 17일에 만들어졌어요. 2026년 11월 2일 기준으로 저장소의 스타는 9,561개이고, 최신 정식 릴리스는 v0.2.0(2026년 10월 12일)이에요. README 상단에는 여전히 Beta로 표시되어 있어요. OpenBot은 각 AI 동료(저장소에서는 Bot이라고 불러요)에게 실제 브라우저, 독립적인 로그인 상태와 파일, 그리고 부여받은 도구를 갖춘 컴퓨터를 제공하는 것을 목표로 해요.
README에도 명확하게 적혀 있어요. 이것은 “제품이 아니라 템플릿(A template, not a product)”이에요. 가입해서 쓸 수 있는 호스팅 버전도 없고, 의존성 패키지로 배포되지도 않아요. 저장소를 클론하고 examples/ 아래의 예제 테넌트 패키지를 원하는 동료, 채널, 스킬로 바꾼 뒤 직접 실행해야 해요. 그러니 “모델은 어디서 선택하나요?”라는 질문의 답은 화면이 아닌 설정 파일에 있어요.
OpenBot을 실행하기 위한 네 가지 준비 사항
아래 표는 모델을 연결하기 전에 갖춰야 할 것들이에요. 하나라도 빠지면 이후 설정을 검증할 수 없어요.
| 준비 사항 | 구체적인 요구 사항 | 설명 |
|---|---|---|
| Docker | PostgreSQL(pgvector 포함)과 내장 Bot 실행 | scripts/start.sh가 Docker 서비스를 실행하고 마이그레이션을 수행해요 |
| Bun | 1.4 이상 | bun install로 의존성을 설치해요 |
| CopilotKit Intelligence | 프로젝트와 라이선스가 필요하며, 무료 플랜도 있어요 | 로컬 평가 환경은 macOS + Docker Desktop이에요. 로컬 라이선스는 30일간 유효하며 npx copilotkit@latest local renew로 갱신할 수 있어요 |
| 모델 키 | OpenAI 호환 엔드포인트의 키 하나 | 이 글에서는 APIYI 토큰을 사용하며, base_url은 https://api.apiyi.com/v1이에요 |
Intelligence의 중요성을 놓치기 쉬워요. .env.example의 주석에 따르면 Intelligence URL, gateway URL 또는 키가 없으면 서버가 아예 시작을 거부해요. 원문에는 “There is no degraded mode.”라고 적혀 있어요. 지속 스레드와 메모리를 Intelligence가 관리하기 때문이에요. Intelligence가 없으면 대화할 때마다 컨텍스트가 사라져요. 따라서 OpenBot을 “완전한 오프라인” 솔루션이라고 설명할 수는 없어요.
OPENAI_BASE_URL은 전체 배포에 적용돼요
README에는 “no model ships in the box”라고 적혀 있어요. 모델은 패키지에 포함되어 배포되지 않으며, 관리자가 제공한 인증 정보는 암호화되어 데이터베이스에 저장되고 로그에는 남지 않아요. 모델을 결정하는 것은 배포 단위의 환경 변수예요. 이 중 가장 중요한 OPENAI_BASE_URL은 동일한 API를 사용하는 엔드포인트라면 무엇이든 지정할 수 있어요. 여러 공급자를 지원하는 게이트웨이, 프록시 또는 자체 하드웨어에서 실행하는 모델도 가능해요. .env.example의 주석은 /v1/chat/completions를 지원하는 엔드포인트라면 모두 사용할 수 있다고 더 구체적으로 설명해요.
이 변수는 개별 Bot이 아니라 전체 배포에 적용돼요. API 서버가 내장 에이전트에 사용하는 클라이언트, 자체 클라이언트를 생성하는 agent-bot, BOT_PROVIDER=openai인 agent-langgraph까지 세 곳 모두 이 변수를 읽어요. 공식 문서에 따르면 이렇게 하면 같은 배포에서 요청의 절반은 새 주소로, 나머지는 이전 주소로 향하는 상황을 막을 수 있어요.
세 곳을 수정해 APIYI 연결하기: OpenBot 환경 변수 설정
OpenBot과 APIYI의 연결 지점
APIYI는 OpenAI 호환 인터페이스를 제공해요. base_url에 https://api.apiyi.com/v1을 입력하면 요청이 /v1/chat/completions로 전달되므로 OpenBot의 OPENAI_BASE_URL 요구사항에 맞아요. 한 가지 더 주의할 점은 OpenBot이 모델명을 입력한 그대로 전달한다는 거예요. APIYI의 /v1/models는 접두사 없는 모델명 claude-opus-5-5를 반환하므로, 공식 게이트웨이 예제를 따라 openai/ 접두사를 붙이지 마세요. 공식 예제의 openai/gpt-5.6-terra는 모델명에 네임스페이스를 붙이는 엔드포인트에서만 사용할 수 있어요.
먼저 전체 설정을 살펴본 뒤 단계별로 진행해 볼게요.
| 수정할 곳 | 설정값 | 이유 |
|---|---|---|
.env의 OPENAI_API_KEY |
APIYI 콘솔에서 만든 sk-... 토큰 |
내장 에이전트와 기본 제공 Bot 두 개가 모두 이 키를 기본으로 사용해요 |
.env의 OPENAI_BASE_URL |
https://api.apiyi.com/v1 |
배포 환경의 모든 모델 요청을 APIYI 호환 엔드포인트로 보내요 |
.env의 BOT_MODEL |
claude-opus-5-5 |
실행할 Bot의 모델을 지정해요. 비워두면 provider spec 파일의 설정값을 사용해요 |
examples/<你的包>/model.yaml의 default_model |
claude-opus-5-5 |
예제 패키지는 현재 gpt-5.6-terra로 설정되어 있어 변경하지 않으면 모델을 찾을 수 없어요 |
.env의 BOT_RESPONSES_API |
false 유지 |
Claude는 APIYI의 Responses 엔드포인트에서 400 오류를 반환해요 |
첫 번째 단계: 전용 토큰 준비하기
- APIYI 토큰 페이지
api.apiyi.com/token에서 새 키를 만들어요. 잔액 한도와 유효기간을 설정하고, 용도에는 “OpenBot 로컬 평가”라고 적어요. - 로컬에서 curl로
GET https://api.apiyi.com/v1/models요청을 보내요. 요청 헤더는Authorization: Bearer sk-...로 설정해요.
확인 기준: HTTP 200이 반환되고 목록에서 claude-opus-5-5를 찾을 수 있어야 해요. 2026-11-02에 직접 테스트했을 때는 모델 259개가 반환됐고, claude-opus-5-5와 claude-opus-5-5-thinking이 모두 포함되어 있었어요.
토큰을 따로 만드는 이유는 “이 기기 전용”과 “프로덕션용”을 분리하기 위해서예요. 템플릿을 설정하는 단계에서 Bot이 여러 번 시행착오를 겪더라도 잔액 한도가 있어 안심할 수 있어요.
두 번째 단계: .env에서 세 줄 수정하기
공식 빠른 시작 가이드에 따라 먼저 cp .env.example .env와 bun install을 실행해요. 이어서 npx --yes copilotkit@latest login, npx --yes copilotkit@latest project select, bun scripts/setup-learning.ts를 차례로 실행해 runtime 키와 Learning 컨테이너를 .env에 기록해요. 그런 다음 아래 세 줄을 수정해요.
OPENAI_API_KEY=sk-발급받은APIYI토큰OPENAI_BASE_URL=https://api.apiyi.com/v1BOT_MODEL=claude-opus-5-5
다음 네 가지도 확인하세요. BOT_PROVIDER는 기본값인 openai를 유지하고, BOT_RESPONSES_API는 false로 유지해요. KEY_ENCRYPTION_KEY는 openssl rand -base64 32로 생성해요. AGENT_BOT_MODEL은 개념 증명용 agent-bot에서만 사용하며, 기본값은 gpt-5.5예요. BOT_MODEL과는 서로 영향을 주지 않아요. agent-bot도 실행한다면 /v1/models에서 이 모델 이름이 있는지 확인하거나, 사용하려는 모델로 변경하세요.
확인 기준: grep OPENAI_ .env를 실행했을 때 올바른 키와 주소가 출력되어야 해요. 주소 끝에는 /v1이 있어야 하고, 불필요한 슬래시나 공백은 없어야 해요. 컨테이너에서 같은 엔드포인트에 접근할 때 다른 경로를 사용해야 한다면 OPENAI_CONTAINER_BASE_URL로 주소를 덮어쓸 수 있어요. 다만 APIYI는 공개 주소이므로 보통 이 변수가 필요하지 않아요.
세 번째 단계: 테넌트 패키지의 model.yaml 한 줄 수정하기
examples/fintech/model.yaml 또는 복사해 둔 테넌트 패키지의 파일을 열어보세요. 현재 설정은 model.provider: openai, model.credential_secret_ref: openai-api-key, model.default_model: gpt-5.6-terra입니다.
default_model을claude-opus-5-5로 바꿔요.provider는openai로 유지해요. 공식적으로 이 항목에는openai또는anthropic만 사용할 수 있어요. APIYI의 OpenAI 호환 엔드포인트를 이용할 때는openai를 선택하세요.credential_secret_ref를 평문 키로 바꾸지 마세요. 이 항목은 저장된 자격 증명을 참조해요.
확인 기준: bash scripts/start.sh를 실행한 후 상태 검사를 모두 통과하고, http://localhost:3010을 열었을 때 기본 동료인 General Assistant와 Knowledge가 보이면 돼요.
미리 알아둘 주의사항이 있어요. 서버가 시작될 때는 원래 OpenAI 또는 Anthropic에 해당 키로 default_model을 호출할 수 있는지 확인해요. 호출할 수 없다면 model-unavailable 또는 model-credential-rejected를 출력하죠. 하지만 OPENAI_BASE_URL이 설정되어 있으면 이 검사를 건너뛰어요. 따라서 APIYI를 사용할 때 모델 이름을 잘못 입력해도 시작 단계에서는 오류가 나지 않고, 첫 메시지를 보낸 뒤에야 문제가 드러나요. 시작에 성공했다는 것은 서비스가 실행됐다는 뜻일 뿐, 모델 설정이 올바르다는 뜻은 아니에요.
버전 안내: v0.2.0과 main 브랜치의 차이
이 차이는 꼭 짚고 넘어가야 해요. main 브랜치의 CHANGELOG에서 Unreleased 항목을 보면, 내장 Bot의 openai/... 모델이 “OpenAI도 Azure도 아닌” OPENAI_BASE_URL을 사용할 때 Responses API 대신 해당 엔드포인트의 /chat/completions를 호출하도록 변경됐어요. 공식적으로 밝힌 이유는 대부분의 OpenAI 호환 엔드포인트가 Chat Completions만 제공하기 때문이에요. 같은 변경에서 둘 중 하나를 강제로 선택할 수 있는 COPILOTKIT_OPENAI_API=responses|chat 설정도 추가됐어요.
이 변경은 아직 정식 태그인 v0.2.0에 포함되지 않았어요. v0.2.0을 체크아웃했다면 내장 Bot이 서드파티 base URL을 사용할 때 여전히 Responses를 호출할 수 있어요. 아래 실측 결과를 함께 보면, 이것이 400 오류의 원인일 가능성이 높아요. 해결 방법은 두 가지예요. 아직 변경 중이라는 점을 염두에 두고 main 브랜치를 기준으로 평가하거나, 이 변경이 정식 릴리스된 후 연동하는 거예요.
🚀 빠른 시작: OpenBot을 설정하기 전에 APIYI apiyi.com의 토큰으로
/v1/chat/completions를 별도로 호출해 보세요. 함수 정의를 함께 전달하고finish_reason이tool_calls를 반환하는지 확인하면 돼요. 인터페이스에 문제가 없다는 것을 확인하면 이후 오류를 해결할 때는 OpenBot 설정만 살펴보면 돼요.
먼저 도구 3개만 허용하기: OpenBot 초기 권한 제한
OpenBot에서 처음부터 모든 도구를 열면 안 되는 이유
공식 문서에서는 도구 수에 대해 이렇게 설명해요. “A model picks the right tool reliably out of about ten， and unreliably out of thirty.” 즉, 도구가 10개 정도일 때는 모델이 적절한 도구를 안정적으로 선택하지만, 30개에 이르면 선택을 신뢰하기 어려워진다는 뜻이에요. OpenBot 소스 코드에는 컴퓨터 관련 도구 13개가 등록되어 있어요. 여기에 MCP 디렉터리의 도구까지 더하면 첫날부터 이 기준을 쉽게 넘을 수 있어요.
도구가 12개를 넘는 Bot은 실행할 때마다 현재 메시지와 일치하는 스킬에 필요한 도구만 전달받아요. 하지만 공식 문서는 이것이 가시 범위를 좁힐 뿐이라며 “It is not a boundary， and it never substitutes for one”이라고 명시해요. 실제 경계는 Admin에서 Bot별로 부여하는 권한(grant), AGENT_COMPUTER_POLICY 동작 정책, 감사 기록의 세 가지예요. 출고 시 기본 설정은 deny: []와 allow: ["true"]로, 모든 동작을 허용한다는 점도 주의하세요.
초기 단계의 도구 3개 목록
| 도구 이름 | 역할 | 초기 단계 |
|---|---|---|
computer_navigate |
브라우저에서 URL 열기 | ✅ 허용 |
computer_snapshot |
페이지 스냅샷 가져오기 | ✅ 허용 |
computer_read_file |
작업 공간 파일 읽기 | ✅ 허용 |
computer_click / computer_type / computer_key |
클릭, 입력, 키 누르기 | ⏸ 검증 후 필요에 따라 허용 |
computer_write_file |
파일 쓰기 | ⏸ 검증 후 필요에 따라 허용 |
computer_run_command |
셸 명령 실행 | ⛔ 명시적으로 거부 |
computer_run_command는 반드시 별도로 차단해야 해요. Compose에서 COMPUTER_SEPARATE_WORKSPACES를 켜면 각 Bot이 자신의 폴더에서 셸을 실행하지만, 공식 문서에서도 “Commands can still read other folders”라고 인정해요. 즉, 명령으로 다른 폴더를 읽을 수 있어요. 실제 격리를 위해서는 computers.mode: sandbox가 필요해요. 초기 단계에서는 이 위험을 감수할 필요가 없어요.
AGENT_COMPUTER_POLICY 작성하기
정책은 JSON으로 작성하고, 규칙에는 CEL 표현식을 사용해요. tool.name, page.host, file.path 같은 필드를 읽을 수 있어요. 처음에는 다음과 같이 설정해 보세요.
.env에 한 줄을 추가해요:AGENT_COMPUTER_POLICY={"mode":"enforce","deny":["tool.name == 'computer_run_command'"],"allow":["tool.name in ['computer_navigate','computer_snapshot','computer_read_file']"]}- Admin에서 General Assistant에 이 세 도구만 부여해요.
- 서비스를 재시작해요. JSON 형식이 잘못되면 서버가 시작에 실패하므로 문제를 바로 발견할 수 있어요.
알아둘 평가 규칙이 두 가지 있어요. 첫째, deny가 allow보다 먼저 적용되므로 나중에 allow 범위를 넓히더라도 셸은 계속 차단돼요. 둘째, 엔진은 fail closed 방식으로 동작해요. 정책이 없거나 비어 있으면 아무것도 허용하지 않고, deny 규칙이 잘못되면 거부하며, allow 규칙이 잘못되면 허용하지 않아요. 원칙은 한마디예요. 처음에는 좁게 제한하고, 필요에 따라 허용하세요. 검증을 통과한 뒤 클릭, 입력, 파일 쓰기 권한을 하나씩 추가하고, 추가할 때마다 감사 기록을 확인하세요.
OpenBot에 APIYI 연동하기: 검증과 문제 해결
한 번에 검증하기: 웹페이지 열기, 파일 읽기, 감사 로그 확인
공식 아키텍처에서 도구 호출은 다음 순서로 진행돼요. 대상을 파악하고, 현재 정책에 따라 평가한 뒤, 감사 로그에 한 줄을 기록하고 나서 컴퓨터에 실제 동작을 요청해요. 전달한 동작이 실패하면 감사 로그에 한 줄을 더 기록해요. 컴퓨터 자체는 정책을 판단하지 않으며, 보안 경계는 서버의 gateway에 있어요. 따라서 검증할 때는 “동작할 수 있는지”와 “기록되는지”를 함께 확인해야 해요.
/workspace에notes.md파일을 만들고 아무 내용이나 두 줄 적어요.- General Assistant에게 공개 웹페이지 하나를 열어 제목을 알려주고,
/workspace/notes.md의 내용을 읽어 달라고 요청해요. - 이어서
ls /를 실행해 달라고 요청해요. 이 요청은 거부되어야 하며, 응답에서 어떤 규칙에 의해 차단됐는지도 알려줘야 해요. - Audit 페이지를 열어 navigate, snapshot, read_file의 허용 기록과 run_command의 거부 기록을 확인해요. 내보내기가 필요하면
GET /api/admin/audit-events?format=csv를 호출할 수 있으며, 한 번에 최대 5,000행까지 내보낼 수 있어요.
모델 측의 사용 가능 여부는 APIYI에서만 직접 테스트했어요. 2026-11-02에 claude-opus-5-5로 /v1/chat/completions를 호출하면서 read_file 함수 정의를 전달한 결과, HTTP 200이 반환됐어요. 응답 시간은 4.06초였고, finish_reason은 tool_calls, 인수는 {"path":"/workspace/notes.md"}였어요. 토큰 사용량은 프롬프트 393토큰, 완료 55토큰이었어요.
stream: true를 추가했을 때도 200이 반환됐어요. SSE 청크에서 함수 이름과 인수가 점진적으로 출력되는 것을 확인할 수 있었고, 마지막은 data: [DONE]으로 끝났어요. 이는 APIYI의 chat 엔드포인트가 Claude의 도구 호출을 OpenAI 형식으로 반환할 수 있다는 뜻이에요. 바로 “모델은 호출할 함수만 결정하고 실행은 담당하지 않는” Agent에 필요한 기능이에요.
문제 해결 표: 자주 발생하는 오류 다섯 가지
| 증상 | 가장 가능성 높은 원인 | 해결 방법 |
|---|---|---|
400 field messages is required |
요청이 Responses 엔드포인트로 전송됐어요. 테스트 결과 claude-opus-5-5로 APIYI의 /v1/responses를 호출하면 이 오류가 반환돼요 |
BOT_RESPONSES_API=false로 설정했는지 확인하세요. v0.2.0에서는 내장 Bot이 여전히 Responses를 호출할 수 있으므로, main 브랜치로 전환하고 COPILOTKIT_OPENAI_API=chat으로 설정해 보세요(아직 미출시 상태) |
| 401 | API 키가 잘못됐거나 만료됐거나, 토큰 잔액 한도를 모두 사용했어요 | APIYI 토큰 페이지에서 유효 기간과 잔액을 확인하고, curl로 /v1/models를 다시 테스트하세요 |
| 모델이 존재하지 않음 | default_model이 여전히 gpt-5.6-terra이거나 모델 이름 앞에 openai/가 붙어 있어요 |
두 곳 모두 접두어 없이 claude-opus-5-5만 입력하세요. 시작 검사를 건너뛰므로 메시지를 보내야 확인할 수 있어요 |
| 도구가 호출되지 않음 | 모델이 도구 호출을 지원하지 않거나, grant가 부여되지 않았거나, 정책이 도구를 차단했어요 | 공식 문서에 따르면 도구 호출 기능이 없는 Bot은 컴퓨터를 제어할 수 없어요. 먼저 감사 로그에 거부 기록이 있는지 확인하세요 |
| 시작이 거부됨 | Intelligence 설정이 누락됐거나, 정책 JSON이 잘못됐거나, provider spec에 공급자를 추가하면서 PROVIDER_IDS를 동기화하지 않았어요 |
Intelligence 설정 세 항목을 모두 채우고 JSON을 검증하세요. APIYI 연결에는 공급자를 추가할 필요 없이 openai를 그대로 사용하면 돼요 |
💡 문제 해결 팁: 오류가 발생하면 먼저 같은 요청을 APIYI apiyi.com의
/v1/chat/completions로 직접 보내 보세요. 직접 호출은 성공하고 OpenBot에서 실패한다면 OpenBot의 설정이나 버전 문제예요. 직접 호출도 실패한다면 토큰과 모델을 확인하세요. 이렇게 하면 문제 범위를 빠르게 좁힐 수 있어요.
OpenBot에서 Claude를 실행할 때 참고할 비용
APIYI는 고정 월 요금 없이 사용량에 따라 과금해요. 2026-11-02에 확인한 claude-opus-5-5의 가격은 다음과 같으며, claude-opus-5-5-thinking도 가격이 같아요.
| 과금 항목 | 단가(100만 토큰당) |
|---|---|
| 입력 | $4 |
| 출력 | $20 |
| 캐시 읽기 | $0.2 |
모델과 가격은 플랫폼의 모델 목록을 기준으로 확인하세요. 도구를 사용한 실측 요청에서 입력 토큰 393개와 출력 토큰 55개를 기준으로 계산하면, 한 번의 요청 비용은 아주 적어요. 다만 Bot이 여러 차례 탐색하고 파일을 읽기 시작하면 컨텍스트가 빠르게 늘어나므로, 토큰 잔액 상한도 함께 설정하는 것이 좋아요.
자주 묻는 질문
Q1: OpenBot을 APIYI에 연결하려면 소스 코드를 수정해야 하나요?
아니요. `.env`의 `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `BOT_MODEL` 세 줄을 수정하고, 테넌트 패키지의 `model.yaml`에서 `default_model`을 바꾸면 돼요. 완전히 새로운 공급자 유형을 추가할 때만 provider spec과 `PROVIDER_IDS`를 수정해야 해요. APIYI는 OpenAI 호환 인터페이스를 사용하므로 여기에 해당하지 않아요.
Q2: 왜 openai/claude-opus-5-5처럼 접두사를 붙이지 않나요?
OpenBot은 모델명을 그대로 전송하므로 엔드포인트가 제공하는 이름을 사용해야 해요. APIYI apiyi.com의 `/v1/models`에는 접두사 없는 `claude-opus-5-5`가 등록되어 있어요. 접두사를 붙이면 오히려 모델을 찾을 수 없어요.
Q3: BOT_RESPONSES_API를 켜서 Responses API를 사용할 수 있나요?
Claude를 연결할 때는 켜지 마세요. 실측 결과, `claude-opus-5-5`로 APIYI의 `/v1/responses`를 호출하면 400 `field messages is required`가 반환됐고, `gpt-5.4-mini`로 바꾸면 200이 반환됐어요. 공식 문서에서도 엔드포인트가 Responses API를 실제로 구현한 경우에만 이 설정을 켜도록 안내해요.
Q4: OpenBot 전체를 실행해 봤나요?
아니요. APIYI 측의 모델 목록, 도구를 사용한 chat 호출, 스트리밍 출력, Responses 엔드포인트의 오류만 검증했어요. OpenBot 전체(Docker와 Intelligence 프로젝트)는 글을 작성한 컴퓨터에서 실행하지 않았으며, 본문의 OpenBot 내부 동작에 관한 내용은 공식 저장소와 문서를 바탕으로 했어요.
Q5: 사용량에 따라 과금되는 키를 Bot이 과도하게 사용하지 않도록 하려면 어떻게 해야 하나요?
APIYI apiyi.com의 토큰 페이지에서 해당 키의 잔액 상한과 유효 기간을 설정하고, 프로덕션용 키와 분리해서 관리하세요. 여기에 이 글에서 소개한 도구 3개 정책을 함께 적용하면 Bot이 할 수 있는 일과 지출할 수 있는 금액을 모두 제한할 수 있어요.
요약
OpenBot과 APIYI 연동 핵심 정리
- 모델 설정은 화면에 없어요:
.env의 세 줄과 테넌트 패키지의model.yaml한 줄에 설정해요. - base_url은 배포 전체에 적용돼요:
OPENAI_BASE_URL을 바꾸면 세 종류의 Bot이 함께 전환돼요. - 시작에 성공해도 모델이 올바른지는 알 수 없어요: 게이트웨이 연결 후에는 검사가 생략되므로, 첫 메시지를 보내 확인해야 해요.
- 버전을 꼭 확인하세요:
/chat/completions호출 변경은 아직 main 브랜치의 Unreleased 상태이며, v0.2.0에는 포함되지 않았어요. - 처음에는 도구 3개만 허용하세요: deny가 allow보다 우선해요. shell은 별도로 거부하고, 범위를 좁게 시작해 점차 늘리세요.
- APIYI의 사용량 기반 요금제로 시작하세요: 전용 토큰과 잔액 한도를 설정하고,
claude-opus-5-5는 접두사 없이 사용해요.
OpenBot에서 모델 설정을 찾기 어려운 이유는 애초에 화면에 없기 때문이에요. .env의 세 줄과 model.yaml의 한 줄을 수정하고 Responses를 비활성화한 상태로 유지하세요. 여기에 도구 3개만 허용하는 정책으로 시작하면 전체 연동 과정을 파악하기 쉬워요. 검증할 때는 웹페이지가 열리는지, 파일을 읽을 수 있는지, 거부된 동작이 감사 로그에 기록되는지만 확인하면 돼요.
먼저 APIYI apiyi.com의 전용 토큰으로 채팅과 도구 호출을 별도로 테스트한 다음 OpenBot에 연동하는 걸 추천해요. 문제가 생겨도 어느 쪽에서 발생했는지 빠르게 파악할 수 있어요.
📚 참고 자료
- CopilotKit/OpenBot 저장소: README, 요구 사항 및 빠른 시작 가이드
- 링크:
github.com/CopilotKit/OpenBot -
설명: 템플릿의 목적, 사전 요구 사항, v0.2.0 릴리스 정보
-
OpenBot 설정 문서: 모델 환경 변수,
model.yaml, 시작 시 검증 - 링크:
github.com/CopilotKit/OpenBot/blob/main/docs/configuration.md -
설명:
OPENAI_BASE_URL,BOT_MODEL,BOT_RESPONSES_API의 원래 정의 -
OpenBot 아키텍처 문서: 게이트웨이, 정책 및 감사
- 링크:
github.com/CopilotKit/OpenBot/blob/main/docs/architecture.md -
설명: 도구 호출 순서, 감사 내역 내보내기 인터페이스
-
APIYI 문서 센터: OpenAI 호환 모드, 함수 호출, 모델 목록
- 링크:
docs.apiyi.com - 설명: base_url 작성 방식, tools 형식,
claude-opus-5-5가격
작성자: APIYI 기술팀
기술 관련 문의: APIYI 공식 사이트 apiyi.com에서 문의해 주세요. 더 많은 연동 자료는 docs.apiyi.com 문서 센터에서 확인할 수 있어요.
