[기술검토] Claude Code Channels — 헤드리스 실행 대체 가능성 분석

📌 Claude Code v2.1.80의 실험 기능 Channels(MCP 기반 이벤트 주입)가 기존 claude -p subprocess 헤드리스 실행을 대체할 수 있는지 검토한 문서. 결론은 현행 유지 — Channels는 결정론적 스킬 실행·구조화 출력 수집에 부적합하며, 원격 권한 승인(Permission Relay)만 부분 도입 가치가 있다.

작성일: 2026-06-12 상태: 초안

---

1. 개요

자체 구축 멀티에이전트 하네스(이하 AI 개발 파이프라인)는 현재 스킬·커맨드 실행 시 claude -p 또는 사내 AI 래퍼 를 subprocess로 직접 호출하는 방식을 사용한다. Claude Code v2.1.80에서 Channels라는 새 실험적 기능이 공개됐다. 이 문서는 Channels가 무엇인지 설명하고, 현재 파이프라인에 적용 가능한지를 기술적으로 검토한다.

---

2. 현재 구조: claude -p / 사내 AI 래퍼

2.1 실행 흐름

2.2 특징

2.3 코드 위치 (파이프라인 내부)

• subprocess 빌드: 헤드리스 실행 워커 스크립트의 _build_claude_cmd
• inline 변환: 같은 스크립트의 _transform_to_inline_cmd
• 스케줄러 호출: 백엔드 collectors의 schedule_runner
• Harness 수동 실행: 백엔드 API의 harness 유틸 라우트

---

3. Claude Code Channels란?

3.1 정의

"A channel is an MCP server that pushes events into a running Claude Code session so Claude can react to things happening outside the terminal." — Anthropic 공식 문서

Channels는 Claude Code 세션이 이미 열린 상태에서, 외부 시스템이 이벤트를 주입할 수 있게 해주는 MCP 서버다.

3.2 작동 원리

3.3 MCP 서버 예시 (최소 구현)

// webhook-channel.ts (Bun)
import { Server } from '@modelcontextprotocol/sdk/server/index.js'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'

const mcp = new Server(
  { name: 'webhook', version: '0.0.1' },
  {
    capabilities: { experimental: { 'claude/channel': {} } },  // 채널로 선언
    instructions: '이벤트가 <channel source="webhook"> 형식으로 도착합니다. 내용을 읽고 행동하세요.',
  },
)

await mcp.connect(new StdioServerTransport())  // Claude Code와 stdio 연결

Bun.serve({
  port: 8788,
  async fetch(req) {
    const body = await req.text()
    // Claude 세션에 이벤트 주입
    await mcp.notification({
      method: 'notifications/claude/channel',
      params: { content: body, meta: { path: new URL(req.url).pathname } },
    })
    return new Response('ok')
  },
})

3.4 Claude가 받는 형식

<channel source="webhook" path="/jira-event">
  이슈 ISSUE-1234가 In Progress로 변경되었습니다.
</channel>

3.5 양방향 통신 (Reply Tool)

채널은 단방향 이벤트 수신만 지원하는 게 아니라, Claude가 응답을 돌려보낼 도구도 제공할 수 있다:

// MCP 서버에 reply 도구 등록
mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [{
    name: 'reply',
    description: '이 채널로 메시지를 돌려보냅니다',
    inputSchema: {
      type: 'object',
      properties: { text: { type: 'string' } },
      required: ['text'],
    },
  }],
}))

3.6 권한 원격 승인 (Permission Relay)

[Claude Code] → "Bash 실행 허가 필요" 알림 → [Channel Server] → Telegram/Slack → 사용자 승인
사용자: "yes abcde" → [Channel Server] → [Claude Code] → 자동 승인

---

4. claude -p vs Channels 비교

---

5. 파이프라인에 Channels 적용 가능성

5.1 핵심 차이: "실행 방식"이 근본적으로 다르다

Channels는 이미 실행 중인 Claude Code 세션을 전제로 한다. 즉, 누군가 claude 대화형 터미널을 열어둬야 채널이 이벤트를 받을 수 있다.

5.2 헤드리스 환경에서의 Channels 가능성

