관리자 설명서

관리자 계정(admin 그룹)으로 로그인하면 화면 오른쪽 위에 ⚙ 관리자 설정 버튼이 생깁니다. 관리 권한을 위임받은 역할의 사용자에게도 보이며, 그 사용자는 맡은 탭·기능만 쓸 수 있습니다. 이 설명서는 관리자 설정의 메뉴 12개를 화면 순서대로 안내합니다. 설치와 .env 설정은 시작하기를 보세요.

화면 캡처는 개발 서버에서 찍었고, 사람 이름·아이디·이메일·기기 이름·서버 주소·키는 예시 값으로 가렸습니다.

처음 설정 순서

새로 설치한 뒤에는 아래 순서로 설정하면 사용자가 바로 채팅할 수 있습니다.

1. 프로바이더 연결: LLM 서버를 연결하고 모델을 감지합니다.
2. 그룹 · 권한: 기본 그룹 user·admin과 역할을 확인합니다.
3. 사용자: 사용자 역할과 허용 모델을 정합니다.
4. 설정에서 조직 기본 모델을 정하고, 그룹마다 다르게 쓰려면 그룹 · 권한에서 그룹 기본 모델을 정합니다.
5. 필요하면 모델 프리셋, 설정(로그인 방식·공지), API 게이트웨이(한도), 금액 한도를 정합니다.

관리자 설정 화면 위쪽에 메뉴가 탭으로 있고, 왼쪽 위 ← 채팅으로를 누르면 채팅 화면으로 돌아갑니다.

프로바이더 연결

Evo Chat이 답변에 쓰는 LLM 서버(프로바이더)를 연결합니다.

• + 연결 등록: 새 연결을 추가합니다. 종류(예: OpenAI 호환 커스텀 엔드포인트), 접속 주소(/v1까지), API 키를 입력합니다.
• 등록한 연결 카드의 버튼:
  • 모델 감지: 그 서버의 모델 목록을 가져옵니다.
  • 모델 보기: 감지된 모델을 확인합니다. 모델마다 이미지 표시를 켜면 그 모델에 채팅 첨부 이미지를 그림으로 보냅니다. 기본은 꺼짐이며, 연결의 모델 정보로 실제 이미지 입력 지원을 확인한 뒤 켭니다. 받지 못하는 모델에 켜면 모델 호출이 오류가 날 수 있습니다.
  • 수정 / 삭제
• API 키와 접속 주소의 자격증명 부분은 저장한 뒤 다시 표시되지 않습니다.
• 설치할 때 .env의 OPENAI_COMPATIBLE_* 값을 넣었다면, 첫 기동 때 연결 하나가 자동으로 등록됩니다.

모델 프리셋

프리셋은 기반 모델 + 시스템 프롬프트 + 파라미터를 묶은 것입니다. 등록하면 사용자 입력창의 모델 선택 목록에 프리셋 묶음으로 나타납니다.

• + 프리셋 등록으로 만듭니다.
• 프리셋을 볼 수 있는 그룹은 그룹 · 권한 아래쪽 프리셋 접근 권한에서 정합니다(기본은 비공개).

그룹 · 권한

그룹

• 기본 그룹은 admin과 user이며 삭제할 수 없습니다. 로그인하려면 둘 중 하나에 속해야 합니다.
• 새 그룹 이름을 입력하고 추가로 그룹을 만듭니다. 각 그룹 옆에 출처(oidc·local)와 인원이 표시됩니다.
• 그룹 이름을 누르면 그 그룹의 구성원, 쿼터, 월 사용 금액 한도, 허용 모델, 그룹 기본 모델을 정하는 칸이 펼쳐집니다.
• SSO(OIDC) 계정의 그룹 소속은 조직 계정 시스템(Keycloak)의 같은 이름 그룹과 맞춰집니다. 앱에서 SSO 계정을 그룹에 넣고 빼면 Keycloak 쪽에도 반영되고, 앱이 Keycloak에 그룹을 새로 만들지는 않습니다.

역할

