orke support

내 서비스가 질문을 보내면, 내 PC나 서버의 AI가 답합니다.
간단한 안내 AI부터 만들고, 실제 서비스 연결은 그다음에 해보세요.

실습 포함 · AI 만들기 → 시험 → 서비스 연결한국어

어떤 기능인가요?

내 서비스에서 호출할 수 있는 AI를 만드는 기능입니다. 이름, 사용할 AI, 지시문을 설정하면 내 서비스의 서버가 질문을 보내고 답을 받아 사용할 수 있습니다.

쇼핑몰 서버가 “배송은 며칠 걸리나요?”를 보내면 정해둔 안내에 따라 답합니다. 실제 주문 현황이 필요하면 그 정보를 조회하는 도구를 별도로 연결합니다.

예: 쇼핑몰 서버내 서비스

→

내가 설정한 AIorke support

→

서비스에 전달답변

홈페이지의 「지원」과 다른 기능입니다

상단 메뉴의 「지원」은 orke 사용 중 문의할 때 이용합니다. 앱 안의 「orke support」는 내 서비스에 AI 기능을 연결할 때 이용합니다.

세 가지만 먼저 기억하세요

이름	쉬운 뜻	쇼핑몰 예시
AI	역할과 답변 규칙을 정한 담당자	「쇼핑몰 안내」라는 이름의 AI
방	대화를 이어가는 한 묶음	고객 한 명과 나누는 상담 한 건
접속 키	내 서비스가 이 AI를 부를 때 사용하는 비밀값	쇼핑몰 서버가 질문에 함께 보내는 키

같은 방에 다음 질문을 보내면 앞의 대화를 이어갑니다. 새로운 상담은 새 방으로 시작하세요.

예제: 쇼핑몰 안내 AI 만들기

사용할 AI의 로그인 확인하기

현재 로그인한 Claude 또는 ChatGPT의 CLI를 사용합니다. 설정 › 계정에서 사용할 계정을 확인하세요. support는 터미널과 같은 현재 계정을 사용합니다.

질문을 처리하면 해당 계정의 사용 한도가 쓰입니다. 질문을 받을 동안 orke가 실행 중이어야 합니다.

✓선택할 AI의 CLI와 로그인이 준비되어 있습니다.

새 AI에 이름과 지시문 넣기

orke support 창에서 새 AI를 만듭니다. 이름은 「쇼핑몰 안내」로 하고, 준비된 계정과 모델을 선택합니다.

「지시문」에 넣을 예시너는 우리 쇼핑몰의 안내 담당자야.
배송은 결제 후 영업일 기준 2~3일 걸리고, 배송비는 3,000원이야.
고객에게 짧고 친절한 한국어로 답해줘.
개별 주문 현황은 아직 조회할 수 없으니 추측하지 말고 상담원에게 확인하도록 안내해줘.

첫 연습은 MCP 서버 없이, 기본 도구를 끈 상태로 시작하세요. 답 형식과 한도는 화면의 기본값을 확인한 뒤 만듭니다.

✓AI 목록에 「쇼핑몰 안내」가 생깁니다.

한 번 표시되는 접속 키 보관하기

만든 직후 접속 키 전체가 한 번 표시됩니다. 복사해 내 서비스 서버에서 사용할 안전한 곳에 보관하고 「키를 저장했습니다」를 누릅니다.

키를 잃으면 새로 만들 수 있지만 이전 키는 사용할 수 없게 됩니다. 연결한 서비스도 새 키로 바꿔야 합니다.

✓실제 서비스 연결에 사용할 키를 보관했습니다.

테스트 탭에서 먼저 질문하기

「테스트」 탭에서 “배송비가 얼마인가요?”라고 물어보세요. 「사용자 정보」 칸에는 연습용 demo_01을 사용할 수 있습니다.

같은 테스트 대화에서 “배송은 며칠 걸려요?”를 이어 물어봅니다. 테스트는 「질문 받기」를 꺼도 실행됩니다. 테스트 대화는 일반 대화 목록에 남지 않으며 이 창을 닫으면 삭제됩니다. 실제 서비스로 질문을 받기 전에 「질문 받기」를 켜세요.

✓배송비 3,000원과 배송 기간의 안내에 맞춰 답합니다.

내 서비스에서 질문 보내기

앱에서 시험이 끝났다면 「연결」 탭을 엽니다. 실제 주소와 요청 예제를 복사할 수 있습니다. 웹페이지의 JavaScript가 직접 부르는 대신, 내 서비스의 서버에서 호출합니다.

내 PC에서 연습할 때와 외부에서 연결할 때

같은 PC에서는 기본 입구 http://127.0.0.1:48700/v1을 사용합니다. 외부 서비스에서 부르려면 해당 입구로 연결되는 HTTPS 프록시 주소가 필요합니다. orke 화면에 접속하는 ngrok 주소는 support API 주소와 별개입니다.

먼저 대화할 방을 만듭니다

다음은 macOS·Linux 셸 기준 예시입니다. 내_접속_키를 실제 키로 바꾸세요. Windows에서는 연결 탭의 요청을 사용하는 셸에 맞춰 실행합니다.

방 만들기 · 내 PC에서 연습