Anthropic 공식 문서에 따르면, 채널은 claude --channel 플래그로 헤드리스 세션과 함께 실행할 수 있다:

# 헤드리스 + 채널 조합 (실험적)
claude --channel webhook --no-interactive

이론적으로는 다음과 같은 구성이 가능하다:

파이프라인 백엔드
    │
    │ HTTP POST to Channel Server
    ▼
Channel MCP Server (webhook.ts)
    │ stdio
    ▼
claude --channel webhook (헤드리스 세션, 장기 실행)
    │
    ▼ 이벤트 수신 → 스킬 자율 실행

5.3 구현 시 해결해야 할 문제들

5.4 실용성 평가

현재 요구사항:
  - Jira 이슈 기반 자동화 파이프라인 (스케줄러)
  - 스킬을 결정론적으로 실행 (특정 스킬, 특정 파라미터)
  - 실행 결과를 DB에 저장
  - 병렬 다수 실행 지원
  - 타임아웃·킬 제어

Channels 적합성:
  - ❌ 결정론적 스킬 호출 → Channels는 Claude의 자율 판단에 의존
  - ❌ 구조화된 출력 수집 → 별도 훅 시스템 필요
  - ❌ Research Preview → Production 사용 불안정
  - ✅ 원격 권한 승인 → Permission Relay 활용 가능
  - ✅ 이벤트 기반 트리거 → Webhook 수신 후 Claude 반응
  - △ 장기 실행 세션 → 데몬 방식으로 응용 가능

---

6. 결론 및 권고사항

6.1 단기 (현재): 현행 유지

claude -p / 사내 AI 래퍼 방식을 유지한다.

• 현재 구조는 안정적이고 결정론적이다
• stream-json 출력 수집 파이프라인이 성숙하다
• Channels는 Research Preview로 프로덕션 적합성 미검증

6.2 중기: Permission Relay 부분 도입 검토

Channels 전체를 대체하는 게 아닌, 원격 권한 승인 기능만 부분 도입:

현재: --dangerously-skip-permissions (전체 허용)
개선안: 민감한 작업은 Channel Permission Relay → Slack/Teams 승인

6.3 장기: Channels 기반 상시 세션 에이전트 실험

향후 Claude Code가 Channels를 안정화하면, 상시 실행 에이전트 세션 방식 실험 가능:

Channel Server (pipeline-channel)
    │ stdio
    ▼
claude --channel pipeline-channel (데몬, 상시 실행)
    │
    ├─ 이벤트: "ISSUE-1234 이슈 자동개발 요청"
    ├─ 이벤트: "ISSUE-5678 코드리뷰 요청"
    └─ 이벤트: "스케줄러 트리거: 야간 배치"

단, 이 방식은 세션 상태 격리, 병렬성, 출력 구조화 문제를 해결한 후 도입해야 한다.

요약 표

---

7. 참고 자료

• Claude Code Channels Reference — Anthropic 공식
• Run Claude Code Programmatically — Anthropic 공식
• MCP SDK — 채널 서버 개발 SDK
• Anthropic Official Channel Implementations — Telegram, Discord, iMessage 참조 구현

---

부록: Channels로 현재 방식을 "에뮬레이션"한다면?

현재 /자동개발 ISSUE-1234 실행 흐름을 Channels로 구현하면:

// pipeline-channel.ts
// 1. 파이프라인 백엔드가 이 채널에 HTTP POST
// 2. Claude Code 세션이 이벤트를 수신
// 3. Claude가 스킬을 자율 호출

await mcp.notification({
  method: 'notifications/claude/channel',
  params: {
    content: '/자동개발 ISSUE-1234',           // 스킬 명령을 이벤트 본문으로 전달
    meta: { source: 'scheduler', priority: 'high' },
  },
})

⚠️ 한계: Claude가 /자동개발 ISSUE-1234를 슬래시 커맨드로 인식하려면 시스템 프롬프트(instructions)에 명시적 지시가 필요하고, 실제로 해당 커맨드를 호출하는지는 Claude의 판단에 따른다. claude -p "/자동개발 ISSUE-1234"처럼 직접 실행을 보장할 수 없다.