• 역할은 기능(채팅, 대화 기록, 프리셋) 허용을 묶은 것입니다.
• 사용자의 역할(직접 부여한 역할 + 소속 그룹의 역할) 중 하나라도 허용하면 쓸 수 있고, 아무 역할도 허용하지 않으면 차단됩니다.
• 기본 역할 basic은 수정·삭제할 수 없습니다. admin 그룹은 역할과 관계없이 모든 권한을 가집니다.
• 새 역할 이름을 쓰고 허용할 기능을 체크한 뒤 역할 추가를 누릅니다.
• 관리 권한: 역할에 관리 화면의 일부를 맡길 수 있습니다. 예를 들어 사용자 조회, 한도 관리(예산·쿼터), 사용량 조회, 감사 로그 조회처럼 탭·기능별로 체크합니다. “…관리”는 같은 영역의 조회를 포함합니다. 조회 권한만 받은 사람에게는 그 화면이 읽기 전용으로 보입니다.
• 역할 편집·부여, 연결·게이트웨이·MCP·스킬·관측성·설정 변경, admin 그룹 구성원 변경, admin 계정 변경은 admin만 할 수 있습니다.

허용 모델과 그룹 기본 모델

• 허용 모델: 체크한 모델만 이 그룹 회원이 쓸 수 있습니다(기본은 모두 차단). admin 그룹은 활성 모델 전체에서 고릅니다.
• 그룹 기본 모델: 이 그룹 사용자가 모델을 고르지 않았을 때 쓰는 모델입니다. 허용 모델 가운데에서 고르며, **없음(조직 기본)**이면 설정의 조직 기본 모델을 씁니다.
• 우선순위: 사용자가 여러 그룹에 속하면 우선순위가 높은 그룹의 기본 모델이 먼저 적용되고, 같으면 그룹 이름 순입니다.
• 정하고 나서 허용 모델·기본 모델 저장을 누릅니다. 저장된 상태에 설정 안 됨·적용 중·적용 안 됨(꺼진 모델)이 표시됩니다. 기본 모델을 허용 모델에서 빼고 저장하면 기본 모델도 해제됩니다.

기본 모델이 정해지는 순서는 다음과 같습니다.

1. 사용자가 직접 고른 모델
2. 우선순위가 가장 높은 그룹의 그룹 기본 모델
3. 조직 기본 모델
4. 위가 모두 없으면 쓸 수 있는 첫 모델

프리셋 접근 권한: 프리셋마다 볼 수 있는 그룹을 정합니다. 정하지 않은 프리셋은 보이지 않습니다.

사용자

• 위쪽 검색창에 아이디·표시명·이메일을 넣고 검색합니다.
• 표에서 표시명, 이메일, 계정 구분(user/admin), 활성 여부를 바꾸고 그 줄의 저장을 누릅니다.
• 줄마다 있는 버튼:
  • 역할: 이 사용자에게 직접 부여할 역할을 정합니다.
  • 허용 모델: 이 사용자가 쓸 수 있는 모델을 정합니다. 모델 선택 목록에는 허용된 모델만 보입니다. 이 사용자가 모델을 고르지 않았을 때 쓰일 기본 모델과 그 출처(그룹 또는 조직 기본)도 함께 보입니다.
  • 쿼터: 사용자별 월 토큰·요청 상한을 정합니다.
  • 금액 한도: 사용자별 월 사용 금액 한도를 정합니다. 아래 월 사용 금액 한도를 보세요.
  • 비밀번호(로컬 계정만): 비밀번호를 재설정합니다.
• 사용자 삭제: 비활성화된 계정만 지울 수 있습니다. 활성을 끄고 저장한 뒤 나타나는 삭제를 누르고, 확인 창에서 영구 삭제를 누릅니다. 되돌릴 수 없으며, 그 사용자의 대화·피드백·API 키·CLI 키(LLM 게이트웨이 키 포함)가 함께 지워집니다. 사용량 통계는 사용자 정보 없이 **(삭제된 사용자)**로 남습니다. SSO 계정은 조직 계정 시스템(Keycloak)에서 따로 지워야 하며, 지우지 않은 계정으로 다시 로그인하면 새 계정이 만들어집니다.
• 이 화면에서 계정을 새로 만들지는 않습니다. SSO·LDAP 계정은 처음 로그인할 때 생기고, 첫 관리자 계정은 설치할 때 .env로 만들어집니다.

