Sonolbot Universal

Windows와 macOS용 Sonolbot 보안강화 배포 패키지입니다.

일반 사용자는 소스코드를 빌드하지 말고 아래 직접 다운로드 링크에서 sonolbot_universal.zip을 받으세요.

바로 다운로드

• Sonolbot Universal 다운로드: https://github.com/volition79/sonolbot-universal/releases/latest/download/sonolbot_universal.zip
• 체크섬: https://raw.githubusercontent.com/volition79/sonolbot-universal/main/SHA256SUMS.txt
• 릴리스 페이지: https://github.com/volition79/sonolbot-universal/releases/latest
• 현재 버전: 0.1.25
• 현재 zip SHA256: 718fed656666f65a3a6af9643e7b3605100ed5f6f7fd5b1e7d49e1f9b132ce12

이 저장소는 수동 최초 설치용 최신 패키지를 제공하는 곳입니다. 설치 후 새 버전 확인과 업데이트는 Sonolbot 내부 업데이트 확인 기능을 사용하세요.

설치 전 사전 요구사항

Sonolbot은 Codex 또는 Claude Code를 내 컴퓨터에서 실행한 뒤 Telegram 봇과 연결하는 방식입니다. 따라서 Sonolbot 압축파일을 실행하기 전에, Windows와 macOS에서 아래 준비를 먼저 끝내야 합니다.

Windows 사용자의 준비 순서

Windows에서는 Sonolbot이 Windows 안의 Linux 환경인 WSL/Ubuntu를 사용합니다. 처음 설치하는 컴퓨터라면 아래 순서대로 진행하세요.

1. WSL 설치 여부 확인
   • Windows 시작 메뉴에서 PowerShell 또는 명령 프롬프트를 엽니다.
   • 아래 명령을 입력합니다.

wsl --status

2. WSL이 없으면 Ubuntu 설치
   • wsl을 찾을 수 없거나 Ubuntu가 없다면, PowerShell 또는 명령 프롬프트에서 아래 명령을 실행합니다.

wsl --install -d Ubuntu

• 설치가 끝난 뒤 재부팅을 요구하면 컴퓨터를 재부팅하세요.
• 재부팅 후 Ubuntu 앱을 처음 실행하면 사용자 이름과 비밀번호를 만들라는 화면이 나옵니다.
• 이 비밀번호는 화면에 표시되지 않는 것이 정상입니다. 입력 후 Enter를 누르세요.

3. Ubuntu 터미널 열기
   • Windows 시작 메뉴에서 Ubuntu를 실행합니다.
   • 또는 PowerShell/명령 프롬프트에서 아래 명령을 입력합니다.

wsl

4. Ubuntu 안에 필요한 도구 설치
   • Ubuntu 터미널에서 아래 명령을 그대로 입력합니다.
   • 중간에 비밀번호를 물으면 Ubuntu 처음 설정 때 만든 비밀번호를 입력하세요.

sudo apt-get update
sudo apt-get install -y python3 python3-pip python3-venv nodejs npm tmux

• python3, python3-pip, python3-venv는 Sonolbot의 WSL 런타임 준비에 필요합니다.
• nodejs, npm은 Codex/Claude Code 설치, 최신 버전 확인, 업데이트에 필요합니다.
• tmux는 Windows/WSL에서 Claude Code를 안정적으로 제어하는 데 필요합니다.

5. Codex 또는 Claude Code 설치와 로그인

   • Codex를 사용할 사람은 Ubuntu 터미널에서 codex --version이 동작해야 합니다.
   • Claude Code를 사용할 사람은 Ubuntu 터미널에서 claude를 직접 실행해 로그인까지 완료해야 합니다.
   • 둘 중 하나만 정상 설치/로그인되어도 Sonolbot을 사용할 수 있습니다.
   • Claude Code는 npm이 아닌 방식으로 설치되어 있을 수도 있습니다. 중요한 기준은 Ubuntu 터미널에서 claude가 정상 실행되고 로그인되어 있는지입니다.

6. 그 다음 Sonolbot 설치 진행

   • 위 준비가 끝난 뒤 sonolbot_universal/windows-amd64/ 폴더에서 1.사전점검.bat부터 실행하세요.
   • 사전점검에서 누락 항목이 나오면 안내된 항목을 먼저 설치한 뒤 다시 실행하세요.

macOS 사용자의 준비 순서

macOS에서는 WSL을 사용하지 않고, Mac에 설치된 Codex 또는 Claude Code를 직접 사용합니다.

1. Terminal 앱 열기

   • Finder에서 응용 프로그램 > 유틸리티 > 터미널을 실행합니다.
   • 또는 Spotlight에서 Terminal을 검색해 실행합니다.

2. Node.js/npm 설치 확인

   • 터미널에서 아래 명령을 입력합니다.

node --version
npm --version

• 둘 다 버전이 나오면 다음 단계로 넘어가면 됩니다.
• command not found가 나오면 Node.js를 설치해야 합니다.

3. Node.js/npm 설치
   • Homebrew를 사용하는 경우:

brew install node

• Homebrew가 없다면 Node.js 공식 설치 프로그램을 사용해도 됩니다.
• 설치 후 터미널을 새로 열고 node --version, npm --version이 나오는지 다시 확인하세요.

4. Codex 또는 Claude Code 설치와 로그인

   • Codex를 사용할 사람은 터미널에서 codex --version이 동작해야 합니다.
   • Claude Code를 사용할 사람은 터미널에서 claude를 직접 실행해 로그인까지 완료해야 합니다.
   • 둘 중 하나만 정상 설치/로그인되어도 Sonolbot을 사용할 수 있습니다.

5. Python 안내

   • macOS에서 Sonolbot의 기본 Go 런타임 실행 자체에는 Python이 필수는 아닙니다.
   • 다만 PDF, DOCX, XLSX 같은 문서 처리 스킬이나 일부 고급 스킬을 쓰면 Python이 필요할 수 있습니다.
   • 그런 기능을 쓸 예정이라면 터미널에서 아래 명령이 동작하는지 확인하세요.

python3 --version

6. 그 다음 Sonolbot 설치 진행
   • Apple Silicon Mac은 sonolbot_universal/macos-arm64/ 폴더를 사용하세요.
   • Intel Mac은 sonolbot_universal/macos-amd64/ 폴더를 사용하세요.
   • 아래의 macOS 실행 방법에 따라 .command 파일을 순서대로 실행하면 됩니다.

설치 및 실행 순서

압축을 푼 뒤 본인 컴퓨터에 맞는 하위 폴더에서 실행하세요.

Windows 64-bit

sonolbot_universal/windows-amd64/ 폴더로 들어간 뒤 아래 파일을 순서대로 더블클릭하세요.

1. 1.사전점검.bat
2. 2.설치하기.bat
3. Codex를 쓸 경우 3.코덱스로그인.bat
4. Claude Code를 쓸 경우 4.클로드코드로그인.bat
5. 5.제미나이로그인.bat는 현재 사용하지 않으므로 실행하지 않아도 됩니다.
6. 6.컨트롤패널.bat

Codex 또는 Claude Code 중 하나만 정상 로그인되어도 사용할 수 있습니다.

Claude Code를 사용할 경우에는 봇을 추가하기 전에 WSL/Ubuntu 터미널에서 claude를 직접 실행해 로그인까지 완료하세요. Claude Code는 npm이 아닌 방식으로 설치되어 있을 수도 있으므로, npm 설치 여부보다 터미널에서 claude가 정상 실행되고 로그인된 상태인지가 중요합니다. 로그인 완료 후 4.클로드코드로그인.bat를 실행하고, 그 다음 컨트롤패널에서 provider를 claude-code로 선택해 봇을 추가하세요.

macOS Apple Silicon

Apple Silicon Mac은 sonolbot_universal/macos-arm64/ 폴더를 사용하세요.

macOS Intel

Intel Mac은 sonolbot_universal/macos-amd64/ 폴더를 사용하세요.

macOS 실행 방법

macOS의 .command 파일은 터미널에서 실행하는 것을 권장합니다.

1. Finder에서 본인 Mac에 맞는 폴더를 엽니다.
2. 폴더 안의 빈 공간을 마우스 오른쪽 클릭합니다.
3. 폴더에서 새로운 터미널 열기 또는 서비스 > 폴더에서 새로운 터미널 열기를 선택합니다.
4. 터미널이 열리면 아래 명령을 순서대로 입력합니다.

터미널이 이미 해당 폴더에서 열렸다면 첫 번째 cd ... 줄은 입력하지 않아도 됩니다. 경로를 직접 쓰기 어렵다면 터미널에 cd 를 입력한 뒤 Finder의 폴더를 터미널로 끌어다 놓고 Enter를 누르세요.

Apple Silicon:

cd /다운로드한/위치/sonolbot_universal/macos-arm64
chmod +x *.command scripts/run_go_client.sh sonolbot-go-client/sonolbot-client sonolbot-go-client/sonolbot-control-panel
xattr -dr com.apple.quarantine .
./1.사전점검.command
./2.설치하기.command
./3.코덱스로그인.command
./6.컨트롤패널.command

Intel Mac:

cd /다운로드한/위치/sonolbot_universal/macos-amd64
chmod +x *.command scripts/run_go_client.sh sonolbot-go-client/sonolbot-client sonolbot-go-client/sonolbot-control-panel
xattr -dr com.apple.quarantine .
./1.사전점검.command
./2.설치하기.command
./3.코덱스로그인.command
./6.컨트롤패널.command

Claude Code를 쓸 경우 ./3.코덱스로그인.command 대신 또는 추가로 ./4.클로드코드로그인.command를 실행하세요. ./5.제미나이로그인.command는 현재 사용하지 않으므로 실행하지 않아도 됩니다.

Claude Code를 사용할 경우에는 봇을 추가하기 전에 터미널에서 claude를 직접 실행해 로그인까지 완료하세요. 로그인 완료 후 ./4.클로드코드로그인.command를 실행하고, 그 다음 컨트롤패널에서 provider를 claude-code로 선택해 봇을 추가하세요.