curl --request POST "http://127.0.0.1:48700/v1/rooms" \
  --header "Authorization: Bearer 내_접속_키" \
  --header "Content-Type: application/json" \
  --data '{"user":"demo_01"}'

응답의 room_id가 방 번호입니다. 아래의 내_방_ID를 이 값으로 바꿉니다.

질문 보내기

curl --request POST "http://127.0.0.1:48700/v1/rooms/내_방_ID/messages" \
  --header "Authorization: Bearer 내_접속_키" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: shipping-question-001" \
  --data '{"text":"배송은 며칠 걸리나요?"}'

요청은 답이 완성될 때까지 기다립니다. 성공한 응답은 status: "done"이며, 기본 답 형식에서는 output.answer에서 답을 읽습니다.

응답 중 확인할 부분 · 설명용 예시

{
  "status": "done",
  "output": {
    "answer": "결제 후 영업일 기준 2~3일 걸립니다."
  }
}

새 질문은 새 Idempotency-Key를 사용합니다. 같은 질문의 응답을 못 받아 다시 연결할 때는 같은 키와 같은 글을 사용해 중복 실행을 방지합니다.

실제 주문을 조회하려면 MCP를 연결합니다

앞의 예시는 지시문에 적힌 안내만 알고 있습니다. 실제 주문 상태를 알려주려면 주문 데이터를 조회하는 도구가 필요합니다.

MCP 서버는 AI가 사용할 외부 도구를 제공하는 연결입니다. 쇼핑몰의 개발자가 주문 조회 MCP를 준비하면 AI 설정의 「MCP 서버 붙이기」에서 연결합니다. 연결 테스트과 질문 테스트을 모두 해보세요.

방을 만들 때의 user는 질문한 사람을 구분하기 위한 값입니다. 내 서비스 서버가 로그인한 고객의 값을 정해 보내고, 조회 서비스도 그 고객에게 허용된 주문만 반환하도록 구성해야 합니다.

처음 연습에서는 기본 도구를 꺼두세요

기본 도구를 켜면 AI가 할 수 있는 일이 늘어납니다. Claude의 셸 도구는 OS 사용자 권한으로 동작하고, ChatGPT의 셸은 기본 읽기 전용 샌드박스를 사용합니다. 필요한 외부 조회는 목적에 맞는 MCP 도구로 연결하세요.

운영 중 확인할 것

상황	설명과 해결
로그인 필요	현재 계정의 CLI 로그인을 완료하고 다시 질문합니다.
한도 대기	계정의 한도 상태를 확인합니다. 줄 선 질문과 거절된 질문을 구분합니다.
MCP 연결 실패	MCP 서버의 실행·주소·인증을 확인하고 연결을 시험합니다.
지시문 변경이 반영되지 않음	변경은 다음 새 방부터 적용됩니다. 새 방에서 시험합니다.
방의 기억을 잃음	그 방의 AI 대화를 이을 수 없습니다. 새 방에서 시작합니다.
키 새로 만들기	이전 키가 무효가 됩니다. 내 서비스의 키도 함께 교체합니다.
방 지우기	진행 중 질문을 취소하고 해당 방의 작업 폴더와 연결된 AI 대화 기록을 지웁니다.

API에서 사용하는 요청

요청	하는 일
`GET /v1/health`	API 입구 상태를 확인합니다. 이 요청에는 접속 키가 필요하지 않습니다.
`POST /v1/rooms`	대화방을 만듭니다. user는 선택값이며 서비스 서버에서 정합니다.
`POST /v1/rooms/{room_id}/messages`	질문을 보내고 답이 완성될 때까지 기다립니다.
`GET /v1/rooms/{room_id}/messages`	대화 기록을 읽습니다. after와 limit으로 다음 목록을 읽습니다.
`GET /v1/rooms/{room_id}/messages/{message_id}`	한 질문의 현재 상태와 결과를 확인합니다.
`DELETE /v1/rooms/{room_id}`	대화와 연결된 기록을 지웁니다. 진행 중 질문은 취소됩니다.

방 만들기와 질문에는 해당 AI의 접속 키를 Bearer 헤더로 보냅니다. 성공 여부를 HTTP 코드와 응답의 status·error에서 함께 읽습니다. 완료되지 않은 답의 output을 정상 답으로 사용하지 않습니다. API는 웹페이지가 직접 호출하는 CORS 연결을 제공하지 않으므로 서비스 서버에서 호출하세요.

실제 서비스에 연결하기 전에

테스트 질문의 성공을 확인한 뒤 필요한 모델과 한도, 보관 기간을 정합니다. 계정의 이용 조건이 다른 사람의 요청을 처리하는 용도를 허용하는지도 각 공급자 안내에서 확인하세요. 관련 설명과 출처는 지원의 에이전트·서비스 안내에서도 볼 수 있습니다.

외부 연결의 HTTPS 프록시 설정 예는 orke support 설정에서 확인할 수 있습니다. 입구는 기본으로 127.0.0.1:48700에서만 열립니다. 설정의 플랫폼 요청 URL을 입력하면 연결 탭의 예시에도 그 주소가 반영됩니다. AI와 입구를 실제로 운영할 PC나 서버에서 준비하세요.