월 사용 금액 한도

웹 채팅과 Evo CLI를 합친 한 달 사용 금액의 상한입니다. LLM 게이트웨이(LiteLLM)의 모델 단가로 계산하며, 통화는 보통 USD이고 소수 둘째 자리까지 넣습니다.

• 사용자 줄의 금액 한도 또는 그룹을 펼친 칸의 월 사용 금액 한도에 금액을 넣고 금액 한도 저장을 누릅니다.
• 비우면 미설정입니다. 사용자 값이 없으면 그룹 값을 따르고, 그룹 값도 없으면 제한이 없습니다. 0은 전면 차단입니다.
• 사용자 값이 있으면 그 값이 우선하고, 여러 그룹에 속하면 가장 좁은(작은) 그룹 값이 적용됩니다.
• 아래에 적용 한도(값과 출처)와 게이트웨이의 누적 금액이 보입니다.
• 한도에 닿은 사용자는 채팅할 때 “이번 달 사용 금액 한도에 도달해 채팅할 수 없습니다”를 보게 됩니다.
• LLM 게이트웨이 연동(CLI_LITELLM_*)이 설정되어 있지 않으면 “금액 한도가 적용되지 않습니다”가 표시되고 한도는 적용되지 않습니다. 관련 설정은 시작하기의 evo CLI 연동 표를 보세요.

CLI 키

Evo CLI가 조직 로그인으로 받은 사람별 LLM 키의 기록입니다. Evo CLI는 이 키로 LLM 게이트웨이를 직접 호출합니다.

• 표에 사용자, 기기(device), alias, 발급·만료 시각이 나옵니다. 만료된 키는 **(만료됨)**으로 표시됩니다.
• 키 원문은 보관하지 않아 표시되지 않습니다.
• 폐기를 누르면 게이트웨이의 키가 삭제되고, 그 CLI는 다음 호출 때 다시 로그인해야 합니다.
• 위쪽 사용자 이름으로 걸러 보고 새로 고침으로 다시 불러옵니다.

사용량

• 기간(시작일·종료일), 사용자 아이디, 그룹, 모델로 걸러 조회합니다.
• 위쪽에 응답 수와 입력·출력 토큰 합계, 아래 표에 사용자·모델별 응답 수와 토큰이 나옵니다.
• 토큰은 프로바이더가 사용량을 보고한 응답만 합산합니다(보고하지 않은 응답은 응답 수에만 포함, 추정치는 만들지 않음).
• 줄마다 있는 기록을 누르면 그 사용자의 웹·CLI 사용 기록을 내 기록과 같은 화면으로 봅니다. 질문·답변 내용은 보이지 않습니다. 관측성(Langfuse) 연동이 켜져 있어야 합니다.

감사 로그

• 모델 선택, 도구 호출, CLI 키 발급·삭제 같은 주요 동작이 기록됩니다.
• 채팅 모델 선택(chat.routing)에는 수동 선택인지, 자동 라우팅이면 어떤 이유로 그 모델을 골랐는지가 함께 남습니다.
• 유형과 **행위자(아이디)**로 걸러 조회합니다.
• 감사 기록은 추가만 되고 수정·삭제할 수 없습니다.

API 게이트웨이

사용자가 설정 - API 키에서 발급한 키로 쓰는 API를 관리합니다.

• 게이트웨이 차단: 비상 시 모든 API 키의 인증을 즉시 거부합니다. 채팅 화면에는 영향이 없습니다.
• 전역 기본 쿼터 · 발급 상한: 월 토큰 상한, 월 요청 상한(비우면 무제한), 사용자당 활성 키 상한을 정하고 저장합니다. 그룹·사용자·키에 정한 상한은 각각 따로 적용됩니다.
• 아래에 이번 달 전체 API 사용량이 보입니다.

MCP 서버

