> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloosphere.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 사용자 개요

> 사용자 목록 조회, 역할 할당, 사용자 추가/편집, 사용량 제한

<Info>관리자 › 사용자</Info>
플랫폼의 모든 사용자, 그룹, 조직을 관리합니다.

* 역할 기반 접근 제어와 그룹별 세밀한 권한 설정으로 조직 규모에 맞는 체계적인 사용자 개요가 가능합니다.

<Frame caption="사용자 개요 메인 화면">
  <img src="https://mintcdn.com/cloocus/Jjr6o_i720oXQtQO/images/admin/users-main.png?fit=max&auto=format&n=Jjr6o_i720oXQtQO&q=85&s=ed3ce2174d98733a0f60c55944a4de54" alt="사용자 개요 메인 화면" width="3360" height="1800" data-path="images/admin/users-main.png" />
</Frame>

사용자 개요 화면은 네 개의 탭으로 구성됩니다.

| 탭                                 | 설명                       |
| --------------------------------- | ------------------------ |
| **개요**                            | 개별 사용자 조회, 추가, 편집, 삭제    |
| [**그룹 및 권한**](/ko/admin/groups)   | 권한 그룹 생성 및 관리            |
| [**조직**](/ko/admin/organizations) | Entra ID 동기화 기반 조직 단위 관리 |
| [**문의**](/ko/admin/inquiries)     | 사용자 문의 접수 및 답변           |

***

## 사용자 목록

### 사용자 조회 및 검색

사용자 목록은 테이블 형태로 표시되며, 다음 컬럼 정보를 제공합니다.

| 컬럼           | 설명                      |
| ------------ | ----------------------- |
| **이름**       | 사용자 표시 이름               |
| **이메일**      | 로그인 이메일 주소              |
| **역할**       | 관리자, 사용자, 보류 중(Pending) |
| **OAuth ID** | SSO 연동 시 외부 인증 ID       |
| **최근 활동**    | 최근 접속 시간                |
| **생성일**      | 계정 생성일                  |

**검색 기능:**

* 이름 또는 이메일로 실시간 검색
* 이름, 생성일, 최근 활동순 정렬

### 사용자 역할

Cloosphere는 세 가지 역할을 제공합니다.

| 역할                 | 설명       |   관리자 패널  |   워크스페이스  |     채팅    |
| ------------------ | -------- | :-------: | :-------: | :-------: |
| **관리자**            | 전체 관리 권한 |   전체 접근   |   전체 접근   |   전체 접근   |
| **사용자**            | 일반 사용자   | 그룹 권한에 따름 | 그룹 권한에 따름 | 그룹 권한에 따름 |
| **보류 중 (Pending)** | 승인 대기    |   접근 불가   |   접근 불가   |   접근 불가   |

<Warning>
  **관리자** 역할은 모든 설정과 데이터에 접근할 수 있습니다. 최소 인원에게만 부여하세요.
</Warning>

### 슈퍼어드민 (SA)

<Info>
  **신규 기능** — 관리자 중 한 명을 <strong>슈퍼어드민(SA)</strong>으로 지정할 수 있습니다.
</Info>

SA는 별도의 역할이 아니라 **관리자 중 대표 관리자**를 표시하는 기능입니다.

* SA로 지정된 관리자의 이메일은 사용자 가입 후 **계정 활성화 대기 화면**에 연락처로 표시됩니다.

| 항목        | 설명                                           |
| --------- | -------------------------------------------- |
| **지정 대상** | 관리자 역할 사용자만                                  |
| **지정 방법** | 사용자 편집 모달에서 **SA로 설정** 버튼 클릭 (관리자 역할일 때만 표시) |
| **표시**    | 사용자 목록에서 SA 배지로 표시                           |
| **효과**    | 계정 활성화 대기 화면에 해당 관리자 이메일이 안내됨                |

<Frame caption="SA 편집 모달">
  <img src="https://mintcdn.com/cloocus/Jjr6o_i720oXQtQO/images/admin/users-sa-edit-modal.png?fit=max&auto=format&n=Jjr6o_i720oXQtQO&q=85&s=2fcca97f22695a593ba36ec8fedf2a05" alt="SA 편집 모달" style={{ maxWidth: '360px' }} width="1334" height="2207" data-path="images/admin/users-sa-edit-modal.png" />