macOS 컨트롤패널에서는 업데이트 확인, 이전 소놀봇 가져오기가 화면 최상단 메뉴바와 패널 내부 관리 영역에 함께 표시됩니다. 자동시작을 켜면 사용자 ~/Library/LaunchAgents에 등록되어 다음 로그인부터 패널과 데몬 자동 시작에 사용됩니다.

6번 컨트롤패널 실행 후 사용 순서

6.컨트롤패널 실행에 성공하면 아래와 같은 Sonolbot Control Panel이 열립니다.

처음 실행 직후 Claude Code 또는 Codex의 현재 버전, 최신 버전이 비어 있거나 업데이트하기 버튼이 보이지 않을 수 있습니다. 이 경우 상단의 새로고침 버튼을 누른 뒤 30~60초 정도 기다리세요. 최초 설치 직후에는 provider 버전 정보가 캐시에 없어 비어 보일 수 있으며, 새로고침 후 표시되는 것이 정상입니다. 새로고침 후에도 Claude Code 정보가 계속 비어 있으면 터미널에서 claude 실행 및 로그인 완료 여부를 먼저 확인하세요.

이후 아래 순서로 설정하세요.

1. 텔레그램 허용 사용자 ID 추가

   • 오른쪽 아래 전역 허용 사용자 ID 영역에 본인의 Telegram 숫자 ID를 입력합니다.
   • ID 추가를 누르고 성공 안내가 뜨면 등록 완료입니다.
   • 이 ID에 포함되지 않은 사용자의 메시지는 봇이 처리하지 않습니다.

2. 봇 추가

   • 텔레그램 봇 관리 탭에서 봇 추가를 누릅니다.
   • Telegram BotFather에서 만든 봇 토큰을 입력하고 검증합니다.
   • provider는 사용할 실행기를 선택합니다.
     • Codex를 사용할 경우: codex
     • Claude Code를 사용할 경우: claude-code
   • 실행 환경은 OS에 맞게 자동 제한됩니다.
     • Windows: wsl
     • macOS: macos
   • Claude Code로 봇을 만들 때 로그인 또는 실행 준비가 안 되어 있으면 4.클로드코드로그인을 먼저 실행한 뒤 다시 시도하세요.

3. 이전 Sonolbot 가져오기

   • 기존 설치본을 이어서 쓰려면 관리 영역 또는 macOS 상단 메뉴의 이전 소놀봇 가져오기를 누릅니다.
   • 기존 Sonolbot 폴더를 선택한 뒤 안내에 따라 가져오기를 적용합니다.
   • 가져오기 후 봇 목록과 설정이 표시되는지 확인하고, 필요하면 provider와 실행 환경을 다시 확인하세요.

4. 데몬 시작

   • 봇이 운영 사용가능 상태인지 확인합니다.
   • 상단의 시작 버튼을 누릅니다.
   • 상태가 데몬: 실행 중으로 바뀌면 Telegram 메시지 감시와 자동 응답이 시작됩니다.

5. Telegram에서 대화 테스트

   • Telegram에서 등록한 봇에게 짧은 메시지를 보냅니다.
   • 답변이 오면 기본 구동이 완료된 것입니다.
   • 답변이 오지 않으면 허용 사용자 ID, 봇 토큰, provider 로그인 상태, 데몬 실행 상태를 먼저 확인하세요.

6. 업데이트 확인

   • 설치 후 새 버전은 패널의 업데이트 확인에서 적용합니다.
   • 이 공개 저장소는 최초 설치용 패키지이며, 일반 업데이트는 Sonolbot 내부 업데이트 기능을 기준으로 진행합니다.

7. 문제가 있을 때 에러보고하기

   • 실행, 로그인, 봇 추가, 모델 변경, Telegram 응답 문제가 있으면 상단의 에러 보고하기를 누르세요.
   • 최근 로그와 진단 정보가 서버로 전송되어 원인 분석에 사용됩니다.
   • 토큰 같은 민감값은 진단 패키지 생성 과정에서 마스킹됩니다.

macOS Gatekeeper 안내

현재 패키지는 Apple notarization을 적용하지 않은 내부/소수 사용자용 배포입니다. macOS에서 "확인되지 않은 개발자" 또는 quarantine 차단이 나오면, 해당 하위 폴더에서 터미널로 아래 명령을 실행한 뒤 다시 여세요.

xattr -dr com.apple.quarantine .

보안 구성

• 실행 바이너리는 garble 기반 obfuscated release build입니다.
• 개인 토큰, 봇 설정, 작업 기록, 로그, runtime 상태는 포함하지 않습니다.
• 서버 artifact와 내부 개발자 문서는 포함하지 않습니다.
• 업데이트/활성화 정책은 Sonolbot 서버의 signed update 경로를 기준으로 운영합니다.

무결성 확인

릴리스의 SHA256SUMS.txt 또는 이 저장소의 SHA256SUMS.txt를 확인하세요.