6. CLI와 에이전트 연동

터미널에서 사바쨩을 다루고, Claude Code나 Codex 같은 내 AI 에이전트가 사바쨩을 대신 다루게 합니다.

6. CLI와 에이전트 연동

saba-chan-cli는 사바쨩을 터미널에서 다루는 도구입니다. 터미널은 명령을 글자로 입력하는 창입니다. 앱으로 할 수 있는 일은 CLI로도 모두 할 수 있습니다. CLI도 앱처럼 데몬에게 부탁할 뿐, 직접 서버 파일을 만지지 않습니다. 사람이 쓰기에도 편하고 기계가 읽기 좋은 출력도 내므로, 내 AI 에이전트에게 사바쨩을 맡기는 통로로도 씁니다.


CLI 쓰기

CLI는 사바쨩을 설치한 폴더에 있습니다(기본 C:\Program Files\Saba-chan\saba-chan-cli.exe). 설치 프로그램은 시스템 PATH(명령을 이름만으로 찾는 폴더 목록)를 바꾸지 않습니다. 그러니 전체 경로로 부르거나 그 폴더를 PATH에 직접 추가하세요. 리눅스에서는 설치기가 ~/.local/bin/saba-chan-cli를 만들어 둡니다.

  • 인자 없이 실행하면 대화형 화면이 열립니다.
  • 데몬이 꺼져 있으면 켤지 물어봅니다. CLI를 닫아도 데몬과 서버는 계속 돕니다.
  • 서버 이름은 일부만 적어도 됩니다.
하고 싶은 일명령
전체 상태saba-chan-cli status
서버 추가saba-chan-cli server add
켜기 · 끄기 · 재시작saba-chan-cli start 팰 · stop 팰 · restart 팰
콘솔 · 게임 명령saba-chan-cli console 팰 · saba-chan-cli run 마크 say 안녕
백업 · 예약 작업saba-chan-cli backup … · saba-chan-cli schedule …
디스코드 연결saba-chan-cli bot pair (코드를 보여 주고 연결될 때까지 기다립니다)
명령 권한 · 레벨별 명령 보기saba-chan-cli perm … · perm commands
디스코드 되묻기 단계saba-chan-cli bot confirm
디스코드 서버 접두사 · 슬래시 명령 모양saba-chan-cli bot prefix … · bot slash …
읽어주는 사바쨩 · 디스코드 서버 관리saba-chan-cli bot tts … · bot moderation · bot channel …
말하는 사바쨩 도구 보기saba-chan-cli chatbot tools (바꾸기: chatbot set tools=[lol,pubg] --guild …)
연결된 AI 에이전트(원격) 보기 · 끊기saba-chan-cli bot agent · bot agent --unlink
사바쨩 업데이트saba-chan-cli update check · update apply
원격 데몬saba-chan-cli remote … · 아무 명령에나 --daemon <이름> (원격 데몬)
앱으로 전환saba-chan-cli gui
개인정보 모두 지우기saba-chan-cli bot erase
자세한 도움말saba-chan-cli <명령> --help

내 AI 에이전트와 연동하기

Claude Code, Codex처럼 터미널 명령을 실행할 수 있는 AI 에이전트라면 사바쨩을 맡길 수 있습니다. 에이전트는 사람처럼 말로 부탁을 받고, 뒤에서 saba-chan-cli를 실행해 결과를 읽습니다.

내 AI 에이전트 (예: Claude Code, Codex)
›

CLI는 에이전트가 쓰기 좋게 다음을 지킵니다.

  • --json: 표준 출력에는 JSON 문서 하나만 나옵니다. 안내와 진행 표시는 표준 오류로 갑니다. 실패하면 error, error_code, (있으면) suggestions가 들어 있습니다.
  • 종료 코드: 0 성공, 1 실패, 2 사용법 오류나 대상이 여럿, 3 데몬에 연결할 수 없음, 4 대상 없음, 130 취소.
  • help --json: 모든 명령의 트리, 인자, 전역 옵션, 종료 코드 표를 JSON으로 줍니다. 데몬이 꺼져 있어도 됩니다. 에이전트가 명령을 외우지 않고 이것부터 읽게 하세요.
  • --json-stream: 오래 걸리는 작업(서버 설치, 업데이트)의 진행을 한 줄에 JSON 하나씩 내고, 마지막 줄에 결과를 싣습니다.
  • events --json: 데몬 이벤트(서버 시작·종료, 설치 진행 등)를 한 줄씩 따라갑니다.
  • do: 데몬이 여는 작업 목록입니다. do 작업 --plan으로 무엇이 바뀌는지 먼저 보고 실행할 수 있습니다.