채팅 모델이 쓸 외부 도구 서버(MCP)를 관리합니다.

• 등록 정책: 허용 호스트를 한 줄에 하나씩 적으면 그 호스트의 서버만 등록할 수 있습니다(비우면 제한 없음). stdio 전송 허용은 기본으로 꺼져 있습니다. 채팅 백엔드 호스트에서 프로세스를 실행하기 때문입니다.
• 서버 등록으로 MCP 서버를 추가합니다.

스킬

사용자가 입력창에서 $로 불러 쓰는 스킬을 배포합니다.

• 표준 SKILL.md 형식의 스킬을 zip 파일(오프라인 설치)로 올리거나, 내용을 붙여넣어 배포합니다. 스크립트 파일은 저장·실행되지 않습니다.
• 사용할 수 있는 그룹을 고릅니다(고르지 않으면 관리자만 사용).
• 아래 배포된 스킬에서 목록을 확인합니다.

관측성

채팅 요청, 모델 호출(토큰·첫 토큰 지연), 도구 호출, 자동 라우팅 결정을 Langfuse로 보냅니다(OpenTelemetry). 꺼도 채팅은 정상 동작합니다.

• 연동 사용을 켜고 Langfuse 주소, Public key, Secret key를 넣습니다. Secret key는 설정된 뒤 비워 두면 그대로 유지됩니다.
• 샘플링 비율(0~1, 1이면 전부)과 환경 이름을 정합니다.
• 캡처 수위를 고릅니다.
  • 메타데이터만(기본·권장): 모델·토큰·지연·라우팅 결과만 보냅니다.
  • 내용 포함(PII 마스킹): 프롬프트·응답을 보내되 이메일·전화·주민번호·카드·키를 가립니다(패턴 기반이라 완전하지 않음).
  • 원문 전체: 그대로 보냅니다. 개인정보가 Langfuse에 저장될 수 있습니다.
• 저장하면 바로 반영되고, 접속 테스트로 저장된 설정을 확인합니다.

Langfuse 화면에 관리자 로그인

Evo Chat 관리자가 같은 Keycloak 계정으로 Langfuse 화면(트레이스·사용 기록)에 들어가게 할 수 있습니다. Evo Chat 앱 설정은 바뀌지 않고, Keycloak 담당과 Langfuse 운영자가 설정합니다. Langfuse 자체 호스팅 무료판(OSS) 기준입니다.

Keycloak 쪽(Evo Chat이 쓰는 렐름)

1. 클라이언트 langfuse를 만듭니다. 기밀 클라이언트(Client authentication On), Standard flow만 켜고, Valid redirect URI는 Langfuse 웹 주소 뒤에 /api/auth/callback/keycloak을 붙인 주소 한 줄, scope는 openid email profile입니다.
2. 클라이언트 역할 langfuse-admin을 만들어 admin 그룹에 매핑합니다.
3. 이 클라이언트 전용 브라우저 흐름을 만들어 “langfuse-admin 역할이 없으면 접근 거부” 조건을 넣고, 클라이언트의 Browser flow로 지정합니다. 무료판 Langfuse는 로그인한 누구나 조직을 만들 수 있으므로, 들어올 수 있는 사람을 이 단계에서 admin 그룹으로 줄입니다.
4. 렐름 셀프 가입은 끄고, 메일 발송(SMTP)을 설정한 뒤 **이메일 확인(Verify email)**을 켭니다. Langfuse가 같은 이메일 계정을 하나로 합치므로 이메일 소유 확인이 필요합니다.

Langfuse 쪽: 아래 환경 변수를 더하고 Langfuse web을 다시 시작합니다.

환경 변수	값
AUTH_KEYCLOAK_CLIENT_ID	langfuse
AUTH_KEYCLOAK_CLIENT_SECRET	클라이언트 비밀(Langfuse 환경 변수에만 둡니다)
AUTH_KEYCLOAK_ISSUER	Keycloak 웹 주소 뒤에 /realms/와 Evo Chat이 쓰는 렐름 이름을 붙인 주소
AUTH_KEYCLOAK_ALLOW_ACCOUNT_LINKING	true(같은 이메일의 기존 Langfuse 계정에 합침)
AUTH_DISABLE_USERNAME_PASSWORD	true(이메일·비밀번호 가입과 로그인을 막음)

