Telegram — CLI-JAW 문서

Telegram을 통해 CLI-JAW 에이전트를 원격으로 제어하세요. 메시지 전송, 응답 수신, 에이전트 출력 전달, STT를 활용한 음성 메시지 처리, 슬래시 명령어 사용까지 -- 모두 휴대폰에서 가능합니다.

설정

1. BotFather로 봇 생성

Telegram에서 @BotFather를 엽니다
/newbot을 보내고 안내에 따릅니다
봇 토큰을 복사합니다 (123456:ABC-DEF... 형태)

2. settings.json 구성

{
  "telegram": {
    "token": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
    "allowedChatIds": [],
    "forwardAll": true
  }
}

처음에는 allowedChatIds를 비워 두세요. 봇에 /id를 보내 채팅 ID를 확인한 후, 보안을 위해 배열에 추가하세요.

3. 대안: jaw init 사용

jaw init --channel telegram --telegram-token "YOUR_TOKEN"

메시지 송수신

텍스트 메시지 -- 봇에 텍스트를 보내면 에이전트에 프롬프트로 전달됩니다
슬래시 명령어 -- Telegram에서 직접 /model, /cli, /status 등을 사용할 수 있습니다
사진 및 문서 -- 첨부 파일은 다운로드되어 저장되고, 에이전트에 설명이 전달됩니다
음성 메시지 -- Gemini STT(또는 Whisper 폴백)를 통해 텍스트로 변환되어 전송됩니다

전달

forwardAll이 true이면 에이전트의 agent_done 결과가 자동으로 Telegram 채팅으로 전달됩니다. Telegram에서 시작된 결과는 에코를 방지하기 위해 제외됩니다.

/forward on   # Enable forwarding
/forward off  # Disable forwarding

파일 전송

에이전트는 채널 전송 API를 사용하여 Telegram으로 파일을 보낼 수 있습니다:

POST /api/telegram/send
POST /api/channel/send  # Unified endpoint (preferred)

파일은 20MB 크기 제한에 따라 검증됩니다. Telegram 메시지는 4096자 단위로 분할되며 Telegram HTML 형식으로 변환됩니다.

그룹 채팅

그룹/슈퍼그룹 채팅에서는 @botUsername으로 멘션할 때만 봇이 응답합니다. 멘션은 처리 전에 메시지에서 자동으로 제거됩니다.

Dashboard Telegram Hub (P0–P4)

포럼 토픽을 서로 다른 CLI-JAW 인스턴스로 라우팅합니다. Manager UI에서 (chatId, threadId) → port 매핑을 설정합니다. Hub 명령어: /setthread, /threads, /hubhelp. P4: Manager UI에서 토픽별 model/systemPrompt override. 자세한 hub-member relay 모델은 structure/telegram.md를 참조하세요.

Watchdog 진단

에이전트 턴이 idle/progress watchdog 임계값을 넘어 멈추면, 종료 진단이 원래 Telegram 채팅 또는 포럼 토픽으로 전달되어 운영자가 턴이 끝난 이유를 확인할 수 있습니다.

사용 가능한 명령어

CLI/Web/Telegram/Discord에 51개 슬래시 명령어가 등록되어 있습니다 (Telegram에서 37개 표시). workflow helper: /plan, /interview, /review, /search, /goal, /orchestrate, /task, /fork, /gd. CLI/Web 동적 /skill:<id>. 봇 전용 명령어:

명령어	설명
`/start`	환영 메시지
`/id`	채팅 ID 표시
`/settings`	봇 설정 (서버가 아닌 봇에서 처리)

환경 변수

환경 변수를 통해 설정을 재정의할 수 있습니다:

TELEGRAM_TOKEN=123456:ABC-DEF...
TELEGRAM_ALLOWED_CHAT_IDS=12345,67890

Kanban Board Discord