대형 기능 · AI 게이트웨이 HTTP API

AI 게이트웨이

외부 프로그램이 로컬 HTTP API로 {ai, prompt}를 보내면, orchterm가 그 AI(claude·codex·agy)를 워커 탭에 띄워 한 턴 실행하고 응답을 동기로 돌려줍니다 — 사람 개입 없는 자동 호출.

무엇을 하는가

외부 프로그램(스크립트·CI·인앱 브라우저 페이지)이 한 줄 프롬프트를 보내면, 게이트웨이가 워커 AI를 탭에 띄워 한 턴 돌리고 연결을 잡은 채 OpenAI 호환 응답을 반환합니다.

caller

외부 프로그램HTTP 클라이언트

POST /run

{ai, prompt}

orchterm

HTTP 서버:9610 · Bearer

워커 탭

1턴 실행

worker

claude · codex · agy워커 탭(1턴)

시작하기

게이트웨이 켜기 (재시작 후 적용)

새 설치는 게이트웨이가 켜진 채 시작합니다. 끄거나 다시 켜는 변경은 앱 재시작 후 적용됩니다.
Bearer 토큰 확인 · 복사

토큰은 최초 1회 랜덤으로 발급됩니다. 설정 → AI 게이트웨이에서 확인·복사해 호출자에게 전달하세요. 모든 요청에 Authorization: Bearer …가 필요하고, 불일치하면 401입니다.

설정 — AI 게이트웨이

AI 게이트웨이
켜짐

포트127.0.0.1 : 9610 (+base)

Bearer 토큰 · 최초 1회 랜덤(192비트)

워커 폴더~/.orchterm/gateway

① 127.0.0.1 전용이라 외부 네트워크 노출이 없습니다 · 토큰을 복사해 호출자에 전달.

워커는 고정 폴더(~/.orchterm/gateway)에서 실행돼 에이전트 신뢰 승인은 최초 1회만 필요합니다.

API 호출 — POST /run

요청은 POST /run(별칭 POST /v1/chat/completions). 본문에 보낼 AI와 프롬프트를 담으면, 응답이 올 때까지 연결을 잡고 OpenAI chat.completion JSON을 동기 반환합니다.

curl — 동기 호출200 · chat.completion

POST /run · 요청

$ curl -s http://127.0.0.1:9610/run \
    -H "Authorization: Bearer $ORCHTERM_GATEWAY_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{ "agent": "claude", "prompt": "PING", "session": "s1" }'

200 OpenAI chat.completion · 응답

{
  "id": "req_8f3a…", "object": "chat.completion",
  "choices": [
    { "index": 0,
      "message": { "role": "assistant", "content": "PONG" },
      "finish_reason": "stop" }
  ],
  "result": "PONG", "error": null // result·error = 레거시 호환
}

① 동기 모델 — 서버는 최대 360초 대기 후 미완료면 504.

본문 필드	의미
`agent` / `ai`	워커 종류 — claude · codex · agy (기본 `claude`)
`prompt` / `messages`	보낼 프롬프트. 둘 다 비면 `400`
`session`	keepalive 키(옵션) — 값이면 워커 재사용, 비우면 1회성
`model`	받지만 현재는 무시됩니다(추후)

세션 keepalive (멀티턴)

session 값을 주면 같은 session은 같은 워커를 재사용합니다 — 컨텍스트가 유지되는 멀티턴. 값을 비우면 응답 후 워커를 닫는 1회성입니다(“응답 후 워커가 사라졌다”는 버그가 아니라 이 동작).

session "s1" — 컨텍스트 유지

# turn 1 — 같은 session으로 첫 호출 $ curl …/run -d '{ "agent":"claude", "session":"s1", "prompt":"기억해: 바나나73" }' ◂ "알겠습니다. '바나나73' 기억했어요." # turn 2 — 같은 session, 워커 재사용 → 회상 $ curl …/run -d '{ "agent":"claude", "session":"s1", "prompt":"아까 코드 뭐였지?" }' ◂ "바나나73 입니다."

▲ turn1의 “바나나73”을 turn2가 회상 — 같은 워커·같은 세션을 재사용.

워커 안전 모드 (기본 ON)

게이트웨이 워커는 기본적으로 안전 모드로 돌아갑니다 — 위험 권한 우회 플래그를 쓰지 않습니다. 우회 모드(무인·빠르지만 비권장)는 설정 “워커 위험 권한 우회”로만 켭니다.

주의 — 게이트웨이는 외부 프로그램이 로컬에서 AI를 부리는 관제탑(control plane)입니다. 토큰·로컬 바인딩·안전 모드 기본값을 함부로 끄지 마세요.

감사 로그 (요청/응답 기록 + 뷰어 탭)

게이트웨이가 켜져 있으면 인증을 통과한 모든 요청을 일자별로 기록합니다 — 프롬프트·시각·총소요·상태(ok·error·timeout)·응답 원문까지. 팔레트 명령 “게이트웨이 감사 로그”로 뷰어 탭을 엽니다.

게이트웨이 감사 로그 — 뷰어 탭

게이트웨이 감사 로그

2026-06-28

요청 (최근 24 / 총 24)

14:02:51기억해: 바나…나나733.1sok

14:02:09PING2.4sok

13:58:44SSH 터널…전성 검토41.8sok

13:55:02대용량 리…파싱 요약360stimeout

═══ 드래그 ═══

요청 원문

{ "agent": "claude", "session": "s1",
  "prompt": "기억해: 바나나73" }

응답 원문

{ "result": "알겠습니다. '바나나73' 기억했어요.",
  "error": null } // totalMs 3142 · status ok

‹ 2026 · 6월 ›

일월화수목금토 31123456 78910111213 14151617181920 21222324252627 2829301234

① 날짜 → 달력 팝업(로그 있는 날만 선택). ② 위쪽 요청 목록 ↕ 아래쪽 상세(요청·응답 원문).

보관 일수는 설정에서 정합니다(기본 10일) — 초과 날짜는 자동 삭제됩니다. 응답은 원문 전량을 저장합니다.

AI 게이트웨이

무엇을 하는가

시작하기