11.8. 컨테이너 및 채널 API 참조¶

이 페이지는 NanoClaw 릴리스에 포함된 컨테이너 실행 및 멀티 채널 메시징 REST API 엔드포인트를 모두 정리한 참조 문서입니다. 모든 엔드포인트는 /api/v1 접두사로 시작하며, 인증이 활성화되어 있으면 요청에 API 키를 함께 보내야 합니다.

인증¶

curl -H "X-API-Key: your-api-key" http://localhost:55765/api/v1/container/runtime

컨테이너 런타임¶

런타임 상태 조회¶

GET /api/v1/container/runtime

감지된 컨테이너 런타임 백엔드를 반환합니다.

응답:

{
  "available": true,
  "backend": "apple_container",
  "version": "0.2.0",
  "networking": {
    "hostGateway": "192.168.64.1",
    "extraRunArgs": []
  },
  "message": "Apple Container runtime detected"
}

backend 값: "apple_container" | "docker" | null

컨테이너 이미지¶

에이전트 이미지 빌드¶

POST /api/v1/container/image/build

aigo-agent-runner 컨테이너 이미지를 비동기로 빌드합니다.

요청 본문:

{
  "imageTag": "aigo-agent-runner:latest"
}

응답:

{
  "success": true,
  "imageTag": "aigo-agent-runner:latest",
  "message": "Build completed successfully",
  "output": "..."
}

이미지 상태 확인¶

GET /api/v1/container/image/status

쿼리 파라미터: imageTag (선택, 기본값: aigo-agent-runner:latest)

응답:

{
  "exists": true,
  "imageTag": "aigo-agent-runner:latest",
  "message": "Image is ready"
}

마운트 보안¶

마운트 검증¶

POST /api/v1/container/mount/validate

요청 본문:

{
  "hostPath": "/Users/alice/projects/myapp",
  "containerPath": "/workspace/extra/myapp",
  "readOnly": true
}

응답:

{
  "allowed": true,
  "canonicalHostPath": "/Users/alice/projects/myapp",
  "message": "Mount validated successfully"
}

마운트 허용 목록 조회¶

GET /api/v1/container/mount/allowlist

응답:

{
  "allowedRoots": ["/Users/alice/projects"],
  "blockedPatterns": [".ssh", ".gnupg", ".env", ".aws", ".azure", ".gcloud", ".docker", ".kube"]
}

마운트 허용 목록 설정¶

PUT /api/v1/container/mount/allowlist

요청 본문:

{
  "allowedRoots": ["/Users/alice/projects", "/Users/alice/data"],
  "blockedPatterns": [".ssh", ".gnupg", ".env", ".aws"]
}

자격증명 프록시¶

프록시 상태 조회¶

GET /api/v1/container/credential-proxy/status

응답:

{
  "running": true,
  "port": 3001,
  "mappingCount": 2
}

프록시 시작¶

POST /api/v1/container/credential-proxy/start

프록시 중지¶

POST /api/v1/container/credential-proxy/stop

자격증명 매핑 추가¶

POST /api/v1/container/credential-proxy/mappings

요청 본문:

{
  "name": "Anthropic API",
  "upstreamUrl": "https://api.anthropic.com",
  "credentialType": "api_key",
  "credential": "sk-ant-..."
}

응답:

{
  "id": "mapping-uuid-...",
  "name": "Anthropic API",
  "placeholder": "CREDENTIAL_PROXY_PLACEHOLDER"
}

자격증명 매핑 삭제¶

DELETE /api/v1/container/credential-proxy/mappings/{id}

프록시 포트 설정¶

PUT /api/v1/container/credential-proxy/port

요청 본문:

{"port": 3001}

IPC¶

IPC 디렉터리 생성¶

POST /api/v1/container/ipc/directories

요청 본문:

{
  "group": "telegram-support",
  "sessionId": "session-abc123"
}

후속 메시지 전송¶

POST /api/v1/container/ipc/follow-up

