claude-telegram-bot 0.3.40 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,326 @@
+# Changelog
+
+## [0.4.0] - 2026-07-10
+### Added
+- `config.json`의 `provider`로 Claude 또는 Codex를 텔레그램 봇의 메인 실행자로 선택할 수 있다.
+- `ctb <config> --provider codex`가 `state.codexSessionId`를 읽어 대화형 `codex resume` 세션을 실행한다.
+- `/provider`로 현재 Telegram provider를 확인하고 `/provider claude`, `/provider codex`로 state override를
+  저장하거나 `/provider default`로 config 기본값을 복원할 수 있다. config 파일은 수정하지 않으며,
+  Claude와 Codex의 세션·모델 override는 각각 보존된다.
+- README에 마지막으로 함께 검증한 Claude Code, Codex CLI, Ollama 버전과 호환성 확인 절차를 기록했다.
+- `/status`에서 봇 호스트에 실제 설치된 세 CLI 버전을 함께 표시한다.
+- 기존 Codex 폴백 재설계 — Claude 레이트 리밋·크레딧 부족 시 `"codexFallback": true`이면 reserve 큐로 넘기기 전에
+  `codex exec`를 실행한다. Codex 세션은 `state.codexSessionId`에 별도로 저장하고 이후
+  `codex exec resume <세션ID>`로 이어간다.
+- Claude와 Codex 세션은 서로 호환되지 않으므로, 성공한 Codex 폴백 내용을
+  `.claude-bot/codex-handoff.md`에 누적하고 이후 Claude 호출의 시스템 프롬프트에 최근 handoff를 주입한다.
+### Changed
+- minor 버전을 `0.4.0`으로 올렸다.
+- 한도 초과 처리 순서 변경: Codex 폴백 성공 시 `/reserve` 자동 재시도를 예약하지 않고, Codex가 꺼져 있거나
+  실패했을 때만 기존 Ollama 폴백/ reserve 흐름으로 내려간다.
+- 일반 메시지, 첨부 파일, 예약 작업과 cron 자연어 해석이 선택된 provider를 사용한다. `/plan`, `/compact`,
+  자동 compact는 Claude provider에서만 동작한다.
+- `/status`가 활성 provider에 맞는 모델·세션·fallback 상태를 표시하고 세 CLI 버전을 함께 확인한다.
+- Codex fallback 응답 머리말을 짧은 `Codex fallback`/`Codex 폴백` 표시로 줄였다.
+- 로컬 lock 안내에서 특정 provider를 뜻하는 `ctb claude` 표현을 중립적인 `ctb`로 변경했다.
+- 기본 설정 예시의 Claude 권한을 `bypassPermissions`에서 `acceptEdits`로 낮췄다.
+
+## [0.3.41] - 2026-07-09
+### Changed
+- Ollama 폴백이 이제 **대화 맥락을 이어받는다** — 기존에는 `localhost:11434/api/chat` HTTP API를
+  직접 호출해 직전 프롬프트 1개만 단발로 처리했고, 헤더에도 "세션은 이어지지 않아요"라고 안내했음.
+  이제 `ollama launch claude --model <m> --yes -- … --resume <세션ID>` 로 **Claude Code CLI 자체를
+  로컬 모델로 구동**해, 폴백·`/ollama` 모드 응답이 Claude와 나누던 대화 스레드를 이어감
+  - 반환된 `session_id`를 `state.sessionId`에 저장해 다음 턴까지 체이닝
+  - 기본 모델 `phi3:mini` → `qwen3.5:4b` (실제 세션 resume 테스트로 검증된 모델)
+  - config 옵션 추가: `ollamaBin`(실행 파일 경로), `ollamaTimeout`(응답 대기 ms, 기본 360000 —
+    로컬 4B 모델 콜드스타트가 첫 응답까지 수 분 걸릴 수 있어 넉넉히 설정)
+  - ⚠️ 완전한 세션 승계가 아니라 **최선 노력(best-effort)**임을 문서에 명시. 로컬 모델의 런타임
+    컨텍스트 창(`num_ctx`)은 Ollama 기본값이 ~4K라 긴 Claude 세션(관측상 ~15K)은 잘려 들어감.
+    `Modelfile`로 `num_ctx`를 키운 변형 모델을 만들어 `ollamaModel`로 지정하면 완화되지만, KV 캐시가
+    RAM을 잡아먹으므로 크기는 머신에 맞춰야 함 — 8GB 머신에선 ~6K가 안전 상한(32K는 스왑으로 먹통).
+    README(영/국문)의 `ollamaModel` 항목과 Ollama 폴백 설명에 관련 안내·한계 추가
+  - 폴백 포지셔닝 정직화: 작은 로컬 모델은 코딩·도구 호출을 Claude처럼 못 하므로
+    "완전한 코딩 대체재"가 아니라 **경량 텍스트 조수**로 명시. 잘하는 역할(Claude 복귀 후
+    시킬 요청을 미리 정리·초안 작성, 요약, 메모 정리)을 안내로 추가
+### Fixed
+- launchd로 뜬 봇에서 Ollama 폴백이 `spawn ollama ENOENT`로 실패하던 문제 — launchd 데몬은
+  로그인 셸을 거치지 않아 `.zshrc`/`brew shellenv`가 설정한 PATH(`/opt/homebrew/bin` 등)를
+  상속받지 못함(`claudeBin`과 동일 원인). `ollamaBin` 미지정 시 흔한 Homebrew/시스템 설치
+  경로를 자동으로 탐색하도록 수정
+
+## [0.3.40] - 2026-07-06
+### Fixed
+- `/status`가 npm에 아직 배포되지 않은 로컬 버전을 npm 레지스트리의 구버전과 비교해
+  실제로는 최신인데도 "업데이트 있음"처럼 `버전: 0.3.39 → 0.3.36 ✨`로 잘못 표시하던 버그
+  - 버전 문자열이 다르기만 하면 화살표를 붙였고, 어느 쪽이 더 최신인지는 비교하지 않았음
+  - 이미 있던 `isNewer()` semver 비교 함수를 사용하도록 수정 — 진짜로 더 최신 버전이 있을 때만 화살표 표시
+
+## [0.3.39] - 2026-07-06
+### Added
+- `/autocompact` 명령어 — 자동 컴팩션 토큰 임계값(`autoCompactThreshold`)을 런타임에 확인·변경
+  - `/autocompact` — 현재 임계값 확인
+  - `/autocompact <숫자>` — 임계값 변경 (state에 저장, 재시작 후에도 유지)
+  - `/autocompact off` — 자동 컴팩션 비활성화 (`0`으로 설정)
+  - `/autocompact default` — config.json의 값(또는 기본값 100000)으로 초기화
+  - 기존에는 config.json을 직접 수정하고 봇을 재시작해야만 값을 바꿀 수 있었음
+
+## [0.3.38] - 2026-07-04
+### Fixed
+- 봇이 busy 상태일 때 사진(첨부)이 포함된 메시지가 연달아 들어오면, 대기열을 합치는 과정에서
+  마지막 메시지를 제외한 앞선 메시지들의 사진이 통째로 사라지던 버그
+  - `drainQueue()`가 텍스트/캡션만 번호 붙여 병합하고 `{...group[group.length-1].msg, ...}`로
+    마지막 메시지 필드만 남겨, 먼저 온 사진의 `photo`/`_mediaGroup`이 유실됨
+  - 큐에 쌓인 모든 메시지의 첨부(사진/문서/음성/영상)를 순서대로 모아 `_mediaGroup`으로
+    합치도록 수정 — Claude가 먼저 온 사진도 모두 확인 가능
+
+## [0.3.37] - 2026-07-04
+### Fixed
+- `busy` 플래그 교착(deadlock) 버그 — `/cron add`, `/plan` 승인 실행, 일반 메시지 처리 3곳에서
+  `busy = true` 직후의 `await tg("sendChatAction", ...)` 호출이 `try/catch` 밖에 있어,
+  일시적 네트워크 오류로 이 호출이 실패하면 `busy`가 영영 `true`로 남아버리는 문제
+  - `/stop`은 `currentChild`가 없어 "실행 중인 작업 없음"이라 답하지만, 새 메시지는 전부
+    무한 대기열에만 쌓이는 모순된 멈춤 상태가 발생
+  - `sendChatAction` 호출을 각 `try` 블록 안으로 이동해, 실패해도 기존 `catch`/`finally`가
+    `busy`/`currentTyping`을 정상적으로 초기화하도록 수정
+
+## [0.3.36] - 2026-07-03
+### Fixed
+- `/plan`(0.3.35)에서 `send()`가 제너레이터 `chunks()`를 배열처럼 `.length`로 인덱싱해
+  모든 메시지가 무응답으로 사라지던 버그
+  - `chunks()`는 `function*`이라 `.length`가 `undefined` → 루프 조건이 항상 false로 평가되어
+    본문이 한 번도 실행되지 않음 (예외도 로그도 없이 조용히 실패)
+  - `const cs = chunks(text)` → `const cs = [...chunks(text)]`로 배열 변환하여 수정
+  - 자세한 원인 분석: `docs/incidents/2026-07-03-plan-send-silent-failure.md`
+
+## [0.3.35] - 2026-06-27
+### Added
+- `/plan <요청>` — Plan Mode
+  - 봇의 `permissionMode` 설정과 무관하게 강제로 `plan`(읽기 전용) 모드로 1회 실행
+  - 계획 내용과 함께 텔레그램 인라인 버튼(✅ 진행 / ❌ 취소) 전송
+  - **진행** 클릭 시 같은 세션을 봇의 실제 `permissionMode`로 이어서 계획 실행
+  - **취소** 클릭 시 세션 변경 없음 (애초에 plan 모드라 편집 자체가 없었음)
+  - `/new`로 세션이 바뀌면 대기 중인 승인은 자동 만료
+  - 헤드리스 `--print` 모드는 진짜 `ExitPlanMode` 툴 인터셉트(중간 정지)가 불가능해, plan 실행 → 승인 → resume 실행의 2단계 방식으로 구현
+
+## [0.3.34] - 2026-06-27
+### Added
+- 커스텀 명령어 — `config.json`의 `commands` 필드로 프로젝트별 `/명령어` 정의
+  - `run`: 쉘 명령어 실행, 출력을 텔레그램으로 전송
+  - `/cmd arg1 arg2` 형태로 인자 전달 가능
+  - Telegram `/` 자동완성 메뉴에 자동 등록
+  - Claude 와 독립 실행 (busy 상태와 무관)
+  - 60초 타임아웃, 4000자 초과 시 truncate
+
+```json
+"commands": {
+  "deploy": { "run": "npm run deploy", "description": "프로젝트 배포" },
+  "logs":   { "run": "tail -n 50 ./app.log", "description": "최근 로그" }
+}
+```
+
+## [0.3.33] - 2026-06-27
+### Fixed
+- 0.3.31 에서 `-p`를 args 맨 앞에 두어 `--output-format`이 `-p`의 값으로 먹히는 버그
+  - 모든 `--flag value` 옵션 뒤에 `-p -- <prompt>` 배치로 수정 (터미널 테스트 검증 순서)
+
+## [0.3.32] - 2026-06-27
+### Added
+- 자동 컴팩션 — `cache_read_input_tokens` 가 임계값 초과 시 `/compact` 자동 실행
+  - 기본값 100,000 토큰 (`config.json` 에 `"autoCompactThreshold": 100000` 으로 조정 가능)
+  - 0 으로 설정하면 비활성화
+  - 압축 후 텔레그램으로 알림 전송
+
+## [0.3.31] - 2026-06-26
+### Fixed
+- `-`로 시작하는 메시지가 여전히 옵션으로 오해되던 문제 (0.3.28~0.3.30 미해결)
+  - `-p<prompt>` 인라인 묶기는 claude CLI 파서가 미지원 (`-p` + `-prompt` 로 분리)
+  - 프롬프트를 모든 옵션 뒤 `--` 구분자 다음에 위치 인자로 전달하도록 변경
+
+## [0.3.30] - 2026-06-26
+### Fixed
+- `-p <prompt>` → `-p<prompt>` (붙여쓰기) 방식으로 변경 (실패 — 0.3.31에서 재수정)
+
+## [0.3.29] - 2026-06-26
+### Fixed
+- 구버전 `claude` CLI에서 `--print` 미지원으로 발생하는 "unknown option" 에러
+  - 시작 시 `claude --help` 로 지원 여부 탐지 → 구버전이면 `-p <prompt>` 자동 폴백
+
+## [0.3.28] - 2026-06-25
+### Fixed
+- `-`로 시작하는 메시지(예: `-9038502는 잔액이고…`)가 Claude CLI 옵션으로 오해되는 문제
+  - `-p <prompt>` → `--print=<prompt>` 방식으로 변경
+
+## [0.3.26] - 2026-06-24
+### Fixed
+- `"session limit"` 에러 미감지 문제 — `isFallbackError` / `classifyClaudeError` 에 추가
+- `"resets 7:20pm"` 형식 파싱 실패 — `parseResetTime` regex에서 `at` 없이도 시간 추출
+### Changed
+- 레이트리밋 에러 시 메시지를 큐에 보관 후 리셋 시간에 자동 재시도 (busy 큐와 동일 메커니즘)
+  - 제한 중 추가로 보내는 메시지도 큐에 쌓임
+  - `/reserve` → 대기 현황 보기, `/reserve rm` → 큐 전체 취소
+
+## [0.3.25] - 2026-06-23
+### Added
+- `/ollama` 명령어 — Ollama 채팅 모드 수동 토글
+  - 켜는 동안 메시지는 Claude 없이 Ollama로 직접 처리 (Claude 세션은 유지)
+  - 다시 `/ollama` 로 끄면 Claude 모드로 복귀
+### Changed
+- Ollama 요청을 `/api/generate` → `/api/chat` 으로 전환
+  - 시스템 프롬프트 지원: `cfg.persona` + 간결체 instruction 주입
+  - 응답 품질 개선 (특히 작은 모델에서 효과적)
+
+## [0.3.24] - 2026-06-23
+### Fixed
+- ctb 종료 시 요약이 항상 SKIP으로 반환되는 문제 수정
+  - 세션 컴팩션 후 `---ctb:start---` 마커가 묻히는 문제 → 최근 대화 기반 요약으로 변경
+
+## [0.3.23] - 2026-06-23
+### Added
+- 텔레그램 메시지 메타데이터 프롬프트 주입
+  - 포워드 메시지: 출처(유저/채널/숨김) 자동 감지 → `[Forwarded from: ...]` 표기
+  - 리플라이: 원본 메시지 내용(최대 300자) → `[Replying to ...: "..."]` 표기
+
+## [0.3.22] - 2026-06-23
+### Changed
+- Codex 폴백 → Ollama 폴백으로 교체 (fetch 기반, 의존성 0 유지)
+  - config.json에 `"ollamaFallback": true`, `"ollamaModel": "phi3:mini"` 로 설정
+  - Claude 레이트리밋·크레딧 부족 시 로컬 Ollama 모델로 자동 대체
+
+## [0.3.21] - 2026-06-23
+### Added
+- `/testfallback` 명령어 — Codex 폴백 연결을 직접 테스트
+
+## [0.3.20] - 2026-06-23
+### Added
+- Codex 폴백 — Claude 레이트리밋·크레딧 부족 시 OpenAI Codex로 자동 대체 응답
+  - config.json에 `"codexFallback": true` 로 활성화, `codex` CLI가 설치된 경우에만 동작
+  - 응답 앞에 "🌙 Claude가 잠시 쉬고 있어요" 안내 문구 자동 삽입
+
+## [0.3.19] - 2026-06-19
+### Added
+- `/compact` 명령어 — 세션을 유지한 채 컨텍스트를 요약 압축 (`/new` 없이 공간 확보)
+- "Prompt is too long" 에러 감지 → `/compact` 또는 `/new` 안내 메시지로 대체
+
+## [0.3.18] - 2026-06-19
+### Fixed
+- 같은 이미지를 여러 번 보내면 파일이 덮어써지는 버그 — 파일명에 타임스탬프 추가 (`tg-<ts>-<id>.<ext>`)
+
+## [0.3.17] - 2026-06-18
+### Fixed
+- `/remember` 메모리가 persona에 덮어쓰여 무시되는 문제 — 메모리를 시스템 프롬프트 맨 앞에 배치하고 헤더를 `## RULES (must follow before anything else)` 로 강화
+
+## [0.3.16] - 2026-06-18
+### Changed
+- `allowedChatId` 를 배열로도 지정 가능 — `["chatId1", "chatId2"]` 형태로 여러 사용자 허용 (기존 문자열 형태 하위 호환)
+- cron 결과·업데이트 알림을 모든 허용 채팅에 브로드캐스트
+
+## [0.3.15] - 2026-06-17
+### Added
+- `/reserve` 명령어 — 사용 한도 초과 시 리셋 시점에 재시도 예약, `/reserve <다른 메시지>` 로 내용 변경, `/reserve rm` 으로 취소
+
+## [0.3.14] - 2026-06-17
+### Added
+- 여러 이미지 동시 전송 지원 — `media_group_id` 감지 후 1초 대기, 그룹 내 모든 이미지를 한 번에 Claude에 전달
+
+## [0.3.13] - 2026-06-16
+### Added
+- `ctb` 세션 시작 시 `---ctb:start---` 마커 삽입 — 종료 요약이 텔레그램 이전 대화를 제외하고 터미널 세션 작업만 요약
+
+## [0.3.12] - 2026-06-16
+### Fixed
+- `ctb` 종료 알림 fetch 실패 — `dns.setDefaultResultOrder("ipv4first")` 추가로 IPv6 우선 시도 문제 해결
+- `ctb` 알림 언어 — `cfg.lang` 미설정 시 `$LANG` 환경변수로 폴백
+- `ctb` 알림 메시지에 `[터미널]` / `[local]` 레이블 추가로 텔레그램 채팅 응답과 구분
+
+## [0.3.11] - 2026-06-15
+### Fixed
+- `ctb` 종료 요약을 config `lang` 에 맞는 언어로 전송 (ko 설정 시 한국어)
+
+## [0.3.10] - 2026-06-15
+### Fixed
+- `ctb` Ctrl+C 종료 시에도 텔레그램 요약 알림 전송
+- 세션 종료 요약을 10단어 이내 짧은 구문으로 제한
+
+## [0.3.9] - 2026-06-15
+### Added
+- 업데이트 자동 감지 — 시작 시 24h 주기로 npm 최신 버전 확인, 새 버전이 있으면 버전당 1회 텔레그램 알림
+
+## [0.3.8] - 2026-06-15
+### Added
+- `ctb` 세션 종료 시 텔레그램으로 한 줄 요약 자동 전송 — config 에 `"ctbNotify": false` 로 비활성화 가능
+
+## [0.3.7] - 2026-06-15
+### Fixed
+- Claude 에러 분류를 JSON 경로(`is_error: true`)에도 적용 — 0.3.6 에서 비정상 종료만 처리하던 것을 JSON 응답 에러까지 확장
+
+## [0.3.6] - 2026-06-14
+### Fixed
+- Claude 에러 메시지 분류 — 크레딧 부족·레이트리밋·서버 과부하·컨텍스트 초과를 감지해 날 것 에러 대신 안내 메시지 표시
+
+## [0.3.5] - 2026-06-14
+### Added
+- `/status` 에 npm 최신 버전 표시 — 업데이트가 있으면 `0.3.4 → 0.3.5 ✨` 형식으로 알림
+
+## [0.3.4] - 2026-06-14
+### Fixed
+- `/stop` 이 작업 중에 무시되는 버그 수정 — 폴링 루프의 `await handle()` 로 인해 `/stop` 메시지가 현재 작업 완료까지 처리되지 않던 문제
+
+## [0.3.3] - 2026-06-13
+### Fixed
+- `ctb` 전역 설치 시 세션 연결 안 되는 문제 — config 탐색 순서를 `cwd` 우선으로 변경
+
+## [0.3.2] - 2026-06-13
+### Fixed
+- 한국어 `/help` 텍스트에서 `/cron` 줄 중복 제거
+
+## [0.3.1] - 2026-06-13
+### Added
+- 퍼시스턴트 메모리 — `/remember <내용>` 으로 저장, `/new` 후에도 유지, 매 대화에 자동 주입
+- `/memory` — 메모리 확인 · `/memory clear` 로 삭제
+- `init` 기본 파일명을 `mybot.json` 으로 변경
+
+## [0.3.0] - 2026-06-12
+### Added
+- `/stop` — 진행 중인 작업 중단 · `--reset` 옵션으로 세션 롤백
+- 메시지 큐 — busy 중 수신된 메시지를 대기 후 자동 처리, 여러 개면 시간 정보와 함께 일괄 병합
+- `init` 파일명 직접 지정 가능 (`ctb init mybot.json`)
+
+## [0.2.7] - 2026-06-11
+### Added
+- `fable` 모델을 MODEL_SUGGESTIONS 및 모델 권유 프롬프트에 추가
+
+## [0.2.6] - 2026-06-11
+### Added
+- 현재 모델을 시스템 프롬프트에 주입 — Claude가 질문 난이도에 따라 상위 모델 전환 스스로 권유
+
+## [0.2.5] - 2026-06-10
+### Added
+- `/model` — 런타임 모델 보기·전환 (`/model sonnet`, `/model default` 등)
+
+## [0.2.4] - 2026-06-09
+### Changed
+- 데이터(state·attachments)를 `.claude-bot/` 숨김 폴더로 이동, 기존 데이터 자동 이주
+
+## [0.2.3] - 2026-06-08
+### Added
+- `/status` — 봇 이름·버전·모델·세션·예약 작업·프로젝트 경로 표시
+
+## [0.2.1] - 2026-06-07
+### Added
+- i18n — 영어 기본 + 한국어, `from.language_code` 로 사용자별 자동 판별
+- `/` 명령 자동완성 메뉴 등록 (`setMyCommands`)
+- 한 줄 인라인 코드를 `<pre>` 블록으로 렌더링 (텔레그램 복사 버튼)
+
+## [0.2.0] - 2026-06-06
+### Added
+- `ctb` CLI — 로컬 터미널에서 텔레그램 봇 세션 공유
+- `/cron` — 예약 작업 자연어 추가·삭제·목록
+- `/restart` — 문법 검사 후 안전 재시작
+- 조용한 예약 작업 — 출력이 비었거나 `SKIP` 이면 전송 안 함
+
+## [0.1.0] - 2026-06-01
+### Added
+- 최초 릴리스 — Telegram → `claude -p` 헤드리스 브리지, zero-dependency, 단일 파일
+- 파일 첨부 지원, HTML 포맷팅, IPv4 우선 설정
+- `launchd` 데몬 예시 (`com.claudebot.example.plist`)