</Frame>

<Note>
  SA는 1명만 지정 가능합니다. 새로운 사용자를 SA로 지정하면 기존 SA 지정은 자동 해제됩니다. SA 지정은 관리자만 할 수 있습니다.
</Note>

***

## 사용자 추가 및 편집

### 사용자 추가

**"+"** 아이콘(tooltip: "사용자 추가")을 클릭하여 수동으로 사용자를 생성합니다.

<Frame caption="사용자 추가 모달">
  <img src="https://mintcdn.com/cloocus/Jjr6o_i720oXQtQO/images/admin/users-add-modal.png?fit=max&auto=format&n=Jjr6o_i720oXQtQO&q=85&s=e497e8048c0873c722e31bfb2669ffda" alt="사용자 추가 모달 — 폼 입력 항목" style={{ maxWidth: '460px' }} width="960" height="924" data-path="images/admin/users-add-modal.png" />
</Frame>

| 필드       | 설명                        |  필수 |
| -------- | ------------------------- | :-: |
| **이메일**  | 로그인에 사용할 이메일 주소           |  O  |
| **이름**   | 표시 이름                     |  O  |
| **비밀번호** | 초기 비밀번호                   |  O  |
| **역할**   | 관리자 / 사용자 / 보류 중(Pending) |  O  |

<Tip>
  다수의 사용자를 한 번에 등록하려면 **CSV 파일 가져오기**를 사용할 수 있습니다. 사용자 추가 모달에서 CSV 업로드 옵션을 선택하세요.
</Tip>

### 사용자 편집

사용자의 **이름 또는 썸네일을 클릭**하거나, 행의 편집 버튼을 클릭하면 편집 모달이 열립니다.

<Frame caption="사용자 편집 모달">
  <img src="https://mintcdn.com/cloocus/Jjr6o_i720oXQtQO/images/admin/users-edit-modal.png?fit=max&auto=format&n=Jjr6o_i720oXQtQO&q=85&s=75735fc1e1d5d95b546501ccaaf4976c" alt="사용자 편집 모달" style={{ maxWidth: '380px' }} width="1321" height="1988" data-path="images/admin/users-edit-modal.png" />
</Frame>

**수정 가능 항목:**

* 이름
* 이메일
* 역할 — 관리자 / 사용자 / 보류 중(Pending) 중에서 선택 후 저장
* 프로필 이미지 URL
* 새 비밀번호
* **소속 그룹** — 사용자가 속한 그룹을 확인하고 추가/제거할 수 있습니다
* **소속 조직 단위(OU)** — 해당 사용자가 속한 조직 단위 트리를 읽기 전용으로 표시 (Entra/Google Workspace 동기화 결과)

<Note>
  조직 단위는 사용자 편집 화면에서 **읽기 전용**으로 보입니다. OU 멤버십은 외부 IdP 동기화로 결정되며, 직접 수정하려면 [조직 관리](/ko/admin/organizations) 화면에서 IdP 동기화 설정을 변경해야 합니다.
</Note>

<Note>
  자기 자신의 역할은 변경할 수 없으며, 최초 가입한 관리자(First User)의 역할도 변경할 수 없습니다.
</Note>

<Tip>
  사용자의 역할 변경은 자동으로 **감사 로그**에 기록됩니다 (`ROLE_CHANGE` 이벤트). 누가 누구의 역할을 언제 어떻게 바꿨는지 [모니터링 > 감사 로그](/ko/monitoring/audit-logs)에서 추적할 수 있습니다.
</Tip>

### 사용자 삭제

<Warning>
  사용자를 삭제하면 해당 사용자의 모든 채팅 기록, 설정, 데이터가 영구적으로 삭제됩니다. 이 작업은 되돌릴 수 없습니다.
</Warning>

### 사용자 채팅

관리자는 사용자의 채팅 목록을 조회할 수 있습니다.

* 사용자 행의 **채팅** 버튼을 클릭합니다.

***

## 사용량 제한

사용자별 토큰 사용량과 일일 한도는 **사용자 편집 → 사용량 탭**에서 **모델 단위**로 확인합니다.

* 기간은 **오늘 · 최근 7일 · 최근 30일**로 전환할 수 있습니다.

