SUGT — 로컬 AI 게이트웨이 및 LLM 스킬 콘솔
**SUGT (su gateway)**는 데스크톱용 로컬 AI 게이트웨이이자 스킬 제어 평면(skills control plane)입니다. 이 시스템은 여러 LLM 제공업체(OpenAI, Anthropic, ModelScope, Volcengine, SiliconFlow, Moonshot Kimi, DeepSeek, DashScope 및 자체 호스팅 모델)의 API 키를 단일한 OpenAI/Anthropic 호환 프록시 뒤에 중앙 집중화합니다. 따라서 Claude Code, Codex, OpenCode 등 다른 AI 코딩 클라이언트들은 모두 하나의 로컬 엔드포인트와 통신하며, 사용자는 단일 패널에서 업스트림 모델을 교체할 수 있습니다. 또한 라이브러리를 잃지 않으면서 스킬을 발견하고, 설치하고, 마운트할 수 있는 스킬 콘솔도 제공합니다.
- 모든 곳에 하나의 키 세트: 기본 URL과 인증 정보가 단일 로컬 게이트웨이에 통합됩니다.
- 업스트림 자유 교체: OpenAI, Anthropic, ModelScope, Volcengine, SiliconFlow, Moonshot Kimi, DeepSeek 또는 자체 모델을 사용하며, 클라이언트 측 재설정이 필요 없습니다.
- 유지되는 스킬: 스킬을 발견하고, 설치하고, 마운트할 수 있으며, 언마운트해도 라이브러리가 손실되지 않습니다.
라이선스
GitHub Releases에서 릴리스된 버전이 전체 제품입니다: 로컬 AI 게이트웨이, 프로토콜 변환(protocol translation), 클라이언트 장악(client takeover), 스킬 콘솔, 그리고 인앱 SOUL 컴패니언을 포함합니다. 소스는 Apache-2.0입니다.
이유 (Why)
- API 키가 분산되어 있음: OpenAI, Anthropic, ModelScope, Volcengine, Moonshot Kimi, DeepSeek, 로컬 모델 등 여러 곳에 API 키가 흩어져 있습니다.
- 모든 에이전트가 자체 기본 URL 및 인증 설정을 원함: 각 클라이언트에서 설정을 재편집하는 것은 지루하고 오류를 일으키기 쉽습니다.
- 스킬들이 다른 폴더에 존재하며 공유된 발견/마운트/유지 흐름이 없음: 기기를 전환할 때마다 모든 것을 다시 해야 합니다.
SUGT는 의도적으로 작게 설계되었습니다: 호환 가능한 로컬 게이트웨이, 일반 에이전트를 위한 원클릭 전환(one-click takeover), 그리고 실제로 유지할 수 있는 스킬 제어 평면(skill control plane)을 제공합니다.
기능 (Features)
콘솔 레이아웃 (Console layout)
총 7개의 주요 탭으로 구성되어 있습니다: 대시보드(Dashboard), 모델(Models), 클라이언트(Clients), 스킬(Skills), SOUL, 규칙(Rules), 설정(Settings). 로그(Logs)와 정보(About)는 설정 내부로 이동했으며, 이제 설정에는 여섯 개의 고정 수평 하위 탭—개요(Overview)(첫 번째), 일반(General), 모양(Appearance), 고급(Advanced), 로그(Logs), 정보(About)—이 있습니다. 개요는 읽기 전용이며 서비스 상태, LAN 공유 상태/URL/키/모델, 활성 상위 제공업체(upstream), 엔드포인트 및 빌드 ID, 그리고 관련 하위 탭으로의 바로가기를 보여줍니다. 로그 폴링은 로그 하위 탭이 보이는 동안에만 실행됩니다.
로컬 AI 게이트웨이 (Local AI Gateway)
- Tauri 프로세스에 내장된 Axum HTTP 서버로, OpenAI Chat Completions, Anthropic Messages, 및 OpenAI Responses를 처리합니다.
- 프로토콜 브리징(Protocol bridging): Anthropic과 OpenAI 간의 양방향 요청/응답 변환을 지원하며, SSE 스트리밍도 포함됩니다.
- 다중 상위 제공업체 장애 조치(Multi-upstream failover):
failover 순서에 따라 다음 제공업체로 자동 전환됩니다. 실험적인 무료 채널은 Chat 및 Responses 경로에서 후보 모델 전반에 걸쳐 장애 조치를 수행합니다.
- 핫 리로드 설정 (Hot-reload config):
config.toml을 편집하면 다음 요청에서 즉시 적용되며, 재시작이 필요 없습니다.
- 포트 폴백(Port fallback): 구성된 포트가 사용 중인 경우, 게이트웨이가 다음에 사용 가능한 포트를 바인딩합니다.
- LAN 공유 (LAN share): “LAN 연결 허용(Allow LAN connections)”을 활성화하면
0.0.0.0에 바인딩하고 한 번의 클릭으로 LAN 기본 URL/API 키를 복사할 수 있습니다.
- 내장 엔드포인트:
/health, /v1/models, /v1/_sugt/traffic, /v1/_sugt/workspace-rules, /v1/_sugt/notify
모델 관리 (Model Management)
- 표준 기본 URL 및 모델 목록을 갖춘 중국 제공업체 카탈로그(ModelScope, Volcengine, SiliconFlow, Moonshot Kimi, DeepSeek 등)가 내장되어 있습니다.
- 패널 하나에서 제공업체를 활성화/비활성화하고, 기본 모델을 전환하며, 연결성을 테스트할 수 있습니다.
- 실험적인 무료 채널: 콘솔을 열거나 해당 상위 제공업체를 선택할 때 한 번 자동 프로브(auto-probe)합니다 (백그라운드 폴링 없음). 언제든지 수동으로 새로 고칠 수 있습니다.
원클릭 에이전트 전환 (One-Click Agent Takeover)
-
22개의 알려진 클라이언트(중국 및 글로벌: Claude Code, Codex, CodeBuddy, Trae, Lingma, iFlow, Kimi CLI, Qoder, Comate, CodeGeeX, Windsurf, Cline, Copilot CLI, Kiro, Goose, Factory Droid 등)를 포함하는 단일 카탈로그. Discovery는 쿼리가 비어 있더라도 전체 카탈로그를 나열하므로, 클라이언트는 가져가기 전에 로컬 트레이스(local traces)가 필요하지 않습니다. 미확인된 클라이언트는 환경 변수(env-var) 기능만 선언하며, 가짜 설정 파일 쓰기는 절대 하지 않습니다.
-
Claude Code / OpenCode: 환경 변수와 실행 스크립트는 로컬 게이트웨어를 가리키며, 장악(takeover)을 해제하면 이를 정리합니다.
-
Codex (CLI / Desktop): model_providers.sugt(wire_api = "responses", requires_openai_auth = false, 로컬 압축 기능)를 포함하여 ~/.codex/config.toml 파일을 작성하고, 사용자가 설정하지 않은 경우 호스팅된 web_search 기능을 비활성화합니다. 또한, 클라이언트가 공식 code_mode_only / use_responses_lite 도구 프로토콜을 상속받지 않도록 model에 sugt- 별칭(alias)이 부여됩니다 (비활성화는 SUGT_CODEX_MODEL_ALIAS=off 사용). auth.json은 인증 모드와 게이트웨이 키만 덮어쓰고 기존 로그인 필드는 유지합니다. 상위 시스템(upstream)에 네이티브 Responses API가 없는 경우, 게이트웨이는 Chat Completions로 브리징됩니다: 네임스페이스 도구를 평탄화하고 돌아오는 길에 이름을 복원하며, 선언을 통해 함수/사용자 정의 도구를 분류하고, 구조화된 도구 결과를 보존하며, 고아 호출(orphan calls)을 쌍으로 묶고, 전체 SSE 생명주기 이벤트(lifecycle events)를 방출합니다. 전달할 수 없는 Responses 필드는 관찰 가능한 방식으로 저하됩니다; 비어 있거나 유효하지 않은 상위 본문 및 4xx 응답은 가짜 빈 성공 대신 Responses 형태의 실패 객체를 생성합니다; 스트리밍은 지연된 도구 이름, 순서가 맞지 않는 인덱스, 잘못된 인수(malformed arguments), 청크에 걸쳐 분할되는 멀티바이트 문자를 허용합니다. MCP 서버는 클라이언트 자체의 [mcp_servers] 테이블 소유로 유지되며, SUGT는 이를 관리하지 않습니다.
-
SOUL 탭에 있는 가벼운 동반자 — 앱의 핵심(soul)이며 별도의 “게이트웨이 에이전트”가 아닙니다.
-
채팅하고, 로컬 프로젝트 폴더 아래에 작은 프로젝트를 생성하며, 파일을 작성하고, 쓰기 전 확인(confirm-before-write)을 통해 앱 또는 시스템 설정을 편집할 수 있습니다 (macOS는 ~/Library/Application Support/sugt/projects/로 기본 설정되어 iCloud Documents와 분리됩니다).
-
신뢰하는 세션에 대한 선택적 자동 승인 쓰기(auto-approve writes) 기능이 있습니다. 작성 후, su는 파일을 다시 읽어 검증합니다.
-
긴 셸 출력은 컨텍스트가 더 큰 프로젝트에서도 사용 가능하도록 잘립니다(head와 tail만 유지).
-
로컬 게이트웨이를 통해 사용자가 설정한 상위 모델을 이용해 이유를 생성합니다. 모델이 비전(vision)을 지원하는 경우 스크린샷을 붙여넣으세요.
-
작업 공간별로 분리된 채팅 기록을 제공하며, 진행 중인 작업을 중간에 멈추거나 더 무거운 작업은 Claude Code 또는 Codex로 넘길 수 있습니다.
-
관리 의도(Management intents)는 읽기 전용 라우팅입니다: su에게 실시간 사실 정보(known clients, taken-over clients, installed skills, repos 등)가 제공되며, 클릭 가능한 카드 형태로 Clients / Skills / Takeover preview / Settings 중 하나를 제안할 수 있습니다. 스스로 클라이언트 설정을 작성하거나, 리포지토리를 복제하거나, 스킬을 설치하는 일은 절대 없습니다. takeover, install 및 mount 작업은 영향도 미리보기와 사용자의 확인이 필요한 결정론적(deterministic) 명령으로 유지됩니다. 이 모든 기능은 제안 기능을 제외하고 모델이 사용 불가능할 때도 작동합니다.
Skills Console
- Git 저장소, Gitee 또는 사용자 지정 소스에서 스킬 인덱스를 새로 고침합니다.
- GitHub / Gitee / GitLab / Bitbucket / GitCode URL을 붙여넣어 스킬을 로컬 스킬(Local Skills)에 직접 설치할 수 있습니다: 호스트 허용 목록, 얕은 클론(프록시 인식,
main → master 폴백), SKILL.md 스캔, 원자적 배포(atomic landing), 실패 시 트랜잭션 롤백, 반복 가능한 ID가 지원됩니다. 이후 UI는 해당 스킬을 에이전트에 마운트하도록 로컬 스킬로 안내합니다.
- 트리거 단어는
SKILL.md 프런트매터(triggers / 触发词 / when_to_use, 쉼표로 구분되거나 YAML 목록)에서 읽어와 칩 형태로 표시되며, 규칙 기반의 "최적화 조언" 대화 상자는 누락된 메타데이터와 수정 방법을 설명합니다. 임의로 생성된 트리거는 없으며 모델이 필요하지 않습니다.
- 스킬 설치, 제거, 마운트 및 언마운트를 수행하며 — 라이브러리는 항상 보존됩니다.
- 여러 에이전트에 동일한 스킬을 마운트할 수 있으며; 마크다운으로 렌더링된 스킬 패널이 제공됩니다.
트래픽 오버레이 (Traffic Overlay)
- 항상 최상단에 표시되는 반투명 오버레이로, 오늘 토큰 활동을 실시간으로 보여줍니다.
- 가로/세로 레이아웃이 가능하며, 크기 조절이 가능하고 원클릭으로 기본값 복원이 가능합니다.
- macOS: 오버레이 위치와 마우스 통과 동작은 로컬 데스크톱 환경을 따릅니다.
작업 공간 규칙 (Workspace Rules)
- 규칙 텍스트, 문서 습관(document habits), 웹훅의 세 가지 독립적인 스위치가 있는 별도의 페이지입니다.
- 활성화된 규칙과 문서 습관은 게이트웨이를 통과하는 OpenAI, Anthropic 및 응답 요청에 주입됩니다. 이는 소프트 프롬프트(soft prompt)이므로 클라이언트가 파일을 읽거나 쓰도록 강제할 수는 없습니다.
- 새로운 설정에는 짧은 범용 규칙 초안(켜기 전까지 비활성화됨)이 포함되어 있으며, 기본적으로
AGENTS.md와 docs/MAP.md를 활성화합니다. 이 습관과 함께 내용이 비어있지 않은 목적 노트가 주입됩니다.
- 웹훅은 기본적으로 꺼져 있습니다. URL은 로컬 상태를 유지하며
/v1/_sugt/notify를 통해 중계됩니다. 모델 컨텍스트에는 절대 포함되지 않습니다.
- 저장된 규칙과 체크박스는 저장한 대로 유지됩니다. 동일한 주입 및 중계 경로가 Windows와 macOS에서 사용됩니다.
게이트웨이 워치독 (Gateway Watchdog)
- 게이트웨이 가용성 여부를 20초마다 감지하고 자동으로 재시작합니다.
- PID 파일을 통해 분리된(detached)
sugt-cli serve 프로세스를 관리합니다 (창 없음, 백그라운드 전용).
외관 / 테마 (Appearance / Themes)
- 내장 스킨: Cyber Console, Street, Skate, Brickyard, Shan-shui, HIPHOP, Jazz Night, 그리고 Anime Boy / Anime Girl (반투명 유리 패널이 적용된 일러스트 배경)
- 테마는 각각 하나의 CSS 파일(또는 JSON 팩)로 구성되며 고정된 약 40토큰 계약을 따릅니다 — 배경 이미지, 반투명 표면,
backdrop-filter 글래스 효과가 포함됩니다.
- 설정 → 외관(Appearance)에서 전환할 수 있습니다;
theme.json, .zip 또는 전체 폴더를 가져오기(import)합니다; 색상을 변경하지 않고 사용자 지정 배경을 오버레이할 수 있습니다.
- 상태 표시줄은 기본적으로 활성화되어 있으며 단단한 로그 서랍을 엽니다; 전체 로그는 설정 → 로그에 있습니다.
- 제작 가이드: [docs/THEME_AUTHORING.md] · 에이전트 규칙: [AGENTS.md]
스크린샷 (Screenshots)
콘솔(Console) — 시작/중지, 트래픽, 에이전트 엔드포인트.
Console
모델(Models) — 제공업체(providers), 기본 모델, 연결성 테스트.
Models
클라이언트(Clients) — 에이전트 검색, 인수 또는 해제.
Clients
스킬(Skills) — 로컬 마운트 및 리포지토리(repo) 검색.
Local skills
설정(Settings) — 개요, 언어, 게이트웨이, 외관 및 오버레이 옵션.
Settings
설정 → 로그(Logs) — 요청 및 게이트웨이 활동.
Logs
국제화 (Internationalization)
SUGT는 내장된 영어(English) / 중국어(中文) 지원 기능을 제공합니다. 모든 UI 텍스트는 제3자 종속성 없이 단일 사전 레이어를 통해 렌더링됩니다.
언어 전환 방법: 설정 → 일반 → 언어를 열고 다음 중 하나를 선택합니다:
| 옵션 | 동작 방식 |
|---|
| 시스템 따르기 (Follow system) | OS 언어를 사용합니다: 중국어 시스템은 中文을, 나머지 모든 것은 영어(English)를 표시합니다 (기본값) |
| ... | |
UI는 전환 직후 즉시 새로 고침됩니다 — 모든 패널, 대화 상자, 토스트 및 트래픽 오버레이가 끊김 없이 업데이트됩니다. 선택된 값은 로컬에 저장되며 재시작 후에도 유지됩니다.
구현 참고 사항:
- 모든 텍스트는
src/i18n.ts의 zh / en 사전(dictionary)에 저장되며, 컴포넌트는 t('네임스페이스.키')를 통해 이를 읽습니다.
- 동적 텍스트(토큰 수, 제공업체 이름, 경로 등)에는
{변수} 보간법(interpolation)이 지원됩니다.
- 설정은
localStorage에 저장되며, 테마 및 기타 UI 설정과 일관성을 유지합니다.
- 새 언어를 추가하는 것은 사전 확장(dictionary extension) 방식이므로 컴포넌트 변경이 필요 없습니다.
시작하기 (Getting Started)
설치 (Install)
Windows (winget) — 매니페스트가 상위 버전과 병합된 후:
winget install lsuen.SUGT
Windows (직접 다운로드) — GitHub Releases에서: SUTAI-windows-x64-setup.exe (NSIS 설치 프로그램) 또는 SUTAI-windows-x64.zip (포터블).
macOS (Homebrew) — 오픈 소스 tap을 통한 롤링 릴리스 캐스크:
brew tap lsuen/homebrew-sugt
brew trust --cask lsuen/homebrew-sugt/sugt
brew install --cask sugt
...
이 캐스크는 고정된 다운로드 URL과 함께 version :latest를 사용하므로, SUGT의 새 버전이 출시되어도 tap 업데이트가 필요하지 않습니다. Homebrew 6.0 미만에서는 brew trust 단계를 건너뛰세요.
애플리케이션 폴더에서 SUTAI로 실행합니다. 이 앱은 서명되지 않았습니다. 첫 실행 시에는 마우스 오른쪽 버튼 클릭 → **열기(Open)**를 하거나, xattr -cr "/Applications/SUTAI.app"을 실행하세요.