package/README.ko.md

@@ -6,19 +6,26 @@
 [![npm downloads](https://img.shields.io/npm/dm/claude-telegram-bot.svg)](https://www.npmjs.com/package/claude-telegram-bot)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-텔레그램으로 Claude Code를 — 어디서든, 어떤 기기에서도.
+텔레그램으로 Claude Code와 Codex를 — 어디서든, 어떤 기기에서도.
 
-텔레그램으로 메시지를 보내면, 집이나 서버에 켜둔 Claude Code가 작업하고 결과를 다시 텔레그램으로 돌려주는 봇입니다.
+텔레그램 메시지를 집이나 서버의 코딩 agent가 처리하고 결과를 다시 채팅으로 보내는, 런타임 의존성 없는 백그라운드 봇입니다.
 
-```
-[나] → 텔레그램 → bot.mjs → claude -p (작업 폴더) → 결과 → 텔레그램
+```text
+[나] → 텔레그램 → bot.mjs
+                    ├─ Claude provider → state.sessionId
+                    ├─ Codex provider  → state.codexSessionId
+                    └─ Ollama 모드·폴백
+                             ↓
+                 결과 → 텔레그램
+
+Claude 한도 → Codex 폴백 → codex-handoff.md → 다음 Claude 호출
 ```
 
 ## 왜 만들었나
 
 자리를 비운 사이에도 폰으로 빌드를 돌려보거나 간단한 수정을 맡기고 싶을 때가 있습니다. 그렇다고 외부에서 데스크톱에 원격 접속해서 터미널을 여는 건 번거롭죠.
 
-텔레그램 봇이면 충분합니다. 메시지를 보내면 집(또는 개인 서버)의 `claude`가 헤드리스로 돌아 작업하고, 답을 채팅으로 보내줍니다. 별도 웹 대시보드도, 추가 서버도 없습니다. 파일 하나(`bot.mjs`)와 설정 파일 하나가 전부입니다.
+텔레그램 봇이면 충분합니다. 메시지를 보내면 집(또는 개인 서버)의 선택된 provider가 헤드리스로 작업하고 답을 채팅으로 보냅니다. 별도 웹 대시보드나 데이터베이스는 없습니다.
 
 ## 이런 분께
 
@@ -27,13 +34,14 @@
 - 맥미니나 홈서버에 띄워두고 어디서든 접속하고 싶은 분
 - 거창한 셀프호스트 구성 없이 텔레그램만으로 끝내고 싶은 분
 
-OpenClaw처럼 웹 UI까지 갖춘 구성을 써봤다면, 이 프로젝트는 그 반대편이라고 보면 됩니다. 대시보드도 데이터베이스도 없고, 이미 설치해 로그인해 둔 `claude` CLI를 그대로 불러 쓰는 게 전부입니다. 설정과 코드를 30초면 훑어볼 수 있습니다.
+OpenClaw처럼 웹 UI까지 갖춘 구성을 써봤다면, 이 프로젝트는 그 반대편이라고 보면 됩니다. 대시보드도 데이터베이스도 없고, 이미 설치해 로그인해 둔 Claude 또는 Codex CLI를 그대로 불러 씁니다.
 
 ## 동작 방식
 
 - 텔레그램 봇 API를 롱폴링으로 받습니다.
-- 메시지가 오면 작업 폴더(`projectDir`)에서 `claude -p`(헤드리스 모드)를 실행합니다.
-- 세션은 `--resume`으로 이어지므로, 봇을 재시작해도 대화 맥락이 유지됩니다.
+- 메시지가 오면 작업 폴더(`projectDir`)에서 선택된 Claude 또는 Codex provider를 실행합니다.
+- 두 provider는 별도 세션으로 이어지므로, 전환하거나 봇을 재시작해도 각각의 맥락이 유지됩니다.
+- Claude 한도 도달 시 Codex 폴백을 쓸 수 있고, 처리 내용은 Claude용 handoff에 기록됩니다.
 - 의존성이 없습니다. Node 18+ 내장 기능(`fetch`, `child_process`)만 씁니다.
 
 ## 다른 도구와 비교
@@ -43,7 +51,7 @@ OpenClaw처럼 웹 UI까지 갖춘 구성을 써봤다면, 이 프로젝트는
 | | 이 봇 | [공식 Claude Code Channels](https://code.claude.com/docs/en/channels) | [claude-code-telegram](https://github.com/RichardAtCT/claude-code-telegram) |
 |---|---|---|---|
 | 런타임 | Node 내장만 | Bun + MCP 플러그인 | Python 3.11+ |
-| 실행 모델 | 메시지마다 `claude -p` | 떠 있는 세션에 이벤트 push | Claude SDK / CLI |
+| 실행 모델 | 메시지마다 Claude 또는 Codex 헤드리스 프로세스 | 떠 있는 세션에 이벤트 push | Claude SDK / CLI |
 | 상시 가동 | 백그라운드 데몬 | 인터랙티브 세션 유지 | 서비스 / 데몬 |
 | 권한 차등 페르소나 | 가능 | 불가 | 불가 |
 | 작업별 권한 승인 버튼 | 없음 | 있음 | 일부 |
@@ -58,8 +66,9 @@ OpenClaw처럼 웹 UI까지 갖춘 구성을 써봤다면, 이 프로젝트는
 ## 요구 사항
 
 - Node.js 18 이상 (내장 `fetch` 사용)
-- `claude` CLI 설치 및 로그인 (봇은 이 인증을 그대로 씁니다)
 - 텔레그램 봇 토큰 ([@BotFather](https://t.me/BotFather)에서 발급)
+- 최소 한 provider: Claude CLI 또는 Codex CLI 설치 및 로그인
+- 선택 사항: Codex 폴백용 Codex CLI, Ollama 모드·폴백용 Ollama와 로컬 모델
 
 상시 가동 예시는 macOS의 launchd 기준입니다. 리눅스라면 systemd나 pm2로 같은 구성을 만들면 됩니다.
 
@@ -93,25 +102,65 @@ claude-telegram-bot ~/botconfigs/myproj/mybot.json
 
 `mybot.json`(또는 사용 중인 config 파일)의 키는 다음과 같습니다.
 
+### 호환성
+
+이 봇은 CLI 옵션과 기계 판독용 출력 형식에 의존하므로 각 도구의 업데이트에 영향을 받을 수 있습니다.
+아래는 2026-07-10에 호환성 기준으로 기록한 개발 환경 버전이며 강제 고정 버전이나 모든 경로의 통과를
+보장하는 표는 아닙니다. 봇 호스트에 실제 설치된 버전은 `/status`에서 확인할 수 있습니다.
+
+| CLI | 기록 버전 | 관련 연동 경로 |
+|---|---:|---|
+| Claude Code | `2.1.206` | JSON 출력, 세션 resume, 권한 모드 |
+| Codex CLI | `0.144.1` | `exec`, `exec resume`, JSONL 이벤트, workspace sandbox |
+| Ollama | `0.31.1` | `ollama launch claude`, 모델 선택, 세션 handoff |
+
+CLI를 업데이트한 뒤에는 무인 실행에 맡기기 전에 `/testfallback`과 일반 Claude 메시지를 각각 확인하세요.
+새 환경의 버전을 기록하고 두 경로를 확인한 뒤 이 표를 갱신하는 것을 권장합니다.
+
+### 설정 키
+
 | 키 | 설명 |
 |---|---|
 | `token` | BotFather에서 받은 봇 토큰 |
 | `allowedChatId` | 처음엔 비워두세요. 봇이 chatId를 알려줍니다 (아래 첫 실행 참고) |
-| `projectDir` | Claude가 작업할 폴더의 절대경로 |
+| `projectDir` | 선택된 provider가 작업할 폴더의 절대경로 |
+| `provider` | (선택) 텔레그램 메시지와 예약 작업의 메인 provider. `"claude"`(기본값) 또는 `"codex"` |
 | `claudeBin` | `which claude` 결과 (절대경로 권장) |
-| `permissionMode` | `plan`(읽기·계획만) / `acceptEdits`(편집 자동 승인) / `bypassPermissions`(쉘 포함 전부 자동) |
-| `model` | 비우면 기본 모델. `opus`, `sonnet` 등. 런타임에 `/model`로 전환 가능(state에 저장) |
+| `permissionMode` | Claude 전용: `plan` / `acceptEdits` / `bypassPermissions` |
+| `model` | Claude 모델. 비우면 CLI 기본값이며 Claude 활성 상태에서 `/model`로 전환 가능 |
 | `lang` | (선택) UI 언어. 비우면 사용자별 자동 판별(기본 영어, 텔레그램이 한국어면 한국어). `"en"`/`"ko"`로 고정 가능 |
 | `name` | (선택) `/help`에 표시되는 봇 이름. 여러 봇 구분용 |
 | `persona` | (선택) 역할 시스템 프롬프트. 페르소나 봇 정의용 |
 | `appendSystemPrompt` | (선택) 기본 "간결하게 답하기" 지침을 직접 덮어쓸 때 |
-| `env` | (선택) `claude` 프로세스에 넘길 환경 변수 |
+| `env` | (선택) provider 프로세스에 넘길 환경 변수 |
 | `schedule` | (선택) 정해진 시각에 프롬프트를 실행하는 cron 작업 — [예약 작업](#예약-작업-cron) 참고 |
 | `commands` | (선택) 쉘 스크립트를 실행하는 커스텀 `/명령어` — [커스텀 명령어](#커스텀-명령어) 참고 |
-| `ollamaFallback` | (선택) `true`로 설정하면 Claude 레이트 리밋·크레딧 부족 시 로컬 Ollama로 자동 대체 |
-| `ollamaModel` | (선택) 폴백에 쓸 Ollama 모델 (기본값: `"phi3:mini"`) |
+| `codexFallback` | (선택) `true`로 설정하면 Claude 레이트 리밋·크레딧 부족 시 Codex를 우선 폴백으로 사용 |
+| `codexBin` | (선택) `codex` 실행 파일 경로. 기본값은 `PATH`의 `"codex"`이며 launchd에서는 절대경로 권장 |
+| `codexModel` | (선택) Codex에 `--model`로 넘길 모델 오버라이드 |
+| `codexSandbox` | (선택) 첫 `codex exec` 세션의 샌드박스 (기본값: `"workspace-write"`) |
+| `codexTimeout` | (선택) Codex 응답을 기다리는 최대 시간(ms). 실패하면 reserve/Ollama로 넘어감 (기본값: `600000`) |
+| `ollamaFallback` | (선택) `true`로 설정하면 Claude 레이트 리밋·크레딧 부족 시 로컬 Ollama를 보조 폴백으로 사용 |
+| `ollamaModel` | (선택) 폴백에 쓸 Ollama 모델 (기본값: `"qwen3.5:4b"`). 세션이 이어받는 맥락의 양은 이 모델의 런타임 컨텍스트 창(`num_ctx`)에 의해 제한됨 — 모델 아키텍처상 최대치와 무관하게 Ollama 기본값은 ~4K라, 긴 Claude 세션에는 부족함. `Modelfile`로 더 큰 창을 구워넣은 변형을 만들어(`FROM qwen3.5:4b` + `PARAMETER num_ctx 6144`, `ollama create qwen3.5:4b-ctx6k -f Modelfile`) 이 값으로 지정할 것. 크기는 RAM에 맞출 것 — 8GB 머신에선 ~6K가 안전 상한이고, 32K는 스왑으로 시스템이 먹통이 됨 |
+| `ollamaBin` | (선택) `ollama` 실행 파일 경로. `/opt/homebrew/bin/ollama`, `/usr/local/bin/ollama`, `/usr/bin/ollama` 순으로 자동 탐색 후 없으면 `PATH`의 `"ollama"` 사용 — launchd로 뜨는 봇은 셸의 `PATH`를 상속받지 못하므로, 다른 경로에 설치했다면 명시적으로 지정할 것 |
+| `ollamaTimeout` | (선택) Ollama 응답을 기다리는 최대 시간(ms) (기본값: `360000` — 로컬 모델은 콜드스타트가 느릴 수 있음) |
 | `autoCompactThreshold` | (선택) 캐시된 입력 토큰이 이 값을 초과하면 컨텍스트 자동 압축 (기본값: `100000`). `0`이면 비활성화. 런타임에 `/autocompact`로 전환 가능(state에 저장) |
 
+같은 config로 로컬 대화형 세션도 실행할 수 있습니다. `ctb mybot.json`은 `config.provider`를 따르고,
+명시적인 옵션은 해당 실행에서만 설정을 덮어씁니다.
+
+```sh
+ctb mybot.json --provider claude
+ctb mybot.json --provider codex
+```
+
+Claude는 `state.sessionId`, Codex는 `state.codexSessionId`를 읽어 `codex resume <세션ID>`로
+재개합니다. 두 provider의 세션은 서로 분리됩니다. `/plan` 승인 흐름은 현재
+`provider: "claude"`에서만 지원하며, 일반 메시지·첨부 파일·예약 작업은 둘 다 지원합니다.
+
+`/provider`는 텔레그램 봇 전용 override를 state에 저장하므로 재시작 후에도 유지되지만 config 파일은
+수정하지 않습니다. 로컬 `ctb`는 계속 `config.provider` 또는 명시적인 `--provider` 옵션을 사용합니다.
+
 `state`와 첨부 파일은 config 파일 옆 **`.claude-bot/` 숨김 폴더**에 저장됩니다(프로젝트 격리). 구버전에서 올리면 첫 시작 때 기존 `state.json`·`attachments/`를 `.claude-bot/`로 **자동 이동**합니다(무손실). 로그는 launchd plist가 가리키는 위치 그대로입니다.
 
 ## 첫 실행
@@ -122,26 +171,42 @@ claude-telegram-bot ~/botconfigs/myproj/mybot.json
    - `테스트 돌려보고 통과하면 커밋하고 push 해줘`
    - `api.ts 에 에러 핸들링 추가해줘`
 
-명령어: `/new`(맥락 초기화) · `/compact`(컨텍스트 압축, 세션 유지) · `/plan <요청>`(계획만 세우고 승인/취소) · `/stop`(작업 중단; `--reset`으로 세션도 롤백) · `/ollama`(Ollama 채팅 모드 토글) · `/cron`(예약 작업 보기·추가·삭제) · `/reserve`(대기 큐 상태 확인 · `/reserve rm`으로 취소) · `/restart`(문법 검사 후 재시작) · `/status`(봇 상태·버전) · `/model`(모델 보기·전환) · `/autocompact`(자동 압축 임계값 보기·설정) · `/id`(채팅 ID 확인) · `/help`(도움말)
+주요 명령어:
+
+| 명령어 | 기능 |
+|---|---|
+| `/provider [claude\|codex\|default]` | 텔레그램 봇 provider 확인·전환 |
+| `/model [이름\|default]` | 활성 provider 모델 확인·전환 |
+| `/new` | 활성 provider의 대화 세션 초기화 |
+| `/plan <요청>` | 계획 작성 후 승인 대기 (Claude 전용) |
+| `/compact` | 현재 컨텍스트 압축 (Claude 전용) |
+| `/stop [--reset]` | 작업 중단, 선택적으로 이전 세션 ID 복원 |
+| `/ollama` · `/testfallback` | 로컬 모드 전환·fallback 연결 테스트 |
+| `/status` | 버전, provider, CLI, 모델, fallback, 세션 상태 확인 |
+| `/remember <내용>` · `/memory` | 영구 메모리 저장·확인 |
+| `/cron` · `/reserve` | 예약 작업·한도 재시도 관리 |
+| `/autocompact` · `/restart` · `/id` · `/help` | 유지관리·도움말 |
 
 > **`/plan <요청>`** 은 봇에 설정된 `permissionMode`와 무관하게 강제로 읽기 전용 plan 모드(편집·쉘 없음)로 요청을 실행하고, 계획 내용과 함께 **✅ 진행 / ❌ 취소** 버튼을 보냅니다. **진행**을 누르면 같은 세션을 봇의 실제 `permissionMode`로 이어서 승인된 계획을 실행하고, **취소**를 누르면 세션은 그대로 유지됩니다. `bypassPermissions` 봇이 뭔가 건드리기 전에 검토 단계를 두고 싶을 때 유용합니다. `/new`로 새 세션을 시작하면 대기 중인 승인은 만료됩니다.
 
-> **`/stop`** 은 실행 중인 Claude 프로세스를 즉시 종료하고 대기 중인 메시지 큐도 비웁니다. `--reset`을 붙이면 세션을 작업 시작 이전 상태로 되돌려 중단된 작업이 대화 맥락에 남지 않습니다.
+> **`/stop`** 은 실행 중인 provider 프로세스를 즉시 종료하고 대기 중인 메시지 큐도 비웁니다. `--reset`을 붙이면 세션을 작업 시작 이전 상태로 되돌려 중단된 작업이 대화 맥락에 남지 않습니다.
 
 > **`/restart`** 는 먼저 `bot.mjs` 에 `node --check` 를 돌려 **문법 오류가 있으면 재시작을 취소**합니다(잘못된 수정이 봇을 크래시 루프에 빠뜨리는 것 방지). 통과하면 프로세스를 종료하고, 다시 띄우는 건 프로세스 관리자에게 맡깁니다. [launchd 설정](#상시-실행-launchd)(`KeepAlive`)이면 바로 동작하고, 관리자 없이 `node bot.mjs` 로만 돌리면 그냥 멈춥니다. 재시작 후 대화 세션은 `state.json` 의 ID로 이어집니다.
 
 ## 사용 메모
 
-- **세션 유지** — 대화는 `--resume`으로 자동으로 이어집니다. 마지막 세션 ID가 `state.json`에 저장되므로 봇을 재시작해도 맥락이 남습니다. 새로 시작하려면 `/new`.
+- **세션 유지** — Claude와 Codex의 세션 ID를 따로 저장합니다. `/provider`로 전환해도 각각의 맥락이 유지되며 `/new`는 활성 provider 세션만 초기화합니다.
 - **메시지 큐** — 작업 중에 새 메시지가 오면 버리지 않고 큐에 쌓아둡니다. 작업이 끝나면 대기 중인 메시지를 모두 하나의 프롬프트로 합쳐서 처리합니다(예: "A 해줘" → "아니다 B 해줘"를 한 번에 처리). `/stop`으로 실행 중인 작업과 큐를 동시에 취소할 수 있습니다.
 - **모델 권유** — 봇이 Claude에게 현재 모델을 알려줍니다. 질문 난이도가 현재 모델 수준을 넘는다고 판단되면 답변 끝에 전환 권유 한 줄이 붙습니다(예: 💡 `/model sonnet`). `/model <이름>`으로 전환(`haiku`, `sonnet`, `opus`, `fable`, 또는 전체 모델 ID) — `state.json`에 저장돼 재시작 후에도 유지됩니다.
-- **한도 초과 큐** — Claude Max / API 레이트 리밋 에러에 리셋 시간이 포함되면, 해당 메시지를 자동으로 큐에 넣고 리셋 시각에 재시도합니다 — 작업 중 큐와 같은 방식입니다. 한도가 걸린 동안 추가로 보내는 메시지도 자동으로 큐에 쌓입니다. `/reserve`로 대기 현황과 리셋 시각 확인, `/reserve rm`으로 큐 전체 취소.
-- **Ollama 폴백** — `"ollamaFallback": true`로 설정하고 `"ollamaModel"`에 로컬 [Ollama](https://ollama.ai) 모델을 지정하면(기본값: `"phi3:mini"`), Claude 레이트 리밋·크레딧 부족 시 자동으로 Ollama로 대체 응답합니다. `/ollama`로 Claude와 관계없이 Ollama를 기본 채팅 상대로 수동 전환할 수도 있습니다 (가벼운 질문에 유용).
+- **한도 초과 큐** — Claude Max / API 레이트 리밋 에러에 리셋 시간이 포함되면, 먼저 활성화된 폴백을 시도합니다. 폴백이 없거나 모두 실패할 때만 해당 메시지를 큐에 넣고 리셋 시각에 재시도합니다 — 작업 중 큐와 같은 방식입니다. 한도가 걸린 동안 추가로 보내는 메시지도 자동으로 큐에 쌓입니다. `/reserve`로 대기 현황과 리셋 시각 확인, `/reserve rm`으로 큐 전체 취소.
+- **Codex 폴백** — `"codexFallback": true`로 설정하면 Claude 레이트 리밋·크레딧 부족 시 `codex exec`가 대신 실행됩니다. Codex는 `state.codexSessionId`에 별도 세션을 저장하고 `codex exec resume <id>`로 이어가지만, Claude 세션과 Codex 세션은 서로 호환되지 않습니다. 대신 성공한 Codex 폴백마다 `.claude-bot/codex-handoff.md`에 요약을 남기고, 이후 Claude 호출 때 최근 handoff 내용을 맥락으로 주입합니다.
+- **실행 중 provider 전환** — `/provider`로 확인하고, `/provider claude` 또는 `/provider codex`로 봇 state override를 저장할 수 있습니다. `/provider default`는 config 값으로 되돌립니다.
+- **Ollama 폴백** — `"ollamaFallback": true`로 설정하고 `"ollamaModel"`에 로컬 [Ollama](https://ollama.ai) 모델을 지정하면(기본값: `"qwen3.5:4b"`), Codex가 꺼져 있거나 실패했을 때 보조 폴백으로 사용됩니다. `/ollama`로 Claude와 관계없이 로컬 모델을 기본 채팅 상대로 수동 전환할 수도 있습니다. 내부적으로 `ollama launch claude … --resume <세션>`을 사용하지만 로컬 모델 컨텍스트가 작으므로 최선 노력(best-effort)입니다.
 - **자동 컴팩션** — 세션의 캐시된 입력 토큰이 `autoCompactThreshold`(기본값 100,000)를 초과하면 `/compact`를 자동 실행하고 알림을 보냅니다. config에서 임계값을 조정하거나, 런타임에 `/autocompact <숫자>`로 설정(`/autocompact off`로 비활성화, `/autocompact default`로 초기화) — `state.json`에 저장돼 재시작 후에도 유지됩니다. 수동으로 `/compact`를 써도 됩니다.
 - **간결한 답변** — 텔레그램에 맞게 짧게 답하도록 시스템 프롬프트가 기본으로 붙습니다. 바꾸려면 `appendSystemPrompt`에 직접 넣으세요 (빈 문자열이면 끔).
 - **언어** — 봇 자체 문구(`/help`, 명령 메뉴, 상태 메시지)는 **기본 영어**, 텔레그램이 한국어인 사용자에겐 한국어로 나옵니다. `lang`(`"en"`/`"ko"`)으로 고정할 수 있습니다. Claude의 실제 답변은 **사용자가 쓴 언어**를 따라갑니다. `/` 명령 메뉴는 `setMyCommands`로 언어별 등록됩니다.
 - **서식 변환** — 답변의 마크다운(굵게·코드·표 등)을 텔레그램 HTML로 바꿔 보냅니다. 변환이 깨지는 경우엔 평문으로 다시 보냅니다.
-- **첨부 파일** — 사진·문서·음성·영상을 보내면 `attachments/`에 내려받고, 그 경로를 Claude에게 전달합니다(캡션도 함께). 이미지는 Read로 열어볼 수 있습니다.
+- **첨부 파일** — 사진·문서·음성·영상을 보내면 `attachments/`에 내려받고, 그 경로와 캡션을 활성 provider에 전달합니다.
 
 ## 커스텀 명령어
 
@@ -273,10 +338,12 @@ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.claudebot.example.pl
 
 - `allowedChatId`를 반드시 설정하세요. 설정 전에는 봇이 아무것도 실행하지 않고 chatId만 알려줍니다. 이게 유일한 인증 수단입니다.
 - 토큰을 자격증명처럼 다루세요. 이슈·로그·스크린샷에 붙여넣지 마세요. 시작 로그는 토큰을 `<redacted>`로 가립니다.
-- 샌드박스는 없습니다. 봇은 `claude`를 내 계정 권한으로 실행합니다. 내 파일, SSH/git 자격증명, Claude 인증 세션에 그대로 접근합니다.
+- 봇 자체는 보안 경계가 아닙니다. Claude는 `permissionMode`, Codex는 `codexSandbox`를 사용하지만 두 프로세스 모두 데몬 사용자의 환경과 자격증명을 상속합니다.
 
 **권한 모드 선택**
 
+Claude와 Codex의 안전 설정은 서로 다르며 `/provider` 전환 시 실제 권한 경계도 달라질 수 있습니다. 아래 표는 Claude의 `permissionMode`입니다.
+
 | 모드 | 허용 범위 | 권장 상황 |
 |---|---|---|
 | `plan` | 읽기·계획만 | Q&A, 코드 리뷰, 기획자 페르소나 |
@@ -287,6 +354,9 @@ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.claudebot.example.pl
 - `projectDir`는 홈 디렉터리가 아니라 특정 프로젝트를 가리키게 해 피해 범위를 줄이세요.
 - 페르소나 봇을 여럿 둘 땐 하나만 `bypassPermissions`로 두고 나머지는 `plan`으로.
 - 상시 가동한다면 전용 계정이나 VM도 고려해 보세요.
+- Codex는 특별한 이유가 없다면 `codexSandbox: "workspace-write"`를 유지하세요.
+- `/plan`, `/compact`, 자동 compact는 Claude 전용입니다.
+- 커스텀 `/명령어`는 provider 설정과 무관하게 데몬 사용자 권한으로 직접 실행됩니다.
 
 보안 이슈는 공개로 올리기보다 GitHub 이슈(민감한 내용은 메인테이너에게 비공개)로 알려주세요.