OpenShell

OpenShell은 Telegram 메시지를 로컬 CLI(codex, claude)에 연결하는 브리지 봇입니다.

• codex provider: 로컬 codex exec --json 사용
• claude provider: 로컬 claude -p --output-format stream-json 사용

CLI 스트림 이벤트를 받아 같은 메시지를 계속 edit하므로 답변이 실시간으로 갱신됩니다.

1. 설치

npm install

2. 최소 설정

.env.example를 복사해 .env를 만들고, 아래 1개만 채우면 실행됩니다.

cp .env.example .env

TELEGRAM_BOT_TOKEN=your_telegram_bot_token

처음 실행 후 Telegram에서 봇과 대화를 열고 /init을 1번 실행해 소유자(1인)를 등록해야 합니다.

필수 조건:

• 로컬 CLI 최소 1개 설치: codex 또는 claude
• 해당 CLI 로그인 완료 (codex login, claude setup-token 등)

3. 실행

개발 모드:

npm run dev

빌드 후 실행:

npm run build
npm run start

4. Telegram 사용법

• 일반 메시지: 그대로 질문
• /init (최초 1회, 소유자 등록)
• /model codex 또는 /model claude (provider 전환)
• /model [codex|claude] <model|default> [effort|default] (모델 변경)
• /models (매번 새로 조회)
• /reset
• /uid
• /help

모델/effort 예시:

• /model codex (Codex로 전환)
• /model codex gpt-5.3-codex xhigh (Codex 모델 + effort 설정)
• /model codex gpt-5.3-codex default (Codex 모델 설정 + effort override 해제)
• /model codex default (Codex 모델/effort override 모두 해제)
• /model claude (Claude로 전환)
• /model claude sonnet (Claude 모델 설정)

Codex effort 지원값:

• none, minimal, low, medium, high, xhigh

참고:

• provider를 생략하면 현재 provider 기준으로 처리됩니다.
• Claude CLI는 effort 단계 선택을 지원하지 않습니다. (xhigh 같은 인자는 무시)
• /models는 실행 시마다 로컬 파일/바이너리에서 목록을 다시 읽습니다. (Codex는 ~/.codex/models_cache.json)
• 계정 권한/플랜에 따라 일부 모델은 실제 실행 시 거부될 수 있습니다.

참고

• /init은 현재 사용자를 소유자(1인)로 등록하고 .openshell/owner.json에 저장합니다. (SESSION_STORE_PATH와 같은 폴더)
• OpenShell은 Codex/Claude CLI를 권한 확인 없이 실행하도록 구성되어 있어 위험합니다. 신뢰 가능한 환경에서만 사용하세요.
• codex는 ~/.codex/models_cache.json에서 모델 목록을 읽습니다.
• claude는 로컬 CLI 바이너리에서 모델 식별자를 추출해 목록을 만듭니다.
• 모델/effort override와 대화 히스토리는 채팅 단위로 저장되며, 재시작 후 자동 복구됩니다.
• 세션 저장 파일 위치는 SESSION_STORE_PATH로 변경할 수 있습니다.
• 답글(reply)로 질문하면 원본 메시지 텍스트를 함께 참고합니다.
• 긴 응답은 Telegram 길이 제한(4096)으로 잘려 표시될 수 있습니다.
• 동일 채팅에서 여러 질문을 연속 전송하면 내부적으로 순차 처리(큐)되어 응답 꼬임을 줄입니다.