wehub-resource-sync
794 lines
37 KiB
Markdown
794 lines
37 KiB
Markdown
[<- 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)
|
|
- [10.4 Team 협업](#sec-13-team)
|
|
- [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/cluster/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/cluster/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** → **모델**을 클릭합니다.
|
|
2. 새 모델을 추가하거나 기존 모델을 편집하고, 연결하는 모델 서비스에 따라 다음 정보를 입력합니다:
|
|
|
|
* **표시 이름**: 식별하기 쉬운 이름을 입력합니다.
|
|
* **벤더 템플릿**: 모델 서비스 유형에 따라 해당 템플릿을 선택합니다. 사용자 정의 또는 호환 인터페이스를 사용하는 경우 **Local / Internal**을 선택할 수 있습니다.
|
|
* **프로토콜**: 인터페이스 프로토콜에 따라 **OpenAI Compatible** 또는 실제 사용하는 다른 프로토콜을 선택합니다.
|
|
* **Base URL**: 모델 서비스가 제공하는 인터페이스 주소를 입력합니다.
|
|
* **API Key**: 해당 모델 서비스의 유효한 키를 입력합니다.
|
|
* **Provider Model**: 실제 호출할 모델 이름을 입력합니다.
|
|
* **통화**: 실제 상황에 맞게 입력합니다. 비용 표시가 필요 없다면 기본값을 유지할 수 있습니다.
|
|
* **입력 가격 / 출력 가격**: 비용 통계를 하지 않을 경우 `0`을 입력할 수 있습니다.
|
|
3. 제출 전에 반드시 다음 항목을 체크합니다:
|
|
|
|
* **보안 모델**
|
|
* **사용**
|
|
4. **저장**을 클릭합니다。
|
|
|
|
> 참고: 페이지의 이미지는 입력 위치와 예시 형식을 보여주기 위한 것입니다. 실제 내용은 사용 중인 모델 서비스 구성에 따라 입력하세요。
|
|
|
|
|
|
### 8.3 OpenClaw 인스턴스 생성
|
|
모델 구성이 완료되면 **OpenClaw Desktop** 인스턴스를 생성합니다.
|
|
|
|
1. 왼쪽 아래의 **ADMIN**을 클릭하여 **워크스페이스**로 전환합니다.
|
|
2. **인스턴스 생성**을 클릭합니다。
|
|
|
|
|
|
#### 1단계: 기본 정보
|
|
- **인스턴스 이름**을 입력합니다(최소 3자).
|
|
- 설명은 선택 사항이며 비워 둘 수 있습니다.
|
|
- **다음**을 클릭합니다.
|
|
|
|
|
|
#### 2단계: 유형 선택
|
|
- **OpenClaw Desktop**을 선택합니다.
|
|
- **다음**을 클릭합니다。
|
|
|
|
|
|
|
|
#### 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 콘솔 개요
|
|
|
|
|
|
|
|
콘솔 홈은 현재 클러스터와 플랫폼의 전체 운영 상태를 보여주며, 관리자가 리소스 사용량과 시스템 상태를 빠르게 파악할 수 있도록 합니다。
|
|
|
|
주요 내용은 다음과 같습니다：
|
|
|
|
- **클러스터 기본 정보 개요**: 현재 플랫폼의 총 사용자 수, 총 인스턴스 수, 실행 중 인스턴스 수, 총 스토리지 사용량을 표시합니다。
|
|
- **노드 개요**: 현재 사용 가능한 노드 수와 현재 클러스터의 주요 스케줄링 노드 정보를 표시합니다。
|
|
- **리소스 신청 현황**: 현재 플랫폼이 신청한 CPU, 메모리, 디스크 리소스 총량을 표시합니다。
|
|
- **용량 대시보드**: 노드, CPU, 메모리, 디스크 등 차원별로 전체 리소스 용량과 현재 사용률을 표시하여 클러스터에 사용 가능한 여유가 있는지 판단하기 쉽게 합니다。
|
|
- **기반 시설 표**: 현재 노드, 리소스 및 기본 런타임 환경의 상태 정보를 확인하는 데 사용됩니다。
|
|
|
|
> 참고: 콘솔은 주로 플랫폼 전체 리소스, 노드, 인스턴스 운영 개요를 보는 데 사용되며, 특정 인스턴스 내부의 OpenClaw 작업에 직접 사용되지는 않습니다。
|
|
|
|
### 9.2 보안 센터 (skill-scanner)
|
|
|
|
콘솔의 **보안 센터**는 플랫폼 자원의 스캔 상태, 이력 보고서, 스캐너 구성을 통합하여 확인하는 데 사용됩니다. 이 기능은 백엔드의 **skill-scanner** 서비스에 의존하여 동작하며, 자원에 대해 정적 스캔, 심층 스캔, 그리고 LLM 기반의 보조 분석을 수행하여 관리자가 잠재적인 위험 콘텐츠, 비정상 자원, 의심스러운 스킬을 식별할 수 있도록 도와줍니다.
|
|
|
|
보안 센터는 현재 다음 세 가지 주요 모듈로 구성됩니다.
|
|
|
|
* **실행 개요**
|
|
* **보고서 이력**
|
|
* **스캐너 구성**
|
|
|
|
#### 9.2.1 실행 개요
|
|
|
|
|
|
|
|
“실행 개요” 페이지는 현재 플랫폼 전체의 스캔 상태와 위험 분포를 확인하는 데 사용되며, 관리자가 현재 보안 상태를 빠르게 파악할 수 있도록 도와줍니다.
|
|
|
|
페이지에는 주로 다음과 같은 내용이 포함됩니다.
|
|
|
|
* **현재 적용 모드**: 현재 사용 중인 모드가 **Quick 모드**인지 **Deep 모드**인지 표시합니다.
|
|
* **빠른 스캔 / 전체 스캔**:
|
|
|
|
* **빠른 스캔**: 새로 추가되거나 변경된 자원을 처리하는 데 적합하며, 스캔 범위가 가볍고 실행 속도가 빠릅니다.
|
|
* **전체 스캔**: 전체 자원을 주기적으로 다시 스캔하여 현재 플랫폼의 모든 자원 상태를 완전하게 재검토하는 데 적합합니다.
|
|
* **총 자산 수**: 현재 보안 센터의 스캔 범위에 포함된 자원 수입니다.
|
|
* **완료된 스캔**: 스캔이 완료된 자원 수입니다.
|
|
* **고위험 / 중위험**: 현재 스캔 결과에서 식별된 위험 등급 통계입니다.
|
|
* **스캔 커버리지**: 실제로 스캔이 완료된 자산 수가 플랫폼 전체 자산 수에서 차지하는 비율을 표시합니다.
|
|
* **SAFE / 고위험 / 대기 중 / 실패**:
|
|
|
|
* **SAFE**: 스캔을 통과했으며 현재 위험이 발견되지 않은 자산 수
|
|
* **고위험**: 즉시 처리해야 하는 위험 자산 수
|
|
* **대기 중**: 증거 수집 대기 또는 스캔 대기열에 있는 자산 수
|
|
* **실패**: 스캔 실행에 실패하여 다시 실행해야 하는 자산 수
|
|
* **플랫폼 자산 위험 추세**: 위험 등급별로 집계된 현재 플랫폼 자산의 위험 분포를 표시합니다.
|
|
* **핫 자산**: 가장 자주 사용되는 스킬 또는 고빈도 사용 자원을 표시하여 관리자가 핵심 자산을 빠르게 파악할 수 있도록 도와줍니다.
|
|
* **스캐너 상태**: 현재 skill-scanner 의 사용 가능 여부 및 연결 상태를 표시합니다. 예: “정적 스캔 사용 가능”, “연결됨”.
|
|
* **위험 알림 및 처리 제안**: 현재 위험 상태에 따른 간단한 안내 정보를 제공합니다.
|
|
* **최근 스캔 작업**: 최근 실행된 스캔 기록을 표시하여 최근 스캔 활동을 추적하기 쉽게 합니다.
|
|
|
|
> 설명：
|
|
>
|
|
> * 페이지에 “현재 고위험 또는 중위험 자산이 없습니다”라고 표시되면, 현재 스캔 결과에서 뚜렷한 위험이 발견되지 않았음을 의미합니다.
|
|
> * 페이지에 “아직 스캔 작업 기록이 없습니다”라고 표시되면, 아직 스캔이 실행되지 않았거나 유효한 스캔 결과가 생성되지 않았음을 의미합니다.
|
|
|
|
#### 9.2.2 보고서 이력
|
|
|
|
“보고서 이력” 페이지는 과거 스캔 보고서와 관련 결과 기록을 확인하는 데 사용되며, 관리자가 이전 스캔 실행 상황을 되짚어볼 수 있도록 도와줍니다.
|
|
|
|
이 모듈은 주로 다음 용도로 사용됩니다.
|
|
|
|
* 과거에 실행된 스캔 작업 결과 확인
|
|
* 서로 다른 시점의 스캔 출력 비교
|
|
* 특정 자원이 서로 다른 단계에서 어떻게 보안 상태가 변했는지 추적 보조
|
|
* 이후 재검토, 재스캔, 문제 추적을 위한 이력 근거 제공
|
|
|
|
> 설명：
|
|
>
|
|
> * “보고서 이력”은 과거 결과의 보관과 추적에 더 중점을 둡니다；
|
|
> * “실행 개요”는 현재 상태와 전체 개요에 더 중점을 둡니다。
|
|
|
|
#### 9.2.3 스캐너 구성
|
|
|
|
|
|
|
|
“스캐너 구성” 페이지는 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 사용 현황을 집계하여 관리자가 전체 소비 상황을 파악할 수 있도록 도와줍니다.
|
|
|
|
|
|
|
|
페이지에는 주로 다음 내용이 포함됩니다.
|
|
|
|
* **입력 Token**: 입력 프롬프트 총량 통계
|
|
* **출력 Token**: 모델 생성 내용 총량 통계
|
|
* **예상 비용**: Provider 단가 기준으로 추산된 비용
|
|
* **내부 비용**: 보안 모델 관련 내부 정산 비용
|
|
* **일일 비용 추세**: 최근 7일 동안 현재 구간 내 예상 비용과 Token 변화 확인
|
|
* **사용자 요약**: 사용자별 사용량 및 비용 집계
|
|
* **인스턴스 요약**: 인스턴스별 사용량 및 비용 집계
|
|
* **최근 비용 기록**: Trace, 사용자, 모델 등 조건으로 비용 기록을 검색하고 페이지 단위로 확인하며, 감사 상세로 이동 가능
|
|
|
|
> 설명: 현재 아직 모델 호출 기록이 생성되지 않았다면 입력 Token, 출력 Token, 비용, 추세 차트가 모두 0 으로 표시될 수 있으며 이는 정상입니다。
|
|
|
|
### 9.5 AI 감사 모듈
|
|
|
|
AI 감사 페이지는 최근의 관리형 모델 호출 기록을 확인하는 데 사용되며, 관리자가 모델 호출, Token 사용, 라우팅 결과를 추적하고 점검하는 데 도움을 줍니다.
|
|
|
|
|
|
|
|
주요 기능은 다음과 같습니다.
|
|
|
|
* **최근 AI Trace**: 최근 모델 호출 체인 확인
|
|
* **Trace 목록**: 최근 관리형 Trace 를 통합 테이블에서 확인
|
|
* **검색 및 필터링**: Trace, 요청 내용, 사용자, 모델 등 조건으로 검색 가능
|
|
* **상태 필터링**: 상태별로 서로 다른 호출 결과 확인 가능
|
|
* **모델 필터링**: 모델별로 해당 호출 기록 필터링 가능
|
|
* **페이지네이션 및 새로고침**: 감사 결과를 페이지 단위로 확인하고 수동 새로고침 가능
|
|
|
|
> 설명: 페이지에 “아직 AI 감사 기록이 없습니다”라고 표시되면, 아직 실제 모델 호출 요청이 발생하지 않았음을 의미합니다。
|
|
|
|
### 9.6 위험 제어 규칙 모듈
|
|
|
|
위험 제어 규칙 페이지는 민감 콘텐츠 탐지 규칙을 구성하고, 규칙 적중 후 어떤 처리 동작을 수행할지 결정하는 데 사용됩니다.
|
|
|
|
|
|
|
|
이 모듈은 주로 다음 기능을 지원합니다.
|
|
|
|
* **규칙 목록 관리**: 전체 규칙과 활성 상태 확인
|
|
* **규칙 분류 보기**: 개인정보, 회사 정보, 고객 업무, 보안 자격 정보, 재무/법무, 정치적 민감, 사용자 정의 등 분류별로 규칙 확인 가능
|
|
* **규칙 필드 구성**: 규칙 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 워크스페이스 홈
|
|
|
|
워크스페이스 홈은 현재 계정의 인스턴스 및 리소스 사용 현황을 표시하는 데 사용되며, 주로 다음 내용을 포함합니다：
|
|
|
|
- **내 인스턴스**: 현재 계정에서 생성한 인스턴스 수를 표시합니다。
|
|
- **실행 중**: 현재 실행 중인 인스턴스 수를 표시합니다。
|
|
- **사용된 스토리지**: 현재 계정이 사용 중인 스토리지 공간을 표시합니다。
|
|
- **내 리소스 할당량**: 현재 계정에서 사용 가능한 할당량 정보(인스턴스 수, 최대 CPU 코어 수, 최대 메모리, 최대 스토리지, 최대 GPU 수)를 표시합니다。
|
|
- **빠른 작업**: **새 인스턴스 생성** 및 **모든 인스턴스 보기** 두 개의 진입점을 제공하여 플랫폼을 빠르게 사용할 수 있게 합니다。
|
|
|
|
> 참고: 페이지에 “아직 인스턴스가 없습니다”가 표시되면, 바로 **새 인스턴스 생성**을 클릭하여 첫 번째 OpenClaw Desktop 인스턴스 생성을 시작할 수 있습니다。
|
|
|
|
### 10.2 내 인스턴스
|
|
|
|
**내 인스턴스** 페이지는 현재 계정에서 생성된 인스턴스를 통합 조회 및 관리하기 위한 페이지입니다. 이 페이지는 주로 인스턴스 관리 기능을 담당합니다。
|
|
|
|
일반적으로 지원되는 작업은 다음과 같습니다：
|
|
|
|
- **인스턴스 상태 보기**: 인스턴스가 생성 중, 실행 중, 중지됨 또는 비정상 상태인지 확인합니다。
|
|
- **인스턴스 상세 진입**: 인스턴스의 기본 정보, 리소스 구성 및 실행 상태를 확인합니다。
|
|
- **인스턴스 중지**: 인스턴스가 비정상이거나 환경을 다시 로드해야 하는 경우 중지 작업을 수행할 수 있습니다。
|
|
- **인스턴스 삭제**: 인스턴스가 더 이상 필요하지 않을 때 CPU, 메모리, 스토리지 등의 리소스를 해제하기 위해 직접 삭제할 수 있습니다。
|
|
|
|
> 참고: 인스턴스를 삭제하면 관련 리소스도 함께 정리됩니다. 실행 전에 내부 데이터와 구성이 백업되었는지 확인하세요。
|
|
|
|
### 10.3 리소스 관리
|
|
|
|
**리소스 관리** 페이지는 사용 가능한 OpenClaw 리소스 내용을 유지하여, 인스턴스 시작 후 주입하고 사용할 수 있도록 하는 데 사용됩니다。
|
|
|
|
페이지에는 주로 다음 부분이 있습니다：
|
|
|
|
- **리소스**: 사용 가능한 리소스 항목을 조회하고 유지합니다。
|
|
- **리소스 패키지**: 여러 리소스를 재사용 가능한 패키지로 묶어 일괄 주입을 쉽게 합니다。
|
|
- **주입 기록**: 리소스 주입 이력과 실행 상태를 확인합니다。
|
|
|
|
리소스 관리 페이지 왼쪽에서는 리소스 유형별로 구분 관리할 수도 있으며, 현재 페이지에 표시되는 유형은 다음과 같습니다：
|
|
|
|
- **채널**
|
|
- **스킬**
|
|
- **에이전트(출시 예정)**
|
|
- **예약 작업(출시 예정)**
|
|
|
|
페이지 오른쪽 상단에서는 다음을 지원합니다：
|
|
|
|
- **새로고침**: 현재 리소스 목록을 다시 불러옵니다。
|
|
- **새로 만들기**: 새로운 리소스 항목을 생성합니다。
|
|
|
|
> 참고: 리소스 관리는 주로 인스턴스 시작 후 사용할 수 있는 OpenClaw 리소스 내용을 준비하는 데 사용되며, 인스턴스 생성 과정을 직접 대체하지는 않습니다. 인스턴스 생성 시 **수동 리소스**, **리소스 패키지**, **아카이브 가져오기** 등의 방식과 함께 리소스를 주입할 수 있습니다。
|
|
|
|
|
|
### 10.3.1 채널 생성
|
|
|
|
“채널”은 OpenClaw와 외부 메시징 플랫폼 또는 접속 대상 간의 연결 방식을 구성하는 데 사용됩니다. 예를 들어 Telegram, Slack, Feishu / Lark 등이 있습니다.
|
|
|
|
|
|
|
|
채널을 생성할 때는 다음 단계에 따라 진행합니다.
|
|
|
|
1. **리소스 관리** 페이지로 이동하고 **리소스** 탭을 유지합니다.
|
|
2. 왼쪽 리소스 유형에서 **채널**을 선택합니다.
|
|
3. 페이지 오른쪽의 **새로 만들기**를 클릭하여 “새 리소스” 팝업을 엽니다.
|
|
4. 팝업에서 기본 정보를 입력합니다.
|
|
- **유형**: **채널** 선택
|
|
- **리소스 Key**: 해당 채널의 고유 식별자를 입력합니다. 식별하기 쉽고 중복되지 않는 영문명 또는 조합명을 사용하는 것을 권장합니다
|
|
- **이름**: 채널 표시 이름을 입력합니다
|
|
- **태그**: 선택 사항이며, 분류 및 검색에 사용됩니다
|
|
- **설명**: 선택 사항이며, 채널의 용도를 보충 설명하는 데 사용됩니다
|
|
- **사용 중**: 체크 상태를 유지하는 것을 권장합니다
|
|
5. **Channel 템플릿** 영역에서 시작 템플릿을 선택합니다. 현재 지원되는 템플릿은 다음과 같습니다.
|
|
- `Telegram`
|
|
- `DingTalk`
|
|
- `Slack`
|
|
- `Feishu / Lark`
|
|
|
|
6. 템플릿을 선택한 후 **템플릿 불러오기**를 클릭합니다. 시스템은 해당 템플릿의 기본 구성을 아래의 **내용 JSON** 영역에 자동으로 입력합니다.
|
|
7. 실제 연동 정보에 따라 **내용 JSON**의 필드 내용을 계속 추가하거나 수정합니다.
|
|
8. 설정이 올바른지 확인한 후 저장을 클릭하여 채널 생성을 완료합니다.
|
|
|
|
> 설명:
|
|
> - **Channel 템플릿**은 기본 구성을 빠르게 생성하는 데 사용됩니다;
|
|
> - **내용 JSON**은 최종적으로 적용되는 채널 구성 내용입니다;
|
|
> - 완전히 일치하는 템플릿이 없는 경우 **내용 JSON**에 직접 수동으로 설정을 입력할 수도 있습니다.
|
|
|
|
### 10.3.2 스킬 업로드
|
|
|
|
스킬은 OpenClaw에 재사용 가능한 기능을 제공하는 데 사용됩니다. 플랫폼은 아카이브 파일 업로드를 통해 스킬을 일괄 가져오는 기능을 지원합니다.
|
|
|
|
|
|
|
|
스킬을 업로드할 때는 다음 단계에 따라 진행합니다.
|
|
|
|
1. **리소스 관리** 페이지로 이동하고 **리소스** 탭을 유지합니다.
|
|
2. 왼쪽 리소스 유형에서 **스킬**을 선택합니다.
|
|
3. **파일 선택**을 클릭하여 로컬 스킬 압축 파일을 선택합니다.
|
|
4. 현재 페이지는 **`.zip`** 파일 업로드만 지원합니다.
|
|
5. 파일 선택이 완료되면 오른쪽의 **스킬 아카이브 업로드**를 클릭합니다。
|
|
6. 시스템은 업로드된 내용을 자동으로 분석하고 각 1단계 디렉터리를 하나의 스킬로 가져옵니다.
|
|
7. 업로드가 완료되면 스킬 목록에서 가져온 스킬 내용을 확인할 수 있습니다。
|
|
|
|
> 설명:
|
|
> - 스킬 아카이브는 미리 디렉터리 구조를 정리해 두는 것을 권장합니다；
|
|
> - 각 1단계 디렉터리는 하나의 독립된 스킬로 인식됩니다；
|
|
> - 업로드 후 목록이 바로 새로고침되지 않으면 페이지 오른쪽 상단의 **새로고침**을 수동으로 클릭하여 다시 불러올 수 있습니다。
|
|
---
|
|
|
|
<a id="sec-13-team"></a>
|
|
### 10.4 Team 협업
|
|
|
|
Team은 여러 OpenClaw Lite 멤버가 공통 목표를 위해 협업하게 합니다. **Teams**를 열고 멤버 템플릿을 선택한 다음 Team 이름을 입력해 만드세요. 멤버별 Runtime이나 리소스 프리셋 설정은 필요하지 않습니다.
|
|
|
|
생성 후 Team 채팅에서 Leader에게 목표를 설명합니다. Leader가 계획, 실행, 검토, 최종 종합을 조율합니다. **Execution Kanban**에서 현재 단계와 완료된 산출물을 보고, **Files**에서 공유 산출물을 확인할 수 있습니다.
|
|
|
|
자세한 내용은 [Team Workspace Quick Guide](./team-workspaces-guide_ko.md)를 참고하세요.
|
|
|
|
<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** 인스턴스 생성
|