사람이 직접 해야 하는 것

  • 확인이 필요한 명령(켜진 서버의 stop·restart 포함)은 터미널이 아니면 묻지 않고 멈추므로 --yes가 있어야 실행됩니다. 서버 삭제나 초기화처럼 되돌릴 수 없는 명령에 --yes를 붙이기 전에는 에이전트가 사람에게 먼저 묻게 하세요.
  • 게임 약관(EULA) 동의와 확인되지 않은 모듈을 격리 없이 돌리는 동의는 --yes나 --json으로 대신할 수 없습니다. 사람이 터미널이나 앱에서 직접 합니다.

에이전트 지침에 붙여 넣을 예시

에이전트의 지침 파일(예: AGENTS.md, CLAUDE.md)에 다음처럼 적어 두면 됩니다. 경로는 내 설치 위치에 맞게 고치세요.

## 사바쨩 게임 서버
- 게임 서버는 saba-chan-cli로만 다룬다: "C:\Program Files\Saba-chan\saba-chan-cli.exe"
- 처음 한 번 `saba-chan-cli help --json`으로 명령과 인자를 읽는다.
- 모든 명령에 --json을 붙이고 종료 코드를 확인한다 (0 성공, 1 실패, 2 사용법·모호함, 3 데몬 없음, 4 대상 없음).
- 서버 삭제·초기화처럼 되돌릴 수 없는 명령은 사람에게 묻고 나서 --yes를 붙인다.
- 약관 동의와 격리 해제는 사람에게 맡긴다.

원격으로 AI 에이전트 연결하기 (MCP)

ChatGPT, Claude 같은 AI 에이전트가 PC의 터미널을 쓰지 못해도, 사바쨩 클라우드에 원격 MCP로 붙여 내 PC의 게임 서버를 맡길 수 있습니다. 내 디스코드 계정에 연결한 모든 PC를 앱에서처럼 다룹니다.

  1. 에이전트의 커넥터(원격 MCP 서버) 추가 화면에 https://saba-chan.online/mcp를 넣습니다. 이 주소는 앱의 설정 → 연결 화면, /내사바쨩 에이전트, saba-chan-cli bot agent에서도 볼 수 있습니다.
  2. 브라우저에 디스코드 로그인이 열리면 PC를 연결한 디스코드 계정으로 로그인하고, 사바쨩 동의 화면에서 허용합니다.
  3. 에이전트에게 말로 부탁합니다. 예: "마크 서버 상태 알려 줘", "팰월드 서버 다시 켜 줘"

에이전트로 할 수 있는 일:

  • 게임 서버: 앱에서처럼 서버를 켜고 끄고, 콘솔 명령을 보내고, 백업·예약 작업·게임 서버 업데이트·진단을 다룹니다. 게임 설정 파일 원문을 읽고 고치거나, 사바쨩 앱 업데이트를 확인하고 적용하는 일도 맡길 수 있습니다(사바쨩 0.1.12부터).
  • 디스코드 서버: 내가 관리하는 디스코드 서버의 사바쨩 설정(언어, 채널 배정, 이모지 업스케일, 게임 채팅·알림 옵션 등)을 읽고 바꾸며, 제재·메시지 청소 같은 서버 관리도 합니다. 사바쨩 웹과 같은 길을 거치므로 서버 주인·서버 관리 권한·PC 주인 판정과 일마다 필요한 디스코드 권한이 웹과 같습니다. PC가 원본인 설정은 PC 주인일 때 PC를 거쳐 바꿉니다.

알아 두면 좋은 점:

  • 한 디스코드 계정에 에이전트를 여러 개(최대 10개) 연결할 수 있습니다. 같은 에이전트를 다시 허용하면 그 에이전트의 예전 연결만 바뀝니다. 연결한 에이전트는 사바쨩 설정 → 연결이나 /내사바쨩 에이전트에서 하나씩 보고 끊을 수 있습니다.
  • 위험한 명령과 정지·재시작, 여러 단계를 한 번에 하는 계획, 제재·메시지 청소 시작·말하는 사바쨩 기억 지우기는 실행 전에 에이전트 화면에서 다시 묻습니다(앱과 같은 규칙). 디스코드로 묻지 않습니다.
  • 원격 결과에는 비밀번호 같은 비밀값과 PC 경로가 빠집니다(게임 설정 파일 원문은 예외로 그대로 보입니다). 그 밖에 사바쨩 웹에서 막힌 PC 전용 설정은 에이전트로도 할 수 없습니다.
  • 연결 끊기: 앱의 설정 → 연결 화면 에이전트 연결 끊기, 디스코드 /내사바쨩 에이전트, saba-chan-cli bot agent --unlink. 90일 동안 쓰지 않은 연결은 저절로 끊깁니다.