grinev/opencode-telegram-bot

OpenCode mobile client via Telegram: run and monitor AI coding tasks from your phone while everything runs locally on your machine. OpenCode V2 support.

OpenCode Telegram Bot – 개요

OpenCode Telegram Bot 은 Telegram 채팅에서 OpenCode AI 코딩 어시스턴트(로컬 CLI 도구)를 제어할 수 있는 Node.js 애플리케이션입니다. OpenCode 서버와 같은 머신에서 실행되며 Telegram 봇 API와 통신하므로 인터넷에 포트를 열 필요가 없습니다.

주요 기능

원격 프롬프트 – 텍스트, 음성 또는 파일을 봇에 보내면 OpenCode가 코드를 생성하고 Telegram 파일로 반환합니다.
세션 관리 – 채팅 명령에서 직접 OpenCode 세션을 생성, 전환, 중단 또는 분리할 수 있습니다.
실시간 추적 – 실행 중인 OpenCode 세션을 추적하여 진행 상황, 하위 에이전트 활동, 모델 사용량을 실시간으로 표시합니다.
모델 및 에이전트 전환 – 즐겨찾는 모델을 선택하거나 Plan 및 Build 에이전트 모드를 즉시 전환할 수 있습니다.
파일 브라우저 – /ls를 사용하여 프로젝트 디렉터리 트리를 탐색하고 파일을 다운로드하거나 다음 프롬프트에 첨부할 수 있습니다.
예약 작업 – 나중에 또는 반복 간격으로 실행할 프롬프트를 미리 정의할 수 있습니다.
음성 입력 – 선택적 Whisper 호환 음성-텍스트 변환.
보안 – 지정한 Telegram 사용자 ID만 봇과 상호 작용할 수 있습니다.
현지화 – UI가 12개 언어로 제공됩니다.
Docker 지원 – OpenCode 서버를 호스트에 두고 컨테이너 내에서 실행할 수 있습니다.

실행 방법

Telegram 봇 생성 @BotFather에서 토큰을 받습니다.
OpenCode 설치 (AI 코딩 CLI) 및 서버 시작 (opencode serve).
봇 설치 npm (npx @grinev/opencode-telegram-bot@latest 또는 전역 설치)으로 설치하고 대화형 마법사를 실행합니다. 마법사에서 봇 토큰, Telegram 사용자 ID, OpenCode 버전(V1 또는 V2), API URL, 자격 증명을 묻습니다.
봇과 채팅 – 차단 상호 작용(예: 메뉴)이 활성화되지 않는 한 일반 텍스트 메시지는 모두 프롬프트가 됩니다.

주요 Telegram 명령 (선택)

명령	기능
`/status`	봇 버전, 서버 상태, 현재 프로젝트, 세션 및 모델 표시
`/new`	새 OpenCode 세션 시작
`/abort`	현재 작업 취소
`/sessions`	최근 세션 찾아보기 및 전환
`/ls`	대화형 파일 브라우저
`/settings`	런타임 기본 설정 조정
`/task` / `/tasklist`	예약된 프롬프트 생성 및 관리
`/opencode_start` / `/opencode_stop`	Telegram에서 로컬 OpenCode 서버 제어

구성

환경 변수 또는 .env 파일(OS별 앱 데이터 폴더에 저장)로 봇 토큰, 허용 사용자 ID, 프록시 설정, OpenCode 서버 URL, 버전 및 선택적 제한(예: TASK_LIMIT)을 제공합니다.
<appHome>/local-commands/에 배치한 로컬 JSON 명령 파일은 호스트에서 임의의 셸 명령을 실행하는 사용자 지정 /command 단축키가 됩니다.

대상 사용자

이미 OpenCode를 AI 지원 코딩에 사용하고 있으며 서버가 로컬에서 실행되는 동안 휴대폰에서 편리하고 안전하게 상호 작용하려는 개발자. 독립형 AI 모델이 아니라 기존 OpenCode 서비스에 명령을 전달하는 얇은 클라이언트입니다.

위의 모든 세부 정보는 저장소의 README에서 직접 가져온 것입니다.