환경설정(관리자)
환경설정은 관리자 계정에만 보입니다. 사이드바 맨 아래 톱니 아이콘(fa-gear, 환경설정)으로 들어갑니다. 같은 자리에 관리자 전용 메뉴가 함께 모여 있습니다.
| 아이콘 | 메뉴 | 내용 |
|---|---|---|
fa-users | 사용자 관리 | 계정 생성·역할·비밀번호 |
fa-chart-column | 통계 | 사용량·활동·배포·감사 로그 |
fa-gear | 환경설정 | 아래 탭 7종 |
환경설정은 상단 탭으로 나뉘고, 화면 맨 아래 [저장] 버튼 하나로 전체가 저장됩니다(저장되면 옆에 ✓ 저장됨). 단, 일반 탭의 테마·언어·로고·제품명은 누르는 즉시 반영되어 별도 저장이 필요 없습니다.
API 키·토큰이 서버 환경변수로 주입된 경우, 해당 입력칸은 잠기고 환경변수로 관리 중 배지와 함께 "환경변수에서 주입됨 (여기서 변경 불가)" 이 표시됩니다. 값을 바꾸려면 서버의 .env 를 수정하고 재기동해야 합니다. 절차는 비밀 관리를 참고하세요.
일반 (fa-sliders)
무엇에 영향을 주나 — 내가 보는 스튜디오 화면과, 전 사용자에게 보이는 브랜딩.
- 테마 — 라이트 / 다크. 즉시 적용되며 이 브라우저에만 저장됩니다.
- 언어 — 한국어 / English. 마찬가지로 개인 설정입니다.
- 브랜딩 (화이트라벨) — 여기서 바꾼 값은 모든 사용자에게 적용됩니다.
- 로고 — png/svg/jpg/webp · 512KB 이하. 사이드바·로그인 화면·갤러리에 적용됩니다. 기본 복원 으로 되돌립니다.
- 제품 표시명 — 비워두면
PlantPulse Studio로 표시됩니다.
로고는 정사각형에 가까운 투명 배경 PNG/SVG 가 가장 깔끔합니다(사이드바에서 24px 로 축소 표시).
AI 프로바이더 (fa-microchip-ai)
무엇에 영향을 주나 — 채팅 답변과 앱 생성 전체. 여기가 비어 있으면 아무것도 동작하지 않습니다.
프로바이더는 세 가지 중 선택하며, 각각 모델·Base URL·키를 따로 기억합니다. 전환해도 이전 설정이 남습니다.
| 프로바이더 | 모델 입력 예 | Base URL |
|---|---|---|
| Anthropic (Claude) | claude-fable-5 · claude-opus-4-8 · claude-sonnet-5 | 입력 없음 |
| OpenAI | gpt-4o · gpt-4.1 · o3 | 선택(기본 https://api.openai.com/v1) |
| OpenAI-Compatible | 서버가 제공하는 모델명 | 필수 — 예 http://vllm-host:8000/v1 |
- API Key — 이미 저장돼 있으면
설정됨배지가 뜨고, 비워두면 기존 키가 유지됩니다. - 연결 테스트 (
fa-plug-circle-check) — 지금 화면에 입력한 값으로 프로바이더에 실제로 붙어 봅니다. 저장 전에 눌러도 되고, 저장할 필요도 없습니다. 성공하면 초록 체크, 실패하면 빨간 표시와 함께 사유가 옆에 뜹니다.
예전에는 플랫폼 탭에만 이 버튼이 있어서, AI 탭은 값을 넣고 저장한 뒤 채팅을 해 봐야 맞는지 알 수 있었습니다. 이제 저장 전에 확인됩니다 — 주소 오타·만료된 키·게이트웨이 다운을 여기서 바로 가릅니다.
폐쇄망에서는 OpenAI-Compatible 로 사내 vLLM/Ollama 게이트웨이를 지정하면 외부 통신 없이 운영할 수 있습니다.
에이전트 동작 (fa-robot)
무엇에 영향을 주나 — 에이전트가 앱을 만드는 방식과 결과물의 일관성.
- 기본 프롬프트 (운영자 추가 지침) — 모든 대화의 시스템 프롬프트 뒤에 붙습니다(최대 4000자). 사내 규칙·선호 라이브러리·화면 스타일 지침을 적으세요. 예: "모든 화면 상단에 회사 로고를 넣어라. 차트 색상은 네이비 계열로 통일하라."
- 빌더 엔진 —
내장 엔진 (기본)/OpenHands 사이드카 (추천). 앱 빌드에만 영향을 주고 채팅(질의)에는 영향이 없습니다. 사이드카가 설치된 환경이라면 OpenHands 쪽이 복잡한 수정에 강합니다. - 비전 자가검증 — 턴이 끝날 때 화면 스크린샷을 AI 가 검토해 레이아웃 문제를 스스로 고칩니다. 품질이 올라가는 대신 토큰 소모가 늘어납니다.
- 턴당 최대 도구 스텝 — 4~48, 기본 24. 한 번의 요청에서 에이전트가 파일을 읽고 고치는 횟수 상한입니다. 복잡한 앱에서 "최대 단계 초과"가 자주 뜨면 32 정도로 올리세요.
- 응답 최대 토큰 — 1,000~200,000, 기본 128000. 너무 낮추면 긴 코드가 중간에 잘립니다.
빌드 표준
생성 앱의 기술 스택·레이아웃을 고정해 에이전트가 임의로 벗어나지 못하게 막습니다. 표준 스택(React + Vite · TypeScript · ECharts 래퍼 · TanStack Query · AppShell/Grid/Section · HashRouter)은 읽기 전용으로 표시됩니다.
- 의존성 잠금 — 새 npm 패키지 설치를 차단합니다. 켜두는 것을 권장합니다(폐쇄망에서는 설치가 실패해 빌드가 깨집니다).
- 레이아웃 규약 강제 — 모든 화면이 공통
AppShell을 쓰도록 검증하고, 어기면 에이전트가 스스로 고칩니다. - 허용 예외 패키지 — 쉼표로 구분(예:
leaflet, framer-motion). 잠금 중에도 이 목록은 설치를 허용합니다. - 앱 기본 레이아웃 (신규 앱) — 제품명·헤더 색(예
#0e2a4e)·최대 폭(px, 기본 1280)·푸터 문구. 새로 만드는 앱에만 적용되고 기존 앱에는 소급되지 않습니다.
런타임 (서버 전역) (fa-server)
무엇에 영향을 주나 — 서버 자원과 앱 접속 주소. 전 사용자 공통입니다.
- 동시 실행 앱 한도 — 1~32, 기본 8. 동시에 떠 있을 수 있는 개발 세션 수입니다. 서버 메모리에 맞춰 정하세요(세션 하나당 개발 서버 한 개).
- 유휴 자동 정지 (분) — 0~1440, 기본 30. 그 시간 동안 아무 작업이 없으면 세션을 정지시켜 자원을 회수합니다. 0 = 자동 정지 안 함. 정지돼도 작업물은 그대로 보존되며 다시 열면 이어집니다.
2026-08-23 이전 버전에는 이 탭에 프리뷰·배포앱의 공개 URL 을 지정하는 앱 오리진 항목이 있었습니다. 지금은 앱이 스튜디오와 같은 도메인의 /container/ 아래에서 서빙되므로 지정할 것이 없습니다.
옛 화면 안내를 보고 이 항목을 찾고 있었다면 도메인과 리버스 프록시 를 보세요.
앱 이미지 레지스트리
배포 버전을 컨테이너 이미지로 빌드해 push 할 대상입니다. 빌더 배포 드로어의 이미지 push 가 이 설정을 사용하며, 비어 있으면 해당 버튼이 "설정되지 않았습니다" 안내를 띄웁니다.
- 레지스트리 URL(예
registry.kopens.io) · 네임스페이스(예plantpulse-apps) · 사용자명 · 액세스 토큰 - 토큰이 이미 저장돼 있으면
저장됨 — 변경 시에만 입력이 표시됩니다.
플랫폼 연동 (fa-plug)
무엇에 영향을 주나 — 실데이터. 이 키가 없으면 사이트·자산·태그를 조회할 수 없어 앱이 가짜 데이터로 만들어집니다.
- 플랫폼 API 키 — 플랫폼에서 발급한
X-API-Key를 넣습니다. 이미 있으면설정됨, 환경변수로 주입됐다면환경변수로 관리 중으로 잠깁니다. - 연결 테스트 — 저장 전에 키가 유효한지 즉시 확인합니다. 성공하면
연결됨, 실패하면 사유가 그대로 표시됩니다.
플랫폼 연결 상태는 화면 하단 상태바에서 항상 확인할 수 있습니다(연결됨 / 응답 이상 / 단절).
Git 연동 (fa-code-branch)
무엇에 영향을 주나 — 만든 앱의 소스를 고객사 저장소에 보관할지 여부.
- GitLab / GitHub 선택 — GitHub 을 고르면 서버 URL 이
https://github.com으로 고정됩니다. - 서버 URL(예
https://gitlab.example.com) · 네임스페이스 (그룹/조직)(예myorg/apps) - 사용자명 (선택) — 비워두면 기본값
oauth2로 인증합니다. - 액세스 토큰 —
glpat-…/ghp_…. 저장돼 있으면 비워둘 때 기존 값이 유지됩니다. - 배포 시 자동 푸시 — 앱을 배포할 때마다 원격 Git 프로젝트로 함께 푸시합니다. 형상관리가 필요한 조직이라면 켜두세요.
MCP (fa-diagram-project)
무엇에 영향을 주나 — 에이전트가 쓸 수 있는 도구의 범위.
MCP 서버의 도구를 에이전트에 노출합니다. 내장 플랫폼 서버 외에 외부 MCP 서버(Streamable HTTP) 를 추가할 수 있고, 새로 생긴 도구는 자동으로 반영됩니다(기본 켜짐).
- 서버 목록 — 각 줄에 상태 LED·이름·주소·
도구 n개·활성 체크박스. 내장 서버에는내장배지가 붙습니다. 줄을 클릭하면 아래에 그 서버의 도구 목록이 열립니다. - MCP 서버 추가 — ID·이름·URL·인증 헤더·토큰을 입력합니다.
- 도구별 노출 — 도구마다 활성 / 채팅 / 빌더 세 개를 따로 끌 수 있습니다. 채팅에서만 쓰고 빌드에서는 막고 싶을 때 유용합니다.
- 도구 다시 발견 — 외부 서버에 도구를 추가했는데 목록에 안 보이면 누르세요. "발견된 도구가 없습니다" 가 뜨면 서버 연결을 확인합니다.
- 충돌 — 다른 서버에 같은 이름의 도구가 있으면 먼저 등록된 쪽이 우선하고, 뒤쪽은 노출되지 않습니다.
외부 MCP 서버 주소는 끝에 슬래시가 있어야 합니다(예 https://host/mcp/). 빠뜨리면 연결에 실패합니다.
사용자 관리
사이드바 fa-users 로 들어갑니다. 표에 아이디 · 이름 · 역할 · 출처 · 생성일 이 나옵니다.
역할은 세 가지입니다.
| 역할 | 할 수 있는 일 |
|---|---|
| 관리자 | 전부 — 환경설정·사용자 관리·통계 포함 |
| 빌더 | 앱 생성·수정·배포, 와처·스킬 관리 |
| 뷰어 | 조회 전용 — 앱 생성 불가("뷰어 권한은 앱을 생성할 수 없습니다") |
출처가 환경변수 인 계정은 서버 설정으로 만들어진 것이라 화면에서 수정·삭제할 수 없습니다. 스튜디오 계정만 다음이 가능합니다.
- 사용자 추가 — 아이디·비밀번호·이름·역할 입력
- 역할 변경 · 비밀번호 재설정(6자 이상) · 삭제
- 목록의 사진을 클릭하면 아바타 이미지를 바꿀 수 있습니다
통계
사이드바 fa-chart-column 로 들어갑니다. 기간은 7일 / 30일 / 90일 중에서 고릅니다.
상단 KPI 다섯 개: 전체 앱 · 배포된 앱 · 대화 · 활성 스킬 · 플랜트 규모(사이트 수·태그 수).
| 탭 | 보는 내용 |
|---|---|
| AI 사용량 | 에이전트 턴·입력/출력 토큰, 일별·사용자별·프로젝트별, 빌더 엔진 비교 |
| 활동 | 일별 활동(액션별), 활동 많은 사용자, 최근 주요 이벤트 |
| 앱 | 신규 앱 추이, 배포 상태, 배포 버전 상위 앱, 템플릿 사용 순위 |
| 채팅 | 일별 질문 수, 질문 많은 사용자 |
| 배포 | 배포 시도·성공·실패, 일별 성공/실패, 최근 배포 이력 |
| 감사 로그 | 시간·사용자·액션·대상·상세 (검색 지원) |
AI 사용량 에서 토큰이 급증했다면 와처 주기가 너무 짧거나 '비전 자가검증'이 켜진 채 대량 빌드가 돌았을 가능성이 큽니다. 배포 탭의 실패 건수는 트러블슈팅과 함께 확인하세요.