English | Deutsch | Français | 日本語 | 한국어 | Nederlands | ไทย | Tiếng Việt | 简体中文 | 繁體中文（香港） | 繁體中文（台灣）
가볍고, 멀티 봇/멀티 세션/멀티태스킹을 지원하는 24/7 AI Coding Agent
Telegram으로 어디서나 로컬 AI Coding Agent를 제어하세요.
Telegram에서 시작한 세션을 나중에 컴퓨터에서 같은 Codex/Copilot CLI 세션으로 이어서 작업할 수 있습니다.
coding-agent-telegram # 또는 ./startup.sh 실행 |
|
→ 원라인 설치:
curl -fsSL https://raw.githubusercontent.com/daocha/coding-agent-telegram/main/install.sh | bash
|
서버를 시작하기 전에 다음을 준비하세요:
|
Openclaw 는 매우 다양한 기능을 제공하고 Pi-Agent 라는 통합 agent loop 도 갖추고 있습니다. 더 폭넓은 use case 를 위한 상당히 종합적인 도구입니다. 저도 Openclaw 를 좋아하고 예전에는 Openclaw 로 coding 했습니다. 하지만 coding 에 한정하면, 내장된 큰 system prompt 와 추가 context 때문에 항상 최선의 선택은 아닙니다. Claude Code / Codex / Copilot 는 coding 에서 더 효율적이고, 더 정확하며, 덜 산만하고, 더 직접적입니다. 이 project 는 의도적으로 단순하며 Codex / Copilot CLI 만 통합합니다. 즉, Codex / Copilot 에 직접 일을 맡길 수 있습니다.
curl -fsSL https://raw.githubusercontent.com/daocha/coding-agent-telegram/main/install.sh | bashpip install coding-agent-telegram
coding-agent-telegramgit clone https://github.com/daocha/coding-agent-telegram
cd coding-agent-telegram
./startup.sh# 방법 A 또는 방법 B를 따르는 경우 다음을 실행
coding-agent-telegram
# 방법 C를 따르는 경우 이것을 다시 실행
./startup.sh이 기능을 사용하면 Telegram 음성 노트에 대해 로컬 Whisper 기반 음성-텍스트 기능을 선택적으로 활성화할 수 있습니다. 오디오 파일은 최대 20 MB 까지만 지원됩니다.
# pip 으로 설치한 경우
coding-agent-telegram-stt-install
# 클론한 저장소에서 실행하는 경우
./install-stt.sh권장 env 설정:
ENABLE_OPENAI_WHISPER_SPEECH_TO_TEXT=true
OPENAI_WHISPER_MODEL=base
OPENAI_WHISPER_TIMEOUT_SECONDS=120
참고:
- Whisper 는 선택한 모델을 처음 사용할 때
~/.cache/whisper로 자동 다운로드합니다. OPENAI_WHISPER_MODEL=turbo를 선택하면large-v3-turbo.pt를 다운로드하는 동안 첫 음성 전사가 시간 초과에 걸릴 가능성이 더 높습니다.- 음성 메시지를 전사한 뒤 봇은 먼저 인식된 텍스트를 Telegram 에 다시 보여주고, 그 다음 에이전트에 전달합니다. 그래서 인식 오류를 확인하기 쉽습니다.
- Telegram을 열고
@BotFather와 대화를 시작합니다. /newbot을 보냅니다.- 다음 항목에 따라 진행합니다:
- 표시 이름
bot으로 끝나는 bot 사용자명
- BotFather가 HTTP API token 을 반환합니다.
- 그 token 을
~/.coding-agent-telegram/.env_coding_agent_telegram의TELEGRAM_BOT_TOKENS에 넣습니다。
가장 확실한 방법은 자신의 bot token 으로 Telegram getUpdates API 를 사용하는 것입니다.
- bot 과 대화를 시작하고
/start같은 메시지를 보냅니다. <BOT_TOKEN>을 바꿔 아래 URL 을 브라우저에서 엽니다:
https://api.telegram.org/bot<BOT_TOKEN>/getUpdates
- JSON 응답에서
chat객체를 찾습니다. - 그 안의 숫자
id값을 복사합니다. - 그 값을
~/.coding-agent-telegram/.env_coding_agent_telegram의ALLOWED_CHAT_IDS에 넣습니다.
참고:
- 개인 채팅의 chat ID 는 보통 양의 정수입니다.
getUpdates결과가 비어 있으면 bot 에 다시 메시지를 보내고 재시도하세요.
현재 이 봇이 받는 메시지:
- 텍스트 메시지
- 사진
ENABLE_OPENAI_WHISPER_SPEECH_TO_TEXT=true로 설정되어 있고 로컬 Whisper 전제 조건이 설치된 경우의 음성 메시지와 오디오 파일- Codex 와 Copilot 은 현재 텍스트와 이미지만 지원하며, 비디오는 지원하지 않습니다
/provider |
새 세션용 제공자를 선택합니다. 선택 내용은 바꿀 때까지 bot/chat 단위로 저장됩니다. |
/project <project_folder> |
현재 프로젝트 폴더를 설정합니다. 폴더가 없으면 앱이 만들고 trusted 로 표시합니다. 이미 존재하지만 아직 untrusted 이면 trust 확인을 요청합니다. |
/branch <new_branch> |
현재 project에서 branch 를 준비하거나 전환합니다. branch 가 이미 있으면 source candidate 로 취급하고, 없으면 repository 의 default branch 를 source candidate 로 사용합니다. |
/branch <origin_branch> <new_branch> |
<origin_branch> 를 source candidate 로 사용해 branch 를 준비하거나 전환합니다. 두 형식 모두 bot 은 실제로 존재하는 source choice 만 보여줍니다: local/<branch>, origin/<branch>. 하나만 있으면 그것만 보이고, 둘 다 없으면 branch source 가 없다고 알립니다. |
/current |
현재 bot/chat 의 활성 세션 을 보여줍니다. |
/new [session_name] |
현재 프로젝트에 새 세션을 만듭니다. 이름을 생략하면 실제 세션 ID를 사용합니다. 제공자, 프로젝트, branch 가 없으면 bot 이 필요한 단계를 안내합니다. |
/switch |
가장 최근 세션을 최신순으로 보여줍니다. 현재 프로젝트의 bot 관리 세션과 로컬 Codex/Copilot CLI 세션이 함께 표시됩니다. |
/switch page <number> |
저장된 세션의 다른 페이지를 보여줍니다. |
/switch <session_id> |
ID 로 특정 세션으로 전환합니다. 로컬 CLI 세션을 선택하면 bot 이 상태에 가져와 이어서 진행합니다. |
/compact |
활성 세션에서 새 compact 세션을 만들고 그쪽으로 전환합니다. |
/commit <git commands> |
활성 세션 project 안에서 검증된 git commit 관련 명령을 실행합니다. ENABLE_COMMIT_COMMAND=true 일 때만 사용할 수 있습니다. 변경성 Git 명령은 trusted project 가 필요합니다. |
/diff |
활성 세션 project 의 변경된 파일 이름을 추적 중인 파일과 추적되지 않은 파일로 나누어 표시합니다. 추적 중인 파일에는 각 파일의 diff 를 여는 inline 버튼이 함께 표시됩니다. |
/pull |
확인 후 활성 세션 브랜치에 대해 origin 에서 pull 합니다. 필요하면 기본 브랜치도 함께 새로고칩니다. |
/push |
현재 활성 세션 에 대해 origin <branch> 를 push 합니다. push 전에 bot 이 확인합니다. |
/abort |
현재 project 의 에이전트 실행 을 중단합니다. 대기 중인 queued question 이 있으면 계속할지 묻습니다. |
CODING_AGENT_TELEGRAM_ENV_FILE |
앱이 특정 env 파일을 사용하도록 지정할 때 사용합니다. |
~/.coding-agent-telegram/.env_coding_agent_telegram |
기본 env 파일 위치입니다. |
./.env_coding_agent_telegram |
이 로컬 파일이 이미 존재할 때만 사용됩니다. |
WORKSPACE_ROOT |
프로젝트 디렉터리를 담는 상위 폴더입니다. |
TELEGRAM_BOT_TOKENS |
쉼표로 구분된 Telegram bot token 목록입니다. |
ALLOWED_CHAT_IDS |
이 bot 사용을 허용할 Telegram 개인 chat ID 목록입니다. |
APP_LOCALE |
공용 bot 메시지와 명령 설명에 사용할 UI locale 입니다. 지원 값: en, de, fr, ja, ko, nl, th, vi, zh-CN, zh-HK, zh-TW. |
CODEX_BIN |
Codex CLI 를 실행할 명령입니다. 기본값: codex. |
COPILOT_BIN |
Copilot CLI 를 실행할 명령입니다. 기본값: copilot. |
CODEX_MODEL |
선택적 Codex model override 입니다. 비워 두면 Codex CLI 기본 model 을 사용합니다. 예: gpt-5.4 OpenAI Codex/OpenAI models |
COPILOT_MODEL |
선택적 Copilot model override 입니다. 비워 두면 Copilot CLI 기본 model 을 사용합니다. 예: gpt-5.4, claude-sonnet-4.6 GitHub Copilot supported models |
CODEX_APPROVAL_POLICY |
Codex 에 전달할 approval mode 입니다. 기본값: never. |
CODEX_SANDBOX_MODE |
Codex 에 전달할 sandbox mode 입니다. 기본값: workspace-write. |
CODEX_SKIP_GIT_REPO_CHECK |
활성화하면 Codex trusted-repo check 를 항상 건너뜁니다. |
ENABLE_COMMIT_COMMAND |
Telegram /commit 명령을 활성화합니다. 기본값: false. |
AGENT_HARD_TIMEOUT_SECONDS |
단일 에이전트 실행 의 하드 타임아웃입니다. 기본값: 0 (비활성화). |
SNAPSHOT_TEXT_FILE_MAX_BYTES |
실행별 diff 스냅샷을 만들 때 bot 이 텍스트로 읽을 최대 파일 크기입니다. 기본값: 200000. |
MAX_TELEGRAM_MESSAGE_LENGTH |
응답을 분할하기 전 최대 메시지 크기입니다. 기본값: 3000. |
ENABLE_SENSITIVE_DIFF_FILTER |
민감한 파일의 diff 를 숨깁니다. 기본값: true. |
ENABLE_SECRET_SCRUB_FILTER |
tokens, keys, .env 값, certificates 등 비밀스러운 출력을 Telegram 으로 보내기 전에 마스킹합니다. 기본값: true (강력 권장). |
SNAPSHOT_INCLUDE_PATH_GLOBS |
일치하는 경로를 diff 에 강제로 포함합니다. 예: .github/*,.profile.test,.profile.prod |
SNAPSHOT_EXCLUDE_PATH_GLOBS |
패키지 기본값 위에 추가 diff 제외 규칙을 더합니다. 예: .*,personal/*,sensitive*.txt 참고: .* 는 숨김 디렉터리 안 파일을 포함한 숨김 경로 에도 매칭됩니다. |
ENABLE_OPENAI_WHISPER_SPEECH_TO_TEXT |
기본값: false. true이면 음성 메시지와 오디오 파일 인식을 활성화합니다. 시스템은 필요한 바이너리나 라이브러리를 확인하고, 누락된 경우 설치를 안내합니다. |
OPENAI_WHISPER_MODEL |
Whisper STT에 사용할 모델입니다. 기본값: base사용 가능한 모델: tiny 약 72 MB, base 약 139 MB, large-v3-turbo 약 1.5 GB모델은 첫 음성 메시지 전송 시 자동으로 다운로드됩니다. 일반적인 사용에는 base를 권장합니다. 더 나은 정확도와 품질이 필요하면 turbo를 시도할 수 있습니다. |
OPENAI_WHISPER_TIMEOUT_SECONDS |
기본값: 120. STT 프로세스 제한 시간입니다. 보통은 충분히 빠르지만 turbo를 선택하면 첫 음성 메시지에서 모델 다운로드로 인해 인터넷 속도에 따라 제한 시간을 초과할 수 있습니다. |
~/.coding-agent-telegram/state.json |
세션 상태의 기본 파일입니다. |
~/.coding-agent-telegram/state.json.bak |
상태 백업 파일입니다. |
~/.coding-agent-telegram/logs |
로그 디렉터리입니다. |
예시:
APP_LOCALE=en
WORKSPACE_ROOT=~/git
TELEGRAM_BOT_TOKENS=bot_token_one
ALLOWED_CHAT_IDS=123456789
DEFAULT_AGENT_PROVIDER=codex
CODEX_BIN=codex
COPILOT_BIN=copilot
CODEX_APPROVAL_POLICY=never
CODEX_SANDBOX_MODE=workspace-write
ENABLE_SENSITIVE_DIFF_FILTER=true
ENABLE_SECRET_SCRUB_FILTER=true세션은 다음 범위로 구분됩니다:
- Telegram bot
- Telegram chat
따라서 같은 Telegram 계정이라도 여러 bot 을 사용하면서 세션이 섞이지 않게 운영할 수 있습니다.
예시:
- Bot A + 내 chat -> backend 작업
- Bot B + 내 chat -> frontend 작업
- Bot C + 내 chat -> infra 작업
활성 세션 은 다음에도 연결됩니다:
- 프로젝트 폴더
- 제공자
- 가능할 경우 branch 이름
각 세션에 저장되는 내용
- 세션 이름
- 프로젝트 폴더
- branch 이름
- 제공자
- timestamps
- 해당 bot/chat 범위의 활성 세션 선택
동시에 실행될 수 있는 에이전트 실행 은 프로젝트 폴더 당 하나뿐입니다. 어떤 chat 이나 Telegram bot 이 시작했는지는 관계없습니다.
- 프로젝트가 사용 중: 그 workspace 에 이미 에이전트 실행 이 있는 상태
- 에이전트가 사용 중: 그 하나의 run 이 현재 요청을 아직 처리 중인 상태
두 agent 가 같은 workspace 에 동시에 쓰지 않도록 bot 이 이 제한을 강제합니다. 충돌하는 수정과 데이터 손상 가능성을 줄이기 위함입니다.
같은 project 에서 이미 agent 가 실행 중이면 bot 은 즉시 다음과 같이 응답합니다:
⏳ 이 project 에서는 이미 agent 가 실행 중입니다. 끝날 때까지 기다려 주세요.
lock 은 디스크가 아니라 메모리에만 유지되므로 agent 가 끝나거나 실패하거나 server 가 재시작되면 자동으로 해제됩니다.
현재 project 에 이미 에이전트 실행 이 있으면, 이후의 텍스트 메시지는 거절되지 않고 queue 됩니다.
- 새 질문은 디스크의 queued-questions file 에 추가됩니다
- 현재 agent 는 이전 요청을 계속 처리합니다
- run 이 정상적으로 끝나면 bot 이 대기 중인 질문 를 자동으로 처리하기 시작합니다
현재 run 이 abort 되었고 대기 중인 질문 가 남아 있으면 자동으로 계속하지 않습니다. 남은 질문을 계속 처리할지, 묶어서 할지, 하나씩 할지를 bot 이 묻습니다.
각 에이전트 실행 동안 bot 은 project 의 가벼운 실행 전후 스냅샷 도 만들어 변경 파일 요약과 diff 를 Telegram 으로 보낼 수 있게 합니다. 이 스냅샷 은 Codex 나 Copilot 이 아니라 bot 앱 자체가 만듭니다.
Snapshot 참고 사항:
- app 은 run 전후에 프로젝트 디렉터리 를 순회합니다
- 일반 텍스트 파일은 git head diff 보다 run 별 스냅샷 diff 를 우선합니다
- 일반적인 의존성, 캐시, 런타임 디렉터리 도 건너뜁니다
- binary 파일 과
SNAPSHOT_TEXT_FILE_MAX_BYTES보다 큰 파일 은 텍스트로 읽지 않습니다 - 매우 큰 project 에서는 이 추가 스캔으로 I/O 와 memory 부담이 커질 수 있습니다
- 스냅샷 이 파일 을 텍스트로 표현할 수 없으면 가능할 때
git diff로 fallback 합니다 - 큰 파일 이나 비텍스트 파일 은 diff 를 생략하고 짧은 안내로 대체할 수 있습니다
Snapshot 제외 규칙은 패키지 resource 에 있습니다:
src/coding_agent_telegram/resources/snapshot_excluded_dir_names.txtsrc/coding_agent_telegram/resources/snapshot_excluded_dir_globs.txtsrc/coding_agent_telegram/resources/snapshot_excluded_file_globs.txt
설치된 패키지 를 수정하지 않고 환경 파일 에서 기본값을 덮어쓸 수 있습니다:
-
SNAPSHOT_INCLUDE_PATH_GLOBS일치하는 path 를 diff 에 강제로 포함합니다. 예:.github/*,.profile.test,.profile.prod -
SNAPSHOT_EXCLUDE_PATH_GLOBS패키지 기본값 위에 추가 diff 제외를 더합니다. 예:.*,personal/*,sensitive*.txt참고:.*는 숨김 디렉터리 안의 파일을 포함한 숨김 경로 와도 일치합니다.
include 와 exclude 가 모두 맞으면 include 가 우선합니다.
bot 은 project 와 branch 를 하나의 묶음으로 다룹니다.
- project 를 선택해도 관련 없는 branch 를 조용히 선택하지 않습니다
- branch 가 필요하면 bot 이 직접 선택을 요청합니다
- 세션 관련 메시지에서 branch 정보를 보여줄 때는 프로젝트와 branch 를 함께 표시합니다
branch 를 만들거나 바꿀 때 bot 은 source 를 명시적으로 안내합니다:
local/<branch>: local branch 를 source 로 사용origin/<branch>: remote branch 에서 먼저 업데이트한 뒤 전환
저장된 세션 branch 와 현재 repository branch 가 다르면 bot 은 그대로 진행하지 않습니다. 어떤 branch 를 쓸지 물어봅니다:
- 저장된 세션 branch 사용
- 현재 repository branch 사용
원하는 source branch 가 없으면 raw Git error 대신 default branch 와 current branch 를 기반으로 fallback source 를 제안합니다.
- 기존 folder 는
CODEX_SKIP_GIT_REPO_CHECK를 따릅니다 /project <name>로 만든 folder 는 이 app 이 trusted 로 표시합니다/project <name>로 선택한 기존 folder 는 Telegram prompt 에서 trust 를 확인하기 전까지 untrusted 로 남습니다- 따라서 새로 만든 프로젝트 폴더 는 바로 사용할 수 있습니다
/commit은ENABLE_COMMIT_COMMAND로 완전히 비활성화할 수 있습니다- 변경을 일으키는
/commit작업은 trusted project 에서만 허용됩니다
log 는 stdout 과 회전하는 로그 파일 양쪽에 기록됩니다:
~/.coding-agent-telegram/logs(10 MB 에서 회전, 3개 백업 유지)
참고: terminal 을 보면서 동시에 로그 파일 을 tail 하면 각 메시지가 두 번 보입니다. 정상 동작입니다. 둘 중 하나만 보세요.
자주 기록되는 이벤트
- bot 시작과 polling 시작
- project 선택
- 세션 생성
- 세션 전환
- 활성 세션 표시
- 일반 run 실행 (잘린 prompt 가 포함된 audit log line 포함)
- resume 실패 후 세션 교체
- warning 과 runtime error
-
src/coding_agent_telegram/메인 애플리케이션 코드 -
tests/테스트 스위트 -
startup.sh로컬 bootstrap / 시작 진입점 -
src/coding_agent_telegram/resources/.env.examplerepo 시작과 package 설치에서 모두 사용하는 canonical environment template -
pyproject.toml패키징 및 의존성 설정
package version 은 Git tag 에서 파생됩니다.
- TestPyPI/testing:
v2026.3.26.dev1 - PyPI prerelease:
v2026.3.26rc1 - PyPI stable:
v2026.3.26
- 이 프로젝트는 자기 머신에서 agent 를 로컬로 실행하는 사용자를 위해 설계되었습니다.
- Telegram bot 은 제어 인터페이스이지 실제 실행 환경은 아닙니다.
- 여러 bot 을 사용해도 하나의 server process 로 모두 관리할 수 있습니다.