• AUTH_DISABLE_SIGNUP, NEXT_PUBLIC_SIGN_UP_DISABLED는 쓰지 않습니다. 모든 로그인 방법의 새 계정 생성을 막아 처음 오는 관리자가 들어오지 못합니다.
• 적용 전에 이메일·비밀번호로만 로그인하는 Langfuse 계정이 없는지 확인합니다.

권한 관리: 무료판 Langfuse는 Keycloak 그룹을 Langfuse 역할에 연결하지 않으므로, 접근과 권한을 따로 관리합니다.

• 들어올 수 있는지: Keycloak admin 그룹(위 3번)
• 무엇을 볼 수 있는지: Langfuse 조직 설정 → Members에서 조직 관리자가 초대하고 역할(Owner·Admin·Member·Viewer)을 줍니다.
• 새 관리자는 Keycloak admin 그룹에 넣은 뒤(이메일 검증 확인) Langfuse의 Keycloak 버튼으로 한 번 로그인하게 하고, 그다음 초대합니다.
• 관리자를 뺄 때는 Keycloak admin 그룹과 Langfuse Members 양쪽에서 지웁니다.
• Evo Chat 관리자는 아니지만 Langfuse만 봐야 하는 사람에게는 그룹을 새로 만들지 말고 클라이언트 역할 langfuse-admin만 직접 줍니다.

작업 공간 (웹 workflow)

작업 공간은 대화가 프로젝트 저장소를 clone해 파일을 읽고 고치며, git 브랜치·커밋·push와 GitLab 이슈·MR 작업까지 하게 해 주는 기능입니다. 기본은 꺼짐이고, 켜지 않으면 기존 채팅·API 동작은 그대로입니다. 상세 절차는 작업 공간 배포, 작업 공간 실행기, 작업 공간 도구, 작업 공간 관리, GitLab 토큰을 함께 보세요.

켜는 조건

다음이 모두 있어야 사용자가 작업 공간 도구를 쓸 수 있습니다. 하나라도 빠지면 모델에 작업 공간 도구가 보이지 않습니다.

1. .env의 WORKSPACE_ENABLED=true
2. 실행기 주소·토큰(WORKSPACE_RUNNER_URL, WORKSPACE_RUNNER_TOKEN) 설정
3. evo-workspace 이미지 준비와 EVOMIND_WORKSPACE_IMAGE 설정
4. 사용자(또는 소속 그룹 역할)에 workspace 기능 권한

이미지 준비와 번들

• 이미지는 docker/workspace/tools.lock에 고정된 도구로 만듭니다. 빌드는 sh scripts/workspace/build.sh evo-workspace:local, 검사는 sh scripts/workspace/test-image.sh evo-workspace:local입니다. 이미지에는 git·glab·evo-workflow와 workspace-runner가 들어가고, 컴파일러·패키지 관리자·curl·wget·nc·ssh는 없습니다.
• 태그는 develop에서 evo-workspace:<X.Y.Z>-dev.<N>, 릴리스 태그 vX.Y.Z에서 evo-workspace:<X.Y.Z>로 붙습니다. latest 태그는 없고 같은 버전 이미지를 덮어쓰지 않습니다.
• 번들에 작업 공간 이미지를 넣으려면 번들 빌드 때 WORKSPACE_IMAGE=<evo-workspace 이미지 참조>를 지정합니다. 번들에 images/evo-workspace.tar와 images/WORKSPACE_IMAGE가 들어가고, 설치·업그레이드가 이미지를 load한 뒤 .env의 EVOMIND_WORKSPACE_IMAGE를 채웁니다. 이미지가 없으면 이 기능을 켤 수 없습니다.

기능 권한

workspace는 기능 권한 중 하나이며 기본 역할에 들어 있지 않습니다(기본 꺼짐). 그룹 · 권한에서 역할을 만들거나 고칠 때 workspace를 체크하면 그 역할을 가진 사용자가 쓸 수 있습니다. admin 그룹은 항상 쓸 수 있습니다.