<Frame caption="사용자 편집 — 사용량 탭">
  <img src="https://mintcdn.com/cloocus/Jjr6o_i720oXQtQO/images/admin/users-usage-limits.png?fit=max&auto=format&n=Jjr6o_i720oXQtQO&q=85&s=d888b43cf3ac4f39883b26e3bca887d3" alt="사용자 편집 사용량 탭" style={{ maxWidth: '460px' }} width="960" height="916" data-path="images/admin/users-usage-limits.png" />
</Frame>

| 컬럼        | 설명                            |
| --------- | ----------------------------- |
| **모델**    | 사용량이 집계되는 모델                  |
| **사용**    | 해당 기간에 그 모델로 사용한 토큰 수         |
| **일일 한도** | 그 모델에 적용되는 일일 토큰 한도 (0 = 무제한) |
| **사용률**   | 일일 한도 대비 사용 비율(%)             |

해당 기간에 사용 기록이 없으면 \*"해당 기간에 기록된 사용량이 없습니다"\*로 표시됩니다.

<Note>
  **일일 한도·사용률**은 기간이 **오늘**일 때만 값이 표시됩니다. 최근 7일·30일에서는 누적 사용량(사용 컬럼)만 보이고 한도·사용률은 표시되지 않습니다.
</Note>

<Note>
  사용량 제한은 전역, 사용자, 그룹, 조직 네 계층에서 설정할 수 있으며, 여러 계층에 설정된 경우 **가장 관대한(높은) 값**이 적용됩니다. 전역 기본값과 모델별 한도는 [모델 설정 — 토큰 제한](/ko/admin/settings/models#토큰-제한)에서 관리합니다.
</Note>

***

## 베스트 프랙티스

<Accordion title="역할 관리 원칙">
  1. **관리자 최소화** — 필요한 인원만 지정
  2. **Pending 활용** — 신규 가입 시 Pending으로 설정하고 검토 후 승인
  3. **정기 검토** — 퇴사자 계정 삭제 또는 비활성화(Pending) 주기적 수행
</Accordion>

<Accordion title="그룹 설계 전략">
  1. **부서 기반** — 마케팅팀, 개발팀, 영업팀 등 부서별 그룹
  2. **역할 기반** — 팀장, 관리직, 신입 등 직급별 그룹
  3. **프로젝트 기반** — 특정 프로젝트 참여자 그룹 (한시적)
</Accordion>

<Accordion title="보안 권장 사항">
  1. **최소 권한 원칙** — 업무에 필요한 최소한의 권한만 부여
  2. **그룹 우선** — 개별 사용자 권한보다 그룹 권한 활용
  3. **정기 감사** — 권한 설정을 주기적으로 검토하고 불필요한 권한 회수
</Accordion>

***

## FAQ

<Accordion title="사용자가 비밀번호를 잊어버렸어요">
  관리자가 사용자 편집에서 새 비밀번호를 설정할 수 있습니다. SSO(Entra ID) 사용 시에는 회사 IT 부서에 문의하세요.
</Accordion>

<Accordion title="특정 사용자만 특정 에이전트를 사용하게 하려면?">
  에이전트 편집 화면의 **접근 권한** 설정에서 특정 그룹 또는 조직을 지정하세요. 공개 범위를 "비공개"로 설정한 뒤 허용 그룹을 추가합니다.
</Accordion>

<Accordion title="퇴사자 계정은 어떻게 처리하나요?">
  계정을 삭제하거나 역할을 **Pending**으로 변경하여 비활성화하세요. 삭제하면 채팅 기록도 함께 삭제되므로, 기록 보존이 필요하면 Pending 처리를 권장합니다.
</Accordion>

***

## 관련 페이지

<Columns cols={3}>
  <Card title="그룹 및 권한" icon="user-shield" href="/ko/admin/groups">
    권한 그룹, 3단계 권한 레벨(없음/읽기/쓰기), 조직 단위 매핑
  </Card>

  <Card title="조직 관리" icon="building" href="/ko/admin/organizations">
    조직/OU 계층, Entra ID 동기화, 조직 기반 접근 제어
  </Card>

  <Card title="문의" icon="inbox" href="/ko/admin/inquiries">
    사용자 문의 접수 및 처리
  </Card>
</Columns>