컨테이너의 IPC 입력 디렉터리에 후속 메시지를 기록합니다.

요청 본문:

{
  "group": "telegram-support",
  "sessionId": "session-abc123",
  "content": "Focus on the authentication module first"
}

종료 신호 전송¶

POST /api/v1/container/ipc/close

컨테이너의 정상 종료를 요청하는 _close 신호 파일을 기록합니다.

요청 본문:

{
  "group": "telegram-support",
  "sessionId": "session-abc123"
}

컨테이너 큐¶

컨테이너 그룹 목록 조회¶

GET /api/v1/container/queue/groups

응답:

["telegram-support", "dev-team", "monitoring"]

큐 카운트 조회¶

GET /api/v1/container/queue/counts

응답:

{
  "queued": 3,
  "running": 2,
  "total": 5
}

그룹 상태 조회¶

GET /api/v1/container/queue/groups/{group}

최대 동시 컨테이너 수 조회/설정¶

GET  /api/v1/container/queue/max-concurrent
PUT  /api/v1/container/queue/max-concurrent

PUT 요청 본문:

{"maxConcurrent": 4}

그룹 네임스페이스¶

네임스페이스 목록 조회¶

GET /api/v1/container/namespaces

네임스페이스 생성¶

POST /api/v1/container/namespaces

요청 본문:

{
  "name": "telegram-support",
  "description": "Customer support channel"
}

네임스페이스 조회¶

GET /api/v1/container/namespaces/{name}

네임스페이스 수정¶

PUT /api/v1/container/namespaces/{name}

네임스페이스 삭제¶

DELETE /api/v1/container/namespaces/{name}

그룹 지침 조회/설정¶

GET /api/v1/container/namespaces/{name}/instructions
PUT /api/v1/container/namespaces/{name}/instructions

PUT 요청 본문:

{"instructions": "You are a support agent for Acme Corp..."}

전역 지침 조회/설정¶

GET /api/v1/container/namespaces/global/instructions
PUT /api/v1/container/namespaces/global/instructions

병합된 지침 조회¶

POST /api/v1/container/namespaces/merge-instructions

요청 본문:

{"groupName": "telegram-support"}

응답:

{
  "merged": "# Global Instructions\nAlways respond in the same language...\n\n# Group Instructions\nYou are a support agent..."
}

작업 스케줄¶

스케줄 목록 조회¶

GET /api/v1/container/schedules

스케줄 생성¶

POST /api/v1/container/schedules

요청 본문:

{
  "name": "Daily Report",
  "group": "reporting",
  "prompt": "Generate today's summary report",
  "schedule": {
    "type": "cron",
    "value": "0 9 * * 1-5"
  },
  "containerConfig": {
    "image": "aigo-agent-runner:latest",
    "timeoutSecs": 600,
    "env": []
  },
  "contextMode": "isolated",
  "enabled": true
}

스케줄 type 값:

cron: value에 cron 표현식 문자열을 지정합니다 (예: "0 9 * * 1-5")
interval: value에 밀리초 단위 숫자를 지정합니다 (예: 300000)
once: value에 ISO 8601 날짜/시간 문자열을 지정합니다 (예: "2026-04-01T02:00:00Z")

스케줄 조회¶

GET /api/v1/container/schedules/{id}

스케줄 수정¶

PUT /api/v1/container/schedules/{id}

스케줄 삭제¶

DELETE /api/v1/container/schedules/{id}

스케줄 로그 목록 조회¶

GET /api/v1/container/schedules/{id}/logs

쿼리 파라미터:

limit (기본값: 20, 최대: 500)
offset (기본값: 0)

감사 및 모니터링¶

감사 로그 조회¶

GET /api/v1/container/audit-log

쿼리 파라미터:

limit (기본값: 50, 최대: 500)
group: 그룹 이름으로 필터링
severity: 심각도로 필터링 (info, warning, violation, error)

실행 기록 조회¶

GET /api/v1/container/run-history

쿼리 파라미터:

limit (기본값: 50, 최대: 500)
group: 그룹 이름으로 필터링