.env 설정

값은 이 문서에 적지 않습니다. 비밀값은 .env에만 두세요.

항목	기본	의미
WORKSPACE_ENABLED	false	기능 전체 스위치
WORKSPACE_GITLAB_HOST	비움	clone·push 대상 GitLab 주소(https). 계정 메뉴의 토큰 상태 표시에도 쓰입니다
WORKSPACE_TOKEN_KEY	비움	사용자별 토큰 암호화 키(base64, AES-GCM). 16·24·32바이트를 받으며 32바이트를 권장합니다(openssl rand -base64 32)
WORKSPACE_GITLAB_TOKEN	비움	사용자별 등록을 쓰지 않고 공용 토큰 하나로 운영할 때의 토큰
WORKSPACE_GITLAB_USER_NAME, WORKSPACE_GITLAB_USER_EMAIL	비움	공용 토큰으로 커밋할 때의 작성자 이름·메일
WORKSPACE_GITLAB_TOKEN_EXPIRES_AT	비움	공용 토큰 만료일(ISO-8601, 날짜만)
WORKSPACE_TOKEN_EXPIRY_WARNING	14d	토큰 만료 임박 경고 기간
WORKSPACE_RUNNER_URL	비움	API가 부르는 실행기 주소(compose 구성에서는 http://workspace-gateway:8090)
WORKSPACE_RUNNER_TOKEN	비움	실행기 서비스 토큰(32자 이상)
WORKSPACE_RUNNER_TIMEOUT	180s	실행기 호출 한 번의 대기 상한
WORKSPACE_MAX_FILE_WRITE_BYTES	262144	모델이 파일 하나에 쓸 수 있는 최대 바이트
WORKSPACE_ALLOWED_GIT_HOSTS	비움	clone을 허용할 GitLab 호스트. 호스트 이름만 쉼표로 적으며 :443으로만 나갑니다. 비우면 clone을 모두 거절합니다
WORKSPACE_HTTP_PROXY	비움	작업 공간 도구가 쓰는 프록시(compose 구성에서는 http://workspace-egress:3128)
WORKSPACE_USER_QUOTA_BYTES	10737418240 (10GiB)	사용자당 디스크 할당량. 0이면 검사하지 않습니다
WORKSPACE_EXEC_TIMEOUT_SEC	120	실행 한 번의 시간 상한(초)
WORKSPACE_MAX_OUTPUT_BYTES	262144	실행 출력 상한(바이트)
WORKSPACE_MAX_PROCESSES	128	실행당 프로세스·스레드 수
WORKSPACE_MAX_FILE_BYTES	1073741824 (1GiB)	실행이 쓸 수 있는 파일 하나의 크기
WORKSPACE_MEMORY_LIMIT	2g	작업 공간 컨테이너 메모리 상한
WORKSPACE_CPUS	2	작업 공간 컨테이너 CPU 상한
WORKSPACE_PIDS_LIMIT	512	작업 공간 컨테이너 프로세스 상한
WORKSPACE_PROTECTED_BRANCHES	main,master,develop,release/*	push를 거절할 보호 브랜치(정확히 일치 또는 접두/*)

EVOMIND_WORKSPACE_IMAGE는 설치·업그레이드가 채우는 이미지 참조입니다. 손으로 채울 때는 릴리스 이미지 태그(evo-workspace:0.7.0처럼 X.Y.Z)를 씁니다.

사용량과 초기화

• 사용자 표의 각 줄에 작업 공간 단추가 생깁니다. 펼치면 상한(기본 10GiB) 대비 사용량, 파일·폴더·링크 수, 프로젝트·worktree별 크기가 보이고 줄마다 삭제할 수 있습니다.
• 초기화는 확인 대화상자를 거친 뒤 그 사용자의 작업 공간만 지웁니다. 계정, GitLab 토큰, 에이전트 ID 등록은 그대로 남습니다. 실행 중이면 409로 거부하고, 그 밖의 실패는 502이며 실패하면 아무것도 지우지 않습니다.
• 사용량 조회는 admin.users.read, 초기화는 admin.users.manage 관리 권한이 필요합니다. 초기화는 감사 로그에 workspace.reset으로 남습니다.

계정 삭제·업그레이드

• 관리자가 계정을 삭제하면 그 사용자의 작업 공간도 함께 지웁니다(작업 공간 번호가 없거나 기능이 꺼져 있으면 건너뜀). 작업 공간을 지우지 못하면 502로 끝나고 대화·키·사용자 행은 그대로 남습니다. 비활성화는 작업 공간을 지우지 않으며, 삭제할 때까지 남습니다.
• 작업 공간용 DB 마이그레이션(V27~V31)은 앱이 기동할 때 Flyway가 번호 순으로 자동 적용합니다. 중간 버전을 거칠 필요가 없습니다.

보안과 제한

• 사람 확인으로만 실행: 이슈 게시, 에이전트 ID 등록, MR 머지는 모델이 미리보기까지만 만들고, 로그인한 사람이 화면에서 확인해야 서버가 실행합니다. 모델 도구에는 이 실행 경로가 열리지 않습니다. 이슈 초안은 30분 뒤 만료됩니다.
• 도구별 승인: 파일 쓰기, git 변경(브랜치 만들기·stage·commit·push), MR 생성, 이슈 게시는 승인 창을 거치고, 읽기·조회 도구는 승인 없이 실행됩니다. 120초 안에 응답이 없거나 거부되면 실행하지 않습니다.
• 감사: 앱 감사에 도구·동작·승인 여부·결과·오류 코드만 남고, 경로·인자·파일 내용·토큰은 남기지 않습니다. 실행기 감사는 표준 출력 한 줄 JSON이며 오래 보관하지 않습니다.
• git 제한: 보호 브랜치에는 push하지 못하고, 대화 작업 브랜치는 chat/<대화 id>로 정해집니다. 이 거절은 앞단 방어이며, 최종 방어선은 GitLab의 보호 브랜치 설정과 사용자 토큰 권한입니다.
• 외부 접속: clone은 WORKSPACE_ALLOWED_GIT_HOSTS에 적은 호스트의 :443으로만 나갑니다. GitLab이 다른 포트를 쓰면 이 배포 구성으로는 clone할 수 없습니다.
• 디스크: 사용량이 상한을 넘으면 실행·clone·worktree·파일 쓰기를 507 disk_quota로 거절합니다. 파일 삭제와 초기화는 상한을 넘어도 허용됩니다. 상한은 파일 시스템 쿼터가 아니라 사용량 합산 검사입니다.

웹 검색·웹 페이지 읽기

모델이 웹을 검색하고 공개 페이지를 읽는 도구는 별도 MCP 서버 등록 없이 evo-api에 들어 있고 기본은 켜짐입니다. 설정 화면이 아니라 .env(개발서버는 인스턴스별 CI/CD File 변수)에 넣고 다시 배포해야 바뀝니다.

• WEB_SEARCH_ENABLED(기본 true): 검색·페이지 읽기 두 도구를 모두 끕니다.
• WEB_SEARCH_TOOLS(기본 tavily,searxng,duckduckgo): 검색 중계에 묻는 도구 순서.
• WEB_SEARCH_MAX_PER_TURN(기본 5, 최대 20): 응답 1건의 검색 횟수 상한.
• WEB_FETCH_ENABLED(기본 true): 페이지 읽기만 끕니다.

검색은 그 답변에 쓰는 모델 연결(openai_compatible = LiteLLM)의 주소·키로 POST /v1/search/{도구}를 부릅니다. 연결 키가 이 경로를 허용해야 하며, 키 설정은 LiteLLM 담당에게 요청합니다. 연결이 LiteLLM이 아니면 검색은 열리지 않고 페이지 읽기만 열립니다.

세션 작업 요청의 종단간 암호화는 DISPATCH_E2E_ENABLED(기본 true)로 켜고 끕니다. 끄면 공개키를 싣지 않고 세션 요청을 보낼 수 없으며(평문 받기만 됨), “평문으로 보내기” 경로는 없습니다. 기기 개인키를 감싸는 DISPATCH_E2E_KEY_SECRET은 비우면 JWT 서명 비밀에서 유도하고, 바꾸면 그 전에 온 안 읽은 암호 메시지를 읽을 수 없습니다.

도구 실행 흔적은 응답을 저장할 때 message_tool_events 표(V36)에 함께 남습니다. 남기는 항목은 서버·도구 이름·상태·짧은 요약(최대 400자)·검색 출처 링크뿐이고, 도구 인자와 결과 본문은 저장하지 않습니다. 메시지를 지우면 흔적도 함께 지워지며, 이 기능 전에 저장된 메시지에는 흔적이 없습니다.

설정

• 보안 설정 - 로컬(아이디·비밀번호) 로그인 허용: 끄면 SSO(OIDC)와 LDAP 로그인만 쓸 수 있습니다.
• LDAP 연결: LDAP URL(예: ldap://ldap:389), Base DN, 바인드 계정 DN, 사용자 검색 필터(예: (uid={0})), 허용 그룹 필터(선택)를 넣고 LDAP 설정 저장을 누릅니다. 바인드 계정 비밀번호는 서버 환경 변수(LDAP_BIND_PASSWORD)로만 설정합니다. 자세한 내용은 LDAP 로그인 설정을 보세요.
• 기본 모델: 조직 기본 모델을 고르고 기본 모델 저장을 누릅니다. Evo CLI·데스크톱 앱은 로그인할 때 이 모델을 기본으로 받고, 웹 채팅도 사용자가 고르지 않았고 그룹 기본 모델이 없을 때 이 모델을 씁니다. 정하지 않았거나 사용자가 이 모델을 쓸 수 없으면 쓸 수 있는 첫 모델을 씁니다. 저장된 모델이 활성 모델 목록에서 빠지면 “현재 사용할 수 없음”으로 표시되고 적용되지 않습니다.

• 전역 기본 설정: 사용자가 따로 정하지 않았을 때 적용할 기본 테마와 기본 언어를 정합니다. 사용자가 정한 값이 우선합니다.

• 공지 배너: 켜면 모든 사용자의 채팅 화면 위쪽에 공지가 보입니다. 내용과 레벨(안내·경고)을 정하고 공지 저장을 누릅니다.

• 채팅 첨부: 사용자가 질문에 붙이는 파일의 한도를 MB로 정합니다. 저장하면 재시작 없이 다음 업로드부터 적용되고, 감사 로그에 SETTING_CHANGE(대상 attachments)로 남습니다.

  항목	기본값	정할 수 있는 범위
  파일 하나	20MB	1MB ~ 서버가 받는 multipart 한도 − 1MB(기본 100MB)
  대화 하나의 합계	100MB	파일 하나 한도 이상 ~ 10GB

  • 기본값으로 되돌리기는 환경 변수 값(ATTACHMENT_MAX_FILE_BYTES, ATTACHMENT_MAX_CONVERSATION_BYTES)으로 돌아갑니다.
  • 화면은 파일을 고를 때마다 현재 한도를 확인하고 넘는 파일을 올리기 전에 막습니다. 서버가 대화 합계 초과로 거절하면 두 한도를 함께 알립니다.
  • 한도를 올릴 때는 API 앞 프록시의 요청 본문 한도(client_max_body_size)도 그보다 크게 두세요. 프록시가 더 작으면 큰 파일은 프록시에서 거절됩니다.
  • 큰 파일도 앱 메모리에 통째로 올리지 않고 4MiB 조각으로 나눠 처리합니다. 다만 업로드하는 동안 multipart 임시 파일이 앱 컨테이너 임시 폴더에 잠시 생기므로, 그 디스크 여유를 함께 봅니다.

함께 보기

• 시작하기: 설치와 .env 설정
• 업그레이드 절차, 웹 OIDC(SSO) 로그인 설정, CLI 세션 API 설정, evo-dispatch 웹 연동 설정