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. Scheduled tasks support.

OpenCode Telegram Bot – 무엇인가요

Node.js 기반의 Telegram 봇으로, 스마트폰에서 OpenCode AI 코드 생성 CLI를 제어할 수 있습니다. 이 봇은 로컬 OpenCode 서버 (같은 머신에서 실행 중)와 공식 Telegram Bot API만과 통신하며, 공개 포트나 노출된 API가 필요하지 않습니다. 실제로는 Telegram 채팅에서 코드 세션을 시작하고, 모델을 전환하며, 파일을 전송하고, 실시간 진행 상황을 확인하고, 작업을 스케줄링하며, 설정을 관리할 수 있습니다.

핵심 기능 (README에 설명됨)

영역	Telegram에서 할 수 있는 일
원격 코드 작성	텍스트 프롬프트(또는 음성 변환 프롬프트)를 OpenCode에 전송하고 생성된 코드를 파일로 받습니다.
세션 관리	새 세션 생성 (`/new`), 기존 세션 계속 (`/sessions`), 이름 변경 (`/rename`), 중단 (`/abort`), 분리 (`/detach`).
실시간 추적	실행 중인 OpenCode CLI 세션을 따라가며 실시간 에이전트 출력, 서브에이전트 단계, 다른 TUI 클라이언트로부터 오는 외부 입력을 표시합니다.
모델 관리	OpenCode의 즐겨찾기나 최근 사용 기록에서 모델을 선택하거나, 제공자별로 모든 모델을 직접 채팅에서 탐색합니다.
에이전트 모드	Plan과 Build 모드를 실시간으로 전환하고, 서브에이전트 활동을 관찰합니다.
스킬 및 명령어	OpenCode의 "스킬"이나 사용자 정의 명령어 (`/skills`, `/commands`)를 탐색하고, 선택적 인수와 함께 실행합니다.
파일 상호작용	이미지, PDF, 텍스트 기반 파일을 업로드합니다. `/ls`로 프로젝트 파일 시스템을 탐색하고, 파일을 다운로드하거나 다음 프롬프트에 파일을 첨부합니다.
스케줄된 작업	단일 또는 반복 프롬프트 생성 (`/task`, `/tasklist`). 반복 작업은 최소 5분 간격으로 실행되며, 기본적으로 최대 10개까지 가능합니다.
상태 및 알림	고정 메시지로 프로젝트/워크트리, 모델, 컨텍스트 사용량, 변경된 파일을 지속적으로 표시합니다. 백그라운드 세션 알림은 분리된 세션 상태를 알려줍니다.
설정 및 로컬라이제이션	`/settings`로 런타임 옵션(메시지 큐, 컨텍스트 압축, STT 등)을 조정할 수 있습니다. `BOT_LOCALE`을 통해 10개 언어로 UI를 사용할 수 있습니다.
보안	봇과 통신할 수 있는 Telegram 사용자 ID는 화이트리스트에 등록된 사용자만 가능하며, 다른 사용자는 무시됩니다.
Docker 및 데몬 모드	OpenCode는 호스트에 유지한 채 컨테이너 내에서 봇을 실행하거나, 내장된 데몬(`opencode-telegram start --daemon`)을 사용합니다.

시작하기 (빠른 시작 흐름)

@BotFather로 Telegram 봇 생성하고 토큰을 기록합니다.
@userinfobot로 Telegram 숫자형 사용자 ID 확인합니다.
같은 머신에서 OpenCode 서버 시작: opencode serve (기본 API URL: http://localhost:4096).
봇 실행 – 가장 쉬운 방법은 원라인 명령어:
```
npx @grinev/opencode-telegram-bot@latest
```
필요한 환경 변수가 누락된 경우, 인터랙티브 워즈드가 토큰, 사용자 ID, API URL 등을 묻고 플랫폼별 설정 디렉터리에 .env 파일을 생성합니다.
Telegram 열기, 새 봇과 채팅 시작 후 프롬프트 전송을 시작합니다.

대체 설치 방법 – npm i -g @grinev/opencode-telegram-bot 후 opencode-telegram start. --daemon을 사용해 자체 완전한 백그라운드 프로세스를 실행하거나, 문서에 설명된 대로 systemd/pm2/Docker에 통합합니다.

설정 요약

변수	의미	일반적인 기본값
`TELEGRAM_BOT_TOKEN`	BotFather에서 받은 토큰	필수
`TELEGRAM_ALLOWED_USER_ID`	당신의 숫자형 Telegram ID	필수
`OPENCODE_API_URL`	로컬 OpenCode 서버 URL	`http://localhost:4096`
`OPENCODE_MODEL_PROVIDER` / `OPENCODE_MODEL_ID`	선택된 모델이 없을 때 사용할 기본 모델	`opencode` / `big-pickle`
`BOT_LOCALE`	UI 언어 (`en`, `es`, `zh`, …)	`en`
`MESSAGE_QUEUE` ((`/settings`에서 설정))	에이전트가 바쁠 때 메시지를 큐에 저장	기본적으로 꺼짐
`TASK_LIMIT`	동시에 실행 가능한 스케줄된 작업 최대 수	`10`
`SCHEDULED_TASK_EXECUTION_TIMEOUT_MINUTES`	스케줄된 실행이 실패로 간주되기 전 기다리는 시간	`120`

이 모든 설정은 .env 파일이나 실제 환경 변수로 제공할 수 있으며, 워즈드는 ~/Library/Application Support/opencode-telegram-bot/.env (macOS), %APPDATA%\opencode-telegram-bot\.env (Windows), ~/.config/opencode-telegram-bot/.env (Linux)에 파일을 씁니다.

누구에게 적합한가요?

이미 로컬에서 OpenCode를 사용하는 개발자로, 작업장에서 벗어난 상태에서도 코드 작업을 시작하고 싶은 사람.
빠르고 안전한 원격 인터페이스가 필요한 팀으로, 포트를 공개하거나 완전한 웹 UI를 설정하고 싶지 않은 사람.
Telegram 봇의 상호작용성 (인라인 키보드, 고정 메시지, 음성 → 텍스트 변환 등)을 좋아하는 파워 유저.

제한 사항 / README 참고 사항

봇은 OpenCode 서버가 봇과 동일한 머신에서 실행 중이거나, 설정된 OPENCODE_API_URL로 접근 가능한 경우에만 작동합니다.
스케줄된 작업은 항상 build 에이전트로 실행됩니다. 반복 작업에 대해 다른 에이전트는 현재 지원되지 않습니다.
npm 패키지는 main 브랜치보다 뒤처질 수 있습니다. README에 나와 있는 일부 기능은 최신 릴리스 버전에 포함되어 있지 않을 수 있습니다.
문서 업로드의 최대 파일 크기는 설정 가능 (CODE_FILE_MAX_SIZE_KB)하지만, 이 개요에는 기본값이 명시되어 있지 않습니다.

결론

OpenCode Telegram Bot은 OpenCode AI 코드 생성 플랫폼과 Telegram 사이의 진정한 프로덕션 수준의 브리지입니다. 보안성 높고 이동성이 뛰어난 UI를 제공하여 원격 코드 생성, 세션 관리, 자동화를 가능하게 합니다. 모든 처리는 로컬에서 완료되며, 다국어 지원과 풍부한 Telegram 네이티브 상호작용(인라인 키보드, 고정 상태, 음성 프롬프트, 파일 탐색)을 제공합니다. 이미 OpenCode를 AI 보조 개발에 의존하고 있다면, 이 봇을 통해 그 워크플로우를 스마트폰으로 확장할 수 있으며, 네트워크 포트를 열지 않고도 가능합니다.