메트릭 조회¶

GET /api/v1/container/metrics

실행 중인 컨테이너 수, 큐 깊이, 보안 이벤트 수 등 현재 컨테이너 메트릭을 반환합니다.

분석 데이터 조회¶

GET /api/v1/container/analytics

과거 실행을 집계한 분석 데이터(일별 실행 수, 성공률, 평균 소요 시간)를 반환합니다.

채널¶

채널 목록 조회¶

GET /api/v1/channels

응답:

{
  "channels": [
    {"name": "telegram", "connected": true, "statusMessage": "Connected"},
    {"name": "slack", "connected": false, "statusMessage": "Not configured"}
  ]
}

채널 상태 조회¶

GET /api/v1/channels/{name}

메시지 전송¶

POST /api/v1/channels/messages

요청 본문:

{
  "chatJid": "tg:123456789",
  "content": "Hello from Backend.AI GO!"
}

채팅 목록 조회¶

GET /api/v1/channels/chats

쿼리 파라미터:

channel: 채널 이름으로 필터링
limit (기본값: 100)

채팅 메시지 조회¶

GET /api/v1/channels/chats/{jid}/messages

쿼리 파라미터:

limit (기본값: 100, 최대: 1000)
before: Unix 타임스탬프, 이 시각 이전의 메시지만 반환

Telegram 채널¶

연결¶

POST /api/v1/channels/telegram/connect

요청 본문:

{"token": "1234567890:ABCdef..."}

연결 해제¶

POST /api/v1/channels/telegram/disconnect

토큰 검증¶

POST /api/v1/channels/telegram/validate

요청 본문:

{"token": "1234567890:ABCdef..."}

Slack 채널¶

연결¶

POST /api/v1/channels/slack/connect

요청 본문:

{
  "botToken": "xoxb-...",
  "appToken": "xapp-..."
}

연결 해제¶

POST /api/v1/channels/slack/disconnect

토큰 검증¶

POST /api/v1/channels/slack/validate

요청 본문:

{
  "botToken": "xoxb-...",
  "appToken": "xapp-..."
}

Discord 채널¶

연결¶

POST /api/v1/channels/discord/connect

요청 본문:

{"token": "your-discord-bot-token"}

연결 해제¶

POST /api/v1/channels/discord/disconnect

토큰 검증¶

POST /api/v1/channels/discord/validate

요청 본문:

{"token": "your-discord-bot-token"}

WhatsApp 채널¶

연결¶

POST /api/v1/channels/whatsapp/connect

요청 본문:

{
  "phoneNumberId": "123456789",
  "accessToken": "your-access-token",
  "webhookVerifyToken": "your-verify-token"
}

연결 해제¶

POST /api/v1/channels/whatsapp/disconnect

설정 검증¶

POST /api/v1/channels/whatsapp/validate

웹훅 검증 (WhatsApp Cloud API)¶

GET /api/v1/channels/whatsapp/webhook

WhatsApp이 hub.mode=subscribe, hub.verify_token, hub.challenge를 담은 GET 요청을 보내고, 검증 토큰이 일치하면 이 엔드포인트가 challenge 값을 그대로 돌려줍니다.

웹훅 수신¶

POST /api/v1/channels/whatsapp/webhook

수신 메시지 이벤트는 WhatsApp 서버가 이 엔드포인트를 호출해 전달하므로, 사용자가 직접 호출할 일은 없습니다.

발신자 허용 목록¶

허용 목록 조회¶

GET /api/v1/channels/sender-allowlist

응답:

{
  "enabled": true,
  "entries": [
    {"chatJid": "tg:123456789", "label": "Alice"},
    {"chatJid": "slack:U01ABCDEF", "label": "Bob"}
  ]
}

허용 목록 설정¶

PUT /api/v1/channels/sender-allowlist

요청 본문:

{
  "enabled": true,
  "entries": [
    {"chatJid": "tg:123456789", "label": "Alice"}
  ]
}