[<- README 홈으로 돌아가기](../README.ko.md)

# ClawManager 배포 및 빠른 시작 가이드

## 목차
- [1. 환경과 목표](#sec-01)
- [2. 배포 방식 개요](#sec-02)
- [3. 방식 A: k3s를 사용한 배포](#sec-03)
- [4. 방식 B: 표준 Kubernetes를 사용한 배포](#sec-04)
- [5. 중국 내 네트워크에서의 이미지 풀링 권장 사항(선택 사항)](#sec-05)
- [6. ClawManager 배포](#sec-06)
- [7. 웹 페이지 시작](#sec-08)
- [8. 빠른 시작 가이드(로그인 후 초기화 및 OpenClaw 인스턴스 생성)](#sec-09)
- [9. 콘솔 및 AI Gateway 기타 기능 설명](#sec-12)
- [10. 워크스페이스 모듈 설명](#sec-13)
- [11. 문제와 대응 빠른 참조](#sec-14)
- [12. 권장 최종 점검 순서(자가 점검용)](#sec-15)

<a id="sec-01"></a>
## 1. 환경과 목표
- **시스템 가정**: `x86_64` 아키텍처 Linux 서버.
- **배포 목표**: **ClawManager**를 배포하고 Web 페이지에서 보안 모델 구성을 완료한 뒤, **OpenClaw Desktop** 인스턴스를 생성하고 시작합니다.
- **적용 시나리오**:
  - **방식 A: k3s 단일 노드/경량 클러스터 배포**
  - **방식 B: 표준 Kubernetes 클러스터 배포**(예: kubeadm 클러스터, 기업용 K8s 클러스터, 클라우드 K8s 클러스터)


---

<a id="sec-02"></a>
## 2. 배포 방식 개요
다음 두 가지 방식 중 하나로 배포할 수 있습니다:

### 방식 A: k3s 배포
단일 노드, 테스트 환경 또는 경량 프로덕션 환경에 적합합니다.

### 방식 B: 표준 Kubernetes 배포
이미 표준 Kubernetes 클러스터를 갖춘 서버 환경에 적합합니다.

어떤 방식을 사용하든 최종적으로 동일한 ClawManager 매니페스트를 적용합니다:

```bash
kubectl apply -f deployments/k8s/clawmanager.yaml
```

---

<a id="sec-03"></a>
## 3. 방식 A: k3s를 사용한 배포

### 3.1 k3s 설치
```bash
curl -sfL https://get.k3s.io | sh -
```

중국 내 네트워크에서는 미러 소스를 사용하여 설치할 수 있습니다:

```bash
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh |   INSTALL_K3S_MIRROR=cn sh -
```

### 3.2 서비스 상태 확인
```bash
sudo systemctl status k3s --no-pager
sudo systemctl enable k3s
```

### 3.3 kubectl 구성
현재 사용자가 `kubectl`을 직접 사용할 수 없다면 다음을 실행합니다:

```bash
mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown "$USER:$USER" ~/.kube/config
```

또는 임시로 지정합니다:

```bash
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
```

### 3.4 클러스터 검증
```bash
kubectl get nodes
```

정상이라면 노드가 `Ready` 상태로 표시됩니다.

---

<a id="sec-04"></a>
## 4. 방식 B: 표준 Kubernetes를 사용한 배포

> 사용 가능한 Kubernetes 클러스터가 이미 있는 x86 서버 환경에 적용됩니다.

### 4.1 사전 점검
현재 `kubectl`이 대상 클러스터에 연결되어 있는지 확인합니다:

```bash
kubectl get nodes
kubectl get ns
```

정상이라면 최소 1개의 `Ready` 노드가 보여야 합니다.

### 4.2 기본 StorageClass 확인
ClawManager의 MySQL과 MinIO는 영구 스토리지가 필요합니다. 먼저 클러스터에 기본 `StorageClass`가 있는지 확인하는 것을 권장합니다:

```bash
kubectl get storageclass
```

클러스터에 기본 스토리지 클래스가 이미 있다면 바로 배포를 계속할 수 있습니다.

**기본 StorageClass가 없는 경우**, 사용 가능한 PV / PVC를 미리 준비하거나 로컬 경로 스토리지 방식을 사용하는 것을 권장합니다. 그렇지 않으면 이후 다음과 같은 문제가 발생할 수 있습니다:

```text
pod has unbound immediate PersistentVolumeClaims
```

---

<a id="sec-05"></a>
## 5. 중국 내 네트워크에서의 이미지 풀링 권장 사항(선택 사항)
서버가 Docker Hub 또는 기타 공개 레지스트리에 느리게 접근하는 경우 이미지 가속을 구성할 수 있습니다.

### 5.1 k3s 시나리오: `/etc/rancher/k3s/registries.yaml` 구성
```yaml
mirrors:
  docker.io:
    endpoint:
      - "https://docker.m.daocloud.io"
      - "https://docker.nju.edu.cn"
      - "https://docker.1ms.run"
  quay.io:
    endpoint:
      - "https://quay.mirrors.ustc.edu.cn"
  gcr.io:
    endpoint:
      - "https://gcr.mirrors.ustc.edu.cn"
  k8s.gcr.io:
    endpoint:
      - "https://registry.aliyuncs.com/google_containers"
```

수정 후 다음을 실행합니다:

```bash
sudo systemctl restart k3s
```

### 5.2 이미지 풀링 검증
```bash
sudo k3s crictl pull docker.io/rancher/mirrored-pause:3.6
```

---

<a id="sec-06"></a>
## 6. ClawManager 배포

### 6.1 프로젝트 코드 가져오기
```bash
git clone https://github.com/Yuan-lab-LLM/ClawManager.git
cd ClawManager
```

### 6.2 배포 매니페스트 적용
저장소 루트 디렉터리에서 실행합니다:

```bash
kubectl apply -f deployments/k8s/clawmanager.yaml
```

### 6.3 기본 리소스 확인
```bash
kubectl get ns
kubectl get pods -n clawmanager-system
kubectl get svc -n clawmanager-system
```

정상적인 경우 다음 구성 요소가 표시됩니다:
- `clawmanager-app`
- `mysql`
- `minio`
- `skill-scanner`

다음 오류가 보이면:

```text
0/1 nodes are available: pod has unbound immediate PersistentVolumeClaims
```

이는 클러스터 스토리지에서 MySQL / MinIO가 PVC 미바인드로 인해 시작되지 못한다는 의미입니다. 문서 끝의 다음 항목으로 바로 이동하세요:

- [11.1 스토리지 문제 전용 처리(PV/PVC)](#sec-14-storage)

---

<a id="sec-08"></a>
## 7. 웹 페이지 시작

### 7.1 NodePort로 접근
ClawManager의 프런트엔드 Service는 기본적으로 HTTPS NodePort를 사용합니다. 먼저 확인합니다:

```bash
kubectl get svc -n clawmanager-system
```

프런트엔드 포트가 다음과 같다면:

```text
443:30443/TCP
```

브라우저에서 직접 다음으로 접근할 수 있습니다:

```text
https://<서버IP>:30443
```


### 7.2 최초 HTTPS 접근 안내
일반적으로 자체 서명 인증서를 사용하므로 브라우저가 “안전하지 않음” 또는 인증서 경고를 표시할 수 있습니다. 다음을 클릭합니다:

```text
고급 → 계속 방문
```

그러면 페이지에 들어갈 수 있습니다.

---

<a id="sec-09"></a>
## 8. 빠른 시작 가이드(로그인 후 초기화 및 OpenClaw 인스턴스 생성)

위 배포를 완료하고 관리 페이지를 성공적으로 연 후에도, 실제로 **OpenClaw** 인스턴스를 생성하고 시작하려면 다음 초기화 단계를 완료해야 합니다.

### 8.1 시스템 로그인
1. 배포 완료 후 페이지를 엽니다. 예: `https://<노드IP>:30443`.
2. 기본 관리자 계정으로 로그인합니다:
   - **사용자 이름**: `admin`
   - **비밀번호**: `admin123`
3. 처음 로그인한 후에는 필요에 따라 기본 비밀번호를 변경하는 것을 권장합니다.


### 8.2 보안 모델 구성(AI Gateway)

![그림 1: AI Gateway 구성](./main/1.png)
로그인 후 먼저 사용 가능한 **보안 모델**을 구성해야 하며, 이는 플랫폼과 이후 인스턴스에서 공통으로 사용됩니다.

1. 왼쪽 메뉴에서 **AI Gateway** → **모델**을 클릭합니다.
2. 새 모델을 추가하거나 기존 모델을 편집하고, 연결하는 모델 서비스에 따라 다음 정보를 입력합니다:

   * **표시 이름**: 식별하기 쉬운 이름을 입력합니다.
   * **벤더 템플릿**: 모델 서비스 유형에 따라 해당 템플릿을 선택합니다. 사용자 정의 또는 호환 인터페이스를 사용하는 경우 **Local / Internal**을 선택할 수 있습니다.
   * **프로토콜**: 인터페이스 프로토콜에 따라 **OpenAI Compatible** 또는 실제 사용하는 다른 프로토콜을 선택합니다.
   * **Base URL**: 모델 서비스가 제공하는 인터페이스 주소를 입력합니다.
   * **API Key**: 해당 모델 서비스의 유효한 키를 입력합니다.
   * **Provider Model**: 실제 호출할 모델 이름을 입력합니다.
   * **통화**: 실제 상황에 맞게 입력합니다. 비용 표시가 필요 없다면 기본값을 유지할 수 있습니다.
   * **입력 가격 / 출력 가격**: 비용 통계를 하지 않을 경우 `0`을 입력할 수 있습니다.
3. 제출 전에 반드시 다음 항목을 체크합니다:

   * **보안 모델**
   * **사용**
4. **저장**을 클릭합니다。

> 참고: 페이지의 이미지는 입력 위치와 예시 형식을 보여주기 위한 것입니다. 실제 내용은 사용 중인 모델 서비스 구성에 따라 입력하세요。


### 8.3 OpenClaw 인스턴스 생성
모델 구성이 완료되면 **OpenClaw Desktop** 인스턴스를 생성합니다.

1. 왼쪽 아래의 **ADMIN**을 클릭하여 **워크스페이스**로 전환합니다.
2. **인스턴스 생성**을 클릭합니다。

![](./main/2.png)
#### 1단계: 기본 정보
- **인스턴스 이름**을 입력합니다(최소 3자).
- 설명은 선택 사항이며 비워 둘 수 있습니다.
- **다음**을 클릭합니다.

![](./main/3.png)
#### 2단계: 유형 선택
- **OpenClaw Desktop**을 선택합니다.
- **다음**을 클릭합니다。


![](./main/4.png)
#### 3단계: 구성
- **Small** 사양을 바로 선택할 수 있습니다:
  - `2 CPU`
  - `4 GB RAM`
  - `20 GB Disk`
- 아래 사용자 정의 구성 영역에서 필요에 따라 수정할 수도 있습니다。
- OpenClaw 리소스 주입 부분에서는 필요에 따라 다음을 선택할 수 있습니다:
  - **수동 리소스**
  - **리소스 패키지**
  - **아카이브 가져오기**
- 처음 사용하는 경우 기본값을 유지하거나 **수동 리소스**를 선택해도 됩니다。
- 마지막으로 **생성**을 클릭합니다。

### 8.4 첫 생성 안내
- **OpenClaw** 인스턴스를 처음 생성할 때는 필요한 이미지를 다운로드하고 환경을 초기화해야 하므로 시간이 더 오래 걸립니다。
- 네트워크가 느리거나 처음 이미지 풀링을 수행하는 경우, 인스턴스 상태가 오랫동안 **생성 중**으로 표시될 수 있습니다. 잠시 기다려 주세요。
- 오랜 시간이 지나도 시작되지 않으면 Kubernetes / Docker 로그로 돌아가 이미지, PVC, 게이트웨이 모델 등의 문제를 점검하세요。

---

<a id="sec-12"></a>
## 9. 콘솔 및 AI Gateway 기타 기능 설명

모델 구성 외에도 플랫폼 홈의 콘솔과 AI Gateway는 감사, 비용, 규칙 거버넌스 등의 기능을 제공하여 관리자가 클러스터 상태, 모델 호출 기록, 보안 정책 실행 상태를 중앙에서 쉽게 확인할 수 있도록 합니다。

### 9.1 콘솔 개요

![](./main/5.png)

콘솔 홈은 현재 클러스터와 플랫폼의 전체 운영 상태를 보여주며, 관리자가 리소스 사용량과 시스템 상태를 빠르게 파악할 수 있도록 합니다。

주요 내용은 다음과 같습니다：

- **클러스터 기본 정보 개요**: 현재 플랫폼의 총 사용자 수, 총 인스턴스 수, 실행 중 인스턴스 수, 총 스토리지 사용량을 표시합니다。
- **노드 개요**: 현재 사용 가능한 노드 수와 현재 클러스터의 주요 스케줄링 노드 정보를 표시합니다。
- **리소스 신청 현황**: 현재 플랫폼이 신청한 CPU, 메모리, 디스크 리소스 총량을 표시합니다。
- **용량 대시보드**: 노드, CPU, 메모리, 디스크 등 차원별로 전체 리소스 용량과 현재 사용률을 표시하여 클러스터에 사용 가능한 여유가 있는지 판단하기 쉽게 합니다。
- **기반 시설 표**: 현재 노드, 리소스 및 기본 런타임 환경의 상태 정보를 확인하는 데 사용됩니다。

> 참고: 콘솔은 주로 플랫폼 전체 리소스, 노드, 인스턴스 운영 개요를 보는 데 사용되며, 특정 인스턴스 내부의 OpenClaw 작업에 직접 사용되지는 않습니다。

### 9.2 보안 센터 (skill-scanner)

콘솔의 **보안 센터**는 플랫폼 자원의 스캔 상태, 이력 보고서, 스캐너 구성을 통합하여 확인하는 데 사용됩니다. 이 기능은 백엔드의 **skill-scanner** 서비스에 의존하여 동작하며, 자원에 대해 정적 스캔, 심층 스캔, 그리고 LLM 기반의 보조 분석을 수행하여 관리자가 잠재적인 위험 콘텐츠, 비정상 자원, 의심스러운 스킬을 식별할 수 있도록 도와줍니다.

보안 센터는 현재 다음 세 가지 주요 모듈로 구성됩니다.

* **실행 개요**
* **보고서 이력**
* **스캐너 구성**

#### 9.2.1 실행 개요

![](./main/14.png)

“실행 개요” 페이지는 현재 플랫폼 전체의 스캔 상태와 위험 분포를 확인하는 데 사용되며, 관리자가 현재 보안 상태를 빠르게 파악할 수 있도록 도와줍니다.

페이지에는 주로 다음과 같은 내용이 포함됩니다.

* **현재 적용 모드**: 현재 사용 중인 모드가 **Quick 모드**인지 **Deep 모드**인지 표시합니다.
* **빠른 스캔 / 전체 스캔**:

  * **빠른 스캔**: 새로 추가되거나 변경된 자원을 처리하는 데 적합하며, 스캔 범위가 가볍고 실행 속도가 빠릅니다.
  * **전체 스캔**: 전체 자원을 주기적으로 다시 스캔하여 현재 플랫폼의 모든 자원 상태를 완전하게 재검토하는 데 적합합니다.
* **총 자산 수**: 현재 보안 센터의 스캔 범위에 포함된 자원 수입니다.
* **완료된 스캔**: 스캔이 완료된 자원 수입니다.
* **고위험 / 중위험**: 현재 스캔 결과에서 식별된 위험 등급 통계입니다.
* **스캔 커버리지**: 실제로 스캔이 완료된 자산 수가 플랫폼 전체 자산 수에서 차지하는 비율을 표시합니다.
* **SAFE / 고위험 / 대기 중 / 실패**:

  * **SAFE**: 스캔을 통과했으며 현재 위험이 발견되지 않은 자산 수
  * **고위험**: 즉시 처리해야 하는 위험 자산 수
  * **대기 중**: 증거 수집 대기 또는 스캔 대기열에 있는 자산 수
  * **실패**: 스캔 실행에 실패하여 다시 실행해야 하는 자산 수
* **플랫폼 자산 위험 추세**: 위험 등급별로 집계된 현재 플랫폼 자산의 위험 분포를 표시합니다.
* **핫 자산**: 가장 자주 사용되는 스킬 또는 고빈도 사용 자원을 표시하여 관리자가 핵심 자산을 빠르게 파악할 수 있도록 도와줍니다.
* **스캐너 상태**: 현재 skill-scanner 의 사용 가능 여부 및 연결 상태를 표시합니다. 예: “정적 스캔 사용 가능”, “연결됨”.
* **위험 알림 및 처리 제안**: 현재 위험 상태에 따른 간단한 안내 정보를 제공합니다.
* **최근 스캔 작업**: 최근 실행된 스캔 기록을 표시하여 최근 스캔 활동을 추적하기 쉽게 합니다.

> 설명：
>
> * 페이지에 “현재 고위험 또는 중위험 자산이 없습니다”라고 표시되면, 현재 스캔 결과에서 뚜렷한 위험이 발견되지 않았음을 의미합니다.
> * 페이지에 “아직 스캔 작업 기록이 없습니다”라고 표시되면, 아직 스캔이 실행되지 않았거나 유효한 스캔 결과가 생성되지 않았음을 의미합니다.

#### 9.2.2 보고서 이력

“보고서 이력” 페이지는 과거 스캔 보고서와 관련 결과 기록을 확인하는 데 사용되며, 관리자가 이전 스캔 실행 상황을 되짚어볼 수 있도록 도와줍니다.

이 모듈은 주로 다음 용도로 사용됩니다.

* 과거에 실행된 스캔 작업 결과 확인
* 서로 다른 시점의 스캔 출력 비교
* 특정 자원이 서로 다른 단계에서 어떻게 보안 상태가 변했는지 추적 보조
* 이후 재검토, 재스캔, 문제 추적을 위한 이력 근거 제공

> 설명：
>
> * “보고서 이력”은 과거 결과의 보관과 추적에 더 중점을 둡니다；
> * “실행 개요”는 현재 상태와 전체 개요에 더 중점을 둡니다。

#### 9.2.3 스캐너 구성

![](./main/15.png)

“스캐너 구성” 페이지는 skill-scanner 의 동작 방식, LLM 관련 설정, 그리고 quick / deep 두 가지 스캔 전략을 관리하는 데 사용됩니다. 저장 후 Deployment rollout 이 트리거되며, 새로운 구성이 적용될 때까지 기다립니다.

페이지에는 주로 다음 내용이 포함됩니다.

##### (1) skill-scanner 서비스 상태

* 현재 백엔드 스캔 서비스의 namespace, Deployment 이름, 연결 상태를 표시합니다.
* 페이지에 **연결됨**, **정적 스캔 사용 가능** 이 표시되면 기본 정적 스캔 기능이 사용 가능한 상태임을 의미합니다.

##### (2) LLM 구성

이 영역은 scanner 가 필요할 때 모델 기반 분석 기능을 수행할 수 있도록 주 LLM 을 구성하는 데 사용됩니다.

주요 필드는 다음과 같습니다.

* **주 LLM 통합**: **AI Gateway** 에 이미 구성된 모델에서 주 LLM 구성을 직접 가져올 수 있습니다.
* **LLM API Key**: `SKILL_SCANNER_LLM_API_KEY` 에 대응하며, 주 LLM analyzer 의 인증에 사용됩니다.
* **LLM Model**: `SKILL_SCANNER_LLM_MODEL` 에 대응하며, 구체적인 모델 이름 등을 지정합니다.
* **LLM Base URL**: `SKILL_SCANNER_LLM_BASE_URL` 에 대응하며, 주 LLM 서비스 주소를 구성하는 데 사용됩니다.

##### (3) Meta LLM 통합

이 영역은 meta analyzer 가 사용하는 모델을 구성하는 데 사용되며, 일반적으로 findings 를 추가 요약, 정리 또는 2차 처리하는 데 사용됩니다.

주요 필드는 다음과 같습니다.

* **Meta LLM 통합**: **AI Gateway** 에 이미 구성된 모델에서 meta analyzer 구성을 직접 가져올 수 있습니다.
* **Meta LLM API Key**: `SKILL_SCANNER_META_LLM_API_KEY` 에 대응합니다.
* **Meta LLM Model**: `SKILL_SCANNER_META_LLM_MODEL` 에 대응합니다.
* **Meta LLM Base URL**: `SKILL_SCANNER_META_LLM_BASE_URL` 에 대응합니다.

> 설명：
>
> * 현재 LLM 이 구성되어 있지 않으면, 페이지에는 일반적으로 현재 정적 스캔만 지원된다는 안내가 표시됩니다；
> * 주 LLM 과 Meta LLM 을 모두 구성한 후에야 scanner 가 더 완전한 의미 분석 및 요약 기능을 사용할 수 있습니다。

##### (4) 현재 스캔 모드

페이지에서는 현재 플랫폼에서 실제로 사용하는 스캔 모드를 선택할 수 있습니다.

* **Quick 모드**: quick analyzers 를 사용하여 스캔을 수행하며, 일상적인 빠른 점검에 적합합니다.
* **Deep 모드**: deep analyzers 를 사용하여 스캔을 수행하며, 보다 완전하고 심층적인 분석에 적합합니다.

주의할 점은 다음과 같습니다.

* Dashboard 의 “빠른 스캔”과 “전체 스캔”은 모두 여기에서 선택한 스캔 강도를 사용합니다；
* 둘의 차이는 주로 스캔 범위에 있으며 analyzer 깊이 자체에는 있지 않습니다。

##### (5) Quick / Deep 스캔 전략

페이지 하단에서는 **빠른** 과 **심층** 두 가지 스캔 전략 구성을 각각 유지하며, 관리자가 서로 다른 시나리오에 따라 다른 analyzer 조합을 선택할 수 있도록 합니다.

각 전략에는 다음 구성 항목이 포함됩니다.

* **타임아웃(초)**: 현재 모드에서 스캔 작업의 타임아웃 시간을 설정합니다.
* **호출 방식**: 필요에 따라 서로 다른 analyzer 를 활성화하거나 비활성화할 수 있습니다.

현재 표시되는 analyzer 유형은 다음과 같습니다.

* **Static**: YAML + YARA 정적 규칙 스캔
* **Bytecode**: Python bytecode 무결성 검증
* **Pipeline**: 명령 체인 및 taint 분석
* **Behavioral**: AST 기반 동작 및 데이터 흐름 분석
* **LLM**: 외부 LLM 에 의존하는 의미 분석
* **Meta**: findings 에 대한 2차 요약 분석

일반적으로 다음과 같이 이해할 수 있습니다.

* **Quick 모드**: 더 빠른 실행에 중점을 두며, 일상적인 증분 점검에 자주 사용됩니다
* **Deep 모드**: 더 많은 analyzer 를 활성화할 수 있으며, 보다 깊이 있는 검토와 보안 감사에 적합합니다

##### (6) 저장 및 적용

페이지 오른쪽 상단의 **저장 및 적용** 은 현재의 모든 scanner 관련 구성을 제출하는 데 사용됩니다. 저장 후 다음 작업이 수행됩니다.

* ClawManager 의 quick / deep 스캔 전략 업데이트
* skill-scanner Deployment 의 관련 환경 변수 업데이트
* rollout 완료를 기다린 후 새 구성을 정식으로 적용

> 설명：
>
> * 스캐너 구성을 변경한 후에는 새 스캔 작업을 실행하기 전에 구성이 완전히 적용될 때까지 기다리는 것을 권장합니다；
> * 구성 후 연결 상태가 비정상적이라면 AI Gateway 모델, LLM 주소, Key, Deployment rollout 상태를 우선 확인하는 것이 좋습니다。

### 9.3 AI Gateway 기능 개요

AI Gateway 는 “모델” 구성 외에도 다음 모듈을 포함합니다.

* **AI 감사**: 모델 호출 Trace, 요청 및 응답 payload, 적중 위험, 라우팅 결정, 호출 상세를 확인합니다.
* **비용**: Token 사용량, 예상 비용, 내부 비용, 추세 통계를 확인합니다.
* **위험 제어 규칙**: 민감 정보 탐지 규칙을 구성하고 적중 시 통과시킬지 안전 모델로 라우팅할지 제어합니다.

### 9.4 비용 모듈

비용 페이지는 플랫폼 모델 호출의 비용과 Token 사용 현황을 집계하여 관리자가 전체 소비 상황을 파악할 수 있도록 도와줍니다.

![](./main/6.png)

페이지에는 주로 다음 내용이 포함됩니다.

* **입력 Token**: 입력 프롬프트 총량 통계
* **출력 Token**: 모델 생성 내용 총량 통계
* **예상 비용**: Provider 단가 기준으로 추산된 비용
* **내부 비용**: 보안 모델 관련 내부 정산 비용
* **일일 비용 추세**: 최근 7일 동안 현재 구간 내 예상 비용과 Token 변화 확인
* **사용자 요약**: 사용자별 사용량 및 비용 집계
* **인스턴스 요약**: 인스턴스별 사용량 및 비용 집계
* **최근 비용 기록**: Trace, 사용자, 모델 등 조건으로 비용 기록을 검색하고 페이지 단위로 확인하며, 감사 상세로 이동 가능

> 설명: 현재 아직 모델 호출 기록이 생성되지 않았다면 입력 Token, 출력 Token, 비용, 추세 차트가 모두 0 으로 표시될 수 있으며 이는 정상입니다。

### 9.5 AI 감사 모듈

AI 감사 페이지는 최근의 관리형 모델 호출 기록을 확인하는 데 사용되며, 관리자가 모델 호출, Token 사용, 라우팅 결과를 추적하고 점검하는 데 도움을 줍니다.

![](./main/7.png)

주요 기능은 다음과 같습니다.

* **최근 AI Trace**: 최근 모델 호출 체인 확인
* **Trace 목록**: 최근 관리형 Trace 를 통합 테이블에서 확인
* **검색 및 필터링**: Trace, 요청 내용, 사용자, 모델 등 조건으로 검색 가능
* **상태 필터링**: 상태별로 서로 다른 호출 결과 확인 가능
* **모델 필터링**: 모델별로 해당 호출 기록 필터링 가능
* **페이지네이션 및 새로고침**: 감사 결과를 페이지 단위로 확인하고 수동 새로고침 가능

> 설명: 페이지에 “아직 AI 감사 기록이 없습니다”라고 표시되면, 아직 실제 모델 호출 요청이 발생하지 않았음을 의미합니다。

### 9.6 위험 제어 규칙 모듈

위험 제어 규칙 페이지는 민감 콘텐츠 탐지 규칙을 구성하고, 규칙 적중 후 어떤 처리 동작을 수행할지 결정하는 데 사용됩니다.

![](./main/8.png)

이 모듈은 주로 다음 기능을 지원합니다.

* **규칙 목록 관리**: 전체 규칙과 활성 상태 확인
* **규칙 분류 보기**: 개인정보, 회사 정보, 고객 업무, 보안 자격 정보, 재무/법무, 정치적 민감, 사용자 정의 등 분류별로 규칙 확인 가능
* **규칙 필드 구성**: 규칙 ID, 표시 이름, 심각도, 동작, 정렬 순서, 정규식 Pattern, 설명 설정 가능
* **규칙 동작 제어**: 규칙 적중 시 통과시키거나 보안 모델로 라우팅하도록 선택 가능
* **일괄 활성화 / 비활성화**: 규칙 상태를 일괄로 조정 가능
* **규칙 테스트 콘솔**: 샘플 텍스트를 붙여 넣어 활성 규칙 또는 초안 규칙이 무엇에 적중하는지 테스트 가능

현재 내장된 규칙 예시는 다음을 포함하지만 이에 한정되지 않습니다.

* 개인정보: 이메일 주소, 휴대전화 번호, 신분증 번호, 여권 번호, 은행카드 문맥, 주소, 이력서 내용 등
* 회사 정보: 내부 IP, 내부 도메인, 호스트 명명, Kubernetes Service DNS, 프로젝트 코드명, 조직 구조, 급여 / HR 정보 등
* 고객 업무: 고객 목록, 계약 / 견적서, 세금계산서 세금 번호, CRM / 티켓 데이터 등
* 보안 자격 정보: 개인 키, API Key, Token, JWT, Cookie / Session, 데이터베이스 연결 문자열, Kubeconfig, 환경 변수 비밀값 등
* 재무/법무: 예산, 이익, 매출, 법무 의견, 소송, NDA 등
* 정치적 민감: 정치 기관, 군사/국가 안보, 극단 폭력 관련 표현 등

> 설명: 기본 규칙은 이미 다양한 일반적인 민감 정보 탐지 시나리오를 포괄하고 있습니다. 실제 사용 시에는 업무 요구에 따라 규칙을 추가, 조정 또는 비활성화할 수 있습니다。
---

<a id="sec-13"></a>
## 10. 워크스페이스 모듈 설명

워크스페이스는 일반 사용자가 플랫폼에 들어온 후 사용하는 주요 작업 영역입니다. 개인 리소스 할당량 조회, 인스턴스 생성, 인스턴스 관리, OpenClaw 관련 리소스 유지에 사용됩니다. 이 모듈은 관리자 측의 “콘솔 개요”와 달리 일상 사용 및 운영 작업에 더 초점이 맞춰져 있습니다。

### 10.1 워크스페이스 홈
![](./main/9.png)
워크스페이스 홈은 현재 계정의 인스턴스 및 리소스 사용 현황을 표시하는 데 사용되며, 주로 다음 내용을 포함합니다：

- **내 인스턴스**: 현재 계정에서 생성한 인스턴스 수를 표시합니다。
- **실행 중**: 현재 실행 중인 인스턴스 수를 표시합니다。
- **사용된 스토리지**: 현재 계정이 사용 중인 스토리지 공간을 표시합니다。
- **내 리소스 할당량**: 현재 계정에서 사용 가능한 할당량 정보(인스턴스 수, 최대 CPU 코어 수, 최대 메모리, 최대 스토리지, 최대 GPU 수)를 표시합니다。
- **빠른 작업**: **새 인스턴스 생성** 및 **모든 인스턴스 보기** 두 개의 진입점을 제공하여 플랫폼을 빠르게 사용할 수 있게 합니다。

> 참고: 페이지에 “아직 인스턴스가 없습니다”가 표시되면, 바로 **새 인스턴스 생성**을 클릭하여 첫 번째 OpenClaw Desktop 인스턴스 생성을 시작할 수 있습니다。

### 10.2 내 인스턴스

**내 인스턴스** 페이지는 현재 계정에서 생성된 인스턴스를 통합 조회 및 관리하기 위한 페이지입니다. 이 페이지는 주로 인스턴스 관리 기능을 담당합니다。
![](./main/10.png)
일반적으로 지원되는 작업은 다음과 같습니다：

- **인스턴스 상태 보기**: 인스턴스가 생성 중, 실행 중, 중지됨 또는 비정상 상태인지 확인합니다。
- **인스턴스 상세 진입**: 인스턴스의 기본 정보, 리소스 구성 및 실행 상태를 확인합니다。
- **인스턴스 중지**: 인스턴스가 비정상이거나 환경을 다시 로드해야 하는 경우 중지 작업을 수행할 수 있습니다。
- **인스턴스 삭제**: 인스턴스가 더 이상 필요하지 않을 때 CPU, 메모리, 스토리지 등의 리소스를 해제하기 위해 직접 삭제할 수 있습니다。

> 참고: 인스턴스를 삭제하면 관련 리소스도 함께 정리됩니다. 실행 전에 내부 데이터와 구성이 백업되었는지 확인하세요。

### 10.3 리소스 관리

**리소스 관리** 페이지는 사용 가능한 OpenClaw 리소스 내용을 유지하여, 인스턴스 시작 후 주입하고 사용할 수 있도록 하는 데 사용됩니다。
![](./main/11.png)
페이지에는 주로 다음 부분이 있습니다：

- **리소스**: 사용 가능한 리소스 항목을 조회하고 유지합니다。
- **리소스 패키지**: 여러 리소스를 재사용 가능한 패키지로 묶어 일괄 주입을 쉽게 합니다。
- **주입 기록**: 리소스 주입 이력과 실행 상태를 확인합니다。

리소스 관리 페이지 왼쪽에서는 리소스 유형별로 구분 관리할 수도 있으며, 현재 페이지에 표시되는 유형은 다음과 같습니다：

- **채널**
- **스킬**
- **에이전트(출시 예정)**
- **예약 작업(출시 예정)**

페이지 오른쪽 상단에서는 다음을 지원합니다：

- **새로고침**: 현재 리소스 목록을 다시 불러옵니다。
- **새로 만들기**: 새로운 리소스 항목을 생성합니다。

> 참고: 리소스 관리는 주로 인스턴스 시작 후 사용할 수 있는 OpenClaw 리소스 내용을 준비하는 데 사용되며, 인스턴스 생성 과정을 직접 대체하지는 않습니다. 인스턴스 생성 시 **수동 리소스**, **리소스 패키지**, **아카이브 가져오기** 등의 방식과 함께 리소스를 주입할 수 있습니다。


### 10.3.1 채널 생성

“채널”은 OpenClaw와 외부 메시징 플랫폼 또는 접속 대상 간의 연결 방식을 구성하는 데 사용됩니다. 예를 들어 Telegram, Slack, Feishu / Lark 등이 있습니다.

![](./main/12.png)

채널을 생성할 때는 다음 단계에 따라 진행합니다.

1. **리소스 관리** 페이지로 이동하고 **리소스** 탭을 유지합니다.
2. 왼쪽 리소스 유형에서 **채널**을 선택합니다.
3. 페이지 오른쪽의 **새로 만들기**를 클릭하여 “새 리소스” 팝업을 엽니다.
4. 팝업에서 기본 정보를 입력합니다.
   - **유형**: **채널** 선택
   - **리소스 Key**: 해당 채널의 고유 식별자를 입력합니다. 식별하기 쉽고 중복되지 않는 영문명 또는 조합명을 사용하는 것을 권장합니다
   - **이름**: 채널 표시 이름을 입력합니다
   - **태그**: 선택 사항이며, 분류 및 검색에 사용됩니다
   - **설명**: 선택 사항이며, 채널의 용도를 보충 설명하는 데 사용됩니다
   - **사용 중**: 체크 상태를 유지하는 것을 권장합니다
5. **Channel 템플릿** 영역에서 시작 템플릿을 선택합니다. 현재 지원되는 템플릿은 다음과 같습니다.
   - `Telegram`
   - `DingTalk`
   - `Slack`
   - `Feishu / Lark`

6. 템플릿을 선택한 후 **템플릿 불러오기**를 클릭합니다. 시스템은 해당 템플릿의 기본 구성을 아래의 **내용 JSON** 영역에 자동으로 입력합니다.
7. 실제 연동 정보에 따라 **내용 JSON**의 필드 내용을 계속 추가하거나 수정합니다.
8. 설정이 올바른지 확인한 후 저장을 클릭하여 채널 생성을 완료합니다.

> 설명:
> - **Channel 템플릿**은 기본 구성을 빠르게 생성하는 데 사용됩니다;
> - **내용 JSON**은 최종적으로 적용되는 채널 구성 내용입니다;
> - 완전히 일치하는 템플릿이 없는 경우 **내용 JSON**에 직접 수동으로 설정을 입력할 수도 있습니다.

### 10.3.2 스킬 업로드

스킬은 OpenClaw에 재사용 가능한 기능을 제공하는 데 사용됩니다. 플랫폼은 아카이브 파일 업로드를 통해 스킬을 일괄 가져오는 기능을 지원합니다.

![](./main/13.png)

스킬을 업로드할 때는 다음 단계에 따라 진행합니다.

1. **리소스 관리** 페이지로 이동하고 **리소스** 탭을 유지합니다.
2. 왼쪽 리소스 유형에서 **스킬**을 선택합니다.
3. **파일 선택**을 클릭하여 로컬 스킬 압축 파일을 선택합니다.
4. 현재 페이지는 **`.zip`** 파일 업로드만 지원합니다.
5. 파일 선택이 완료되면 오른쪽의 **스킬 아카이브 업로드**를 클릭합니다。
6. 시스템은 업로드된 내용을 자동으로 분석하고 각 1단계 디렉터리를 하나의 스킬로 가져옵니다.
7. 업로드가 완료되면 스킬 목록에서 가져온 스킬 내용을 확인할 수 있습니다。

> 설명:
> - 스킬 아카이브는 미리 디렉터리 구조를 정리해 두는 것을 권장합니다；
> - 각 1단계 디렉터리는 하나의 독립된 스킬로 인식됩니다；
> - 업로드 후 목록이 바로 새로고침되지 않으면 페이지 오른쪽 상단의 **새로고침**을 수동으로 클릭하여 다시 불러올 수 있습니다。
---

<a id="sec-14"></a>
## 11. 문제와 대응 빠른 참조

<a id="sec-14-storage"></a>
### 11.1 스토리지 문제 전용 처리(PV/PVC)

다음 오류가 보이는 경우：

```text
0/1 nodes are available: pod has unbound immediate PersistentVolumeClaims
```

클러스터 스토리지가 자동으로 바인딩되지 않았음을 의미합니다. 이 경우 x86 단일 노드 서버 방식으로 로컬 `hostPath` PV/PVC를 수동 생성할 수 있습니다。

> 이 방식은 단일 노드 서버 테스트 또는 경량 환경에 적합합니다. 프로덕션 환경에서는 NFS, Ceph, 클라우드 디스크 등 정식 스토리지를 사용하는 것이 좋습니다。

#### 11.1.1 PV 생성
```bash
kubectl apply -f - <<EOF
apiVersion: v1
kind: PersistentVolume
metadata:
  name: mysql-pv-local
spec:
  capacity:
    storage: 5Gi
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Delete
  hostPath:
    path: /tmp/mysql-data
EOF

kubectl apply -f - <<EOF
apiVersion: v1
kind: PersistentVolume
metadata:
  name: minio-pv-local
spec:
  capacity:
    storage: 10Gi
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Delete
  hostPath:
    path: /tmp/minio-data
EOF
```

#### 11.1.2 PVC 생성
```bash
kubectl apply -f - <<EOF
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: mysql-data
  namespace: clawmanager-system
spec:
  storageClassName: ""
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 5Gi
  volumeName: mysql-pv-local
EOF

kubectl apply -f - <<EOF
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: minio-data
  namespace: clawmanager-system
spec:
  storageClassName: ""
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  volumeName: minio-pv-local
EOF
```

#### 11.1.3 Pod 재생성
```bash
kubectl delete pod --all -n clawmanager-system
```

#### 11.1.4 상태 다시 확인
```bash
kubectl get pvc -n clawmanager-system
kubectl get pods -n clawmanager-system -w
```

예상 결과：
- `mysql-data` / `minio-data`가 `Bound`
- `mysql` / `minio` / `skill-scanner` / `clawmanager-app`가 최종적으로 `Running`

---

| 현상 | 원인 | 처리 |
| :--- | :--- | :--- |
| `kubectl`의 `localhost:8080` 연결이 거부됨 | kubeconfig가 구성되지 않음 | `KUBECONFIG`를 설정하거나 `~/.kube/config`에 복사 |
| Pod 이미지 풀링 타임아웃 | Docker Hub / GHCR 네트워크 불안정 | 이미지 가속 또는 프록시 구성 |
| MySQL / MinIO가 계속 `Pending` | PVC가 바인딩되지 않음 | `StorageClass`를 확인하거나 PV/PVC를 수동 생성 |
| 브라우저에서 페이지를 열 수 없음 | NodePort가 열려 있지 않음 / `port-forward` 프로세스가 유지되지 않음 | 포트를 열거나 포워딩 터미널을 유지 |
| 페이지는 열리지만 OpenClaw 인스턴스를 생성할 수 없음 | 보안 모델이 구성되지 않음 | 먼저 **AI Gateway → 모델**에서 보안 모델을 구성하고 활성화 |
| 인스턴스가 오랫동안 “생성 중” 상태로 남음 | 첫 이미지 풀링에 시간이 오래 걸림 / 스토리지 또는 네트워크 문제 | 잠시 기다리고, 필요 시 Pod와 이벤트 확인 |

---

<a id="sec-15"></a>
## 12. 권장 최종 점검 순서(자가 점검용)
1. `kubectl get nodes`
2. `kubectl get storageclass`
3. `kubectl get pods -n clawmanager-system`
4. `kubectl get pvc -n clawmanager-system`
5. `kubectl get svc -n clawmanager-system`
6. 브라우저에서 `https://<IP>:30443` 열기
7. 백엔드에 로그인하여 **보안 모델 구성** 완료
8. 워크스페이스에서 **OpenClaw Desktop** 인스턴스 생성
