- Eine Kubernetes-first-Kontrollplattform zur zentralen Verwaltung von OpenClaw- und Linux-Desktop-Runtimes fuer Teams und Cluster im grossen Massstab.
+ ClawManager ist eine Kubernetes-native Control Plane fuer die Verwaltung von AI-Agent-Instanzen mit kontrolliertem AI-Zugriff, Runtime-Orchestrierung und wiederverwendbaren Ressourcen ueber mehrere Agent-Runtimes hinweg.
@@ -18,214 +18,187 @@
-
+
-## News
-
-- [2026-03-26]: 🚀🚀 Die AI-Gateway-Dokumentation und Uebersicht wurden aktualisiert, inklusive Modell-Governance, Audit-Trace, Kostenrechnung und Risikokontrolle. Siehe [AI Gateway](#ai-gateway).
-- [2026-03-20]: 🎉🎉 ClawManager Release — ClawManager ist jetzt eine Plattform zur Verwaltung virtueller Desktops und bietet Funktionen wie Batch-Bereitstellung, Webtop-Unterstützung, Zugriff über ein Desktop-Portal, Laufzeit-Image-Konfiguration, Markdown-Backup und Migration von OpenClaw-Speicher/Einstellungen, Cluster-Ressourcenübersicht sowie mehrsprachige Dokumentation.
-
-## Was Es Ist
-
-ClawManager hilft Teams dabei, Desktop-Runtimes auf Kubernetes zentral zu deployen, zu betreiben und darauf zuzugreifen.
-
-Es ist fuer Umgebungen gedacht, in denen:
+
-- Desktop-Instanzen fuer mehrere Benutzer erstellt werden muessen
-- Quotas, Images und Lebenszyklen zentral verwaltet werden sollen
-- Desktop-Dienste innerhalb des Clusters bleiben sollen
-- sicherer Browser-Zugriff ohne direkte Pod-Freigabe gebraucht wird
+
ClawManager in 60 Sekunden
-## Warum Nutzer Es Waehlen
+
+
+
-- Ein Admin-Panel fuer Benutzer, Quotas, Instanzen und Runtime-Images
-- OpenClaw-Unterstuetzung mit Import und Export von Speicher und Einstellungen
-- Sicherer Desktop-Zugriff ueber die Plattform statt direkter Service-Freigabe
-- AI Gateway fuer kontrollierten Modellzugriff, Audit-Trails, Kostenanalyse und Risikokontrolle
-- Kubernetes-naher Deployment- und Betriebsablauf
-- Geeignet sowohl fuer zentral gesteuerte Rollouts als auch fuer Self-Service-Erstellung
+
+ Ein schneller Blick auf Agent-Provisionierung, Skill-Verwaltung und -Scanning sowie AI-Gateway-Governance.
+
-## Schnellstart
+## Neuigkeiten
-### Voraussetzungen
+Wichtige aktuelle Produkt- und Dokumentations-Updates.
-- Ein funktionierender Kubernetes-Cluster
-- `kubectl get nodes` funktioniert
+- [2026-04-08] Skill-Verwaltung und Skill-Scanning wurden der Plattform hinzugefuegt. Details siehe [Merged PR #52](https://github.com/Yuan-lab-LLM/ClawManager/pull/52).
+- [2026-03-26] Die AI-Gateway-Dokumentation wurde erweitert und deckt nun Modell-Governance, Audit und Trace, Kostenrechnung sowie Risikokontrolle genauer ab. Siehe [AI Gateway Guide](./docs/aigateway.md).
+- [2026-03-20] ClawManager hat sich zu einer breiteren Control Plane fuer AI-Agent-Workspaces entwickelt, mit staerkerer Runtime-Steuerung, wiederverwendbaren Ressourcen und Security-Scanning-Workflows.
-### Deployment
+> Wenn ClawManager fuer dein Team nuetzlich ist, gib dem Projekt gerne einen Star, damit mehr Nutzer und Entwickler es entdecken.
-Das mitgelieferte Manifest direkt anwenden:
+
-```bash
-kubectl apply -f deployments/k8s/clawmanager.yaml
-kubectl get pods -A
-kubectl get svc -A
-```
+
+## Produktueberblick
-**Hinweis:** Wir stellen zwei Deployment-Manifeste bereit. Wählen Sie basierend auf Ihrer Umgebung:
-- `deployments/k8s/clawmanager.yaml` - Für Standard-Kubernetes-Cluster mit ausreichenden Ressourcen. Enthält MinIO für Objektspeicher und Skill Scanner für Skill-Management.
-- `deployments/k3s/clawmanager.yaml` - Für K3s-Cluster oder ressourcenbeschränkte Umgebungen. Enthält Skill Scanner, verwendet jedoch das lokale Dateisystem anstelle von MinIO für die Speicherung.
+ClawManager bringt den Betrieb von AI-Agent-Instanzen auf Kubernetes und legt darauf drei hoeherwertige Control Planes. Teams koennen damit AI-Zugriff steuern, Runtime-Verhalten ueber Agents orchestrieren und Workspace-Faehigkeiten ueber scanbare und wiederverwendbare channel- und skill-Ressourcen bereitstellen.
-## Aus Dem Quellcode Bauen
+Es eignet sich besonders fuer:
-Wenn du ClawManager aus dem Quellcode starten oder paketieren moechtest, statt das mitgelieferte Kubernetes-Manifest zu verwenden:
+- Plattformteams, die AI-Agent-Instanzen fuer mehrere Nutzer betreiben
+- Betriebsteams, die Runtime-Sichtbarkeit, Command-Dispatch und Desired-State-Kontrolle benoetigen
+- Entwicklungsteams, die Agent-Workspaces ueber wiederverwendbare Ressourcen statt ueber manuelle Konfiguration bereitstellen wollen
-### Frontend
+
+## Erste Schritte
-```bash
-cd frontend
-npm install
-npm run build
-```
+ClawManager bietet jetzt klarere Einstiegspfade sowohl fuer Standard-Kubernetes als auch fuer leichtere Cluster-Setups. Zum Evaluieren der Plattform ist es am sinnvollsten, zuerst den passenden Deployment-Pfad fuer die eigene Umgebung zu waehlen und danach dem First-Use-Flow zu folgen.
-### Backend
+- Standard-Kubernetes-Deployment: [deployments/k8s/clawmanager.yaml](./deployments/k8s/clawmanager.yaml)
+- K3s / leichtgewichtiges Deployment: [deployments/k3s/clawmanager.yaml](./deployments/k3s/clawmanager.yaml)
+- First-Login- und Schnellstart-Ablauf: [Benutzerhandbuch](./docs/use_guide_de.md)
+- Deployment-Hinweise und Architekturkontext: [Deployment Guide (English)](./docs/deployment.md)
-```bash
-cd backend
-go mod tidy
-go build -o bin/clawreef cmd/server/main.go
-```
+## Drei Control Planes
-### Docker-Image
+
+### AI Gateway
-Das komplette Applikations-Image im Repository-Root bauen:
+AI Gateway ist die Governance-Ebene fuer Modellzugriffe in ClawManager. Es stellt verwalteten Agent-Runtimes einen einheitlichen OpenAI-kompatiblen Einstiegspunkt bereit und legt Richtlinien-, Audit- und Kostenkontrollen ueber die Upstream-Provider.
-```bash
-docker build -t clawmanager:latest .
-```
+- Einheitlicher Einstiegspunkt fuer Modell-Traffic
+- Sichere Modell-Routing-Logik und policy-gesteuerte Modellauswahl
+- End-to-End-Audit- und Trace-Aufzeichnungen
+- Integrierte Kostenrechnung und Nutzungsanalyse
+- Regeln fuer Risikokontrolle mit Block- oder Umleitungslogik
-### Standardkonten
+Siehe [AI Gateway Guide (English)](./docs/aigateway.md).
-- Standard-Admin-Konto: `admin / admin123`
-- Standardpasswort fuer importierte Admin-Benutzer: `admin123`
-- Standardpasswort fuer importierte regulaere Benutzer: `user123`
+
+### Agent Control Plane
-### Erste Schritte
+Agent Control Plane ist die Runtime-Orchestrierungsschicht fuer verwaltete AI-Agent-Instanzen. Jede Instanz wird damit zu einer verwalteten Runtime, die sich registrieren, Status melden, Commands empfangen und sich am Desired State der Plattform ausrichten kann.
-1. Als Administrator anmelden.
-2. Benutzer erstellen oder importieren und Quotas vergeben.
-3. Runtime-Image-Karten in den Systemeinstellungen pruefen oder aktualisieren.
-4. Als normaler Benutzer anmelden und eine Instanz erstellen.
-5. Ueber Portal View oder Desktop Access auf den Desktop zugreifen.
+- Agent-Registrierung mit sicherem Bootstrap und Session-Lifecycle
+- Heartbeat-basierte Runtime-Status- und Health-Reports
+- Desired-State-Synchronisierung zwischen Control Plane und Instanz
+- Command-Dispatch fuer Start, Stop, Konfigurationsanwendung, Health Checks und Skill-Operationen
+- Sichtbarkeit pro Instanz fuer Agent-Status, channel, skill und Command-Historie
-## Hauptfunktionen
+Siehe [Agent Control Plane Guide (English)](./docs/agent-control-plane.md).
-- Instanz-Lifecycle-Management: erstellen, starten, stoppen, neu starten, loeschen, anzeigen und synchronisieren
-- Unterstuetzte Runtimes: `openclaw`, `webtop`, `ubuntu`, `debian`, `centos`, `custom`
-- Runtime-Image-Kartenverwaltung im Admin-Panel
-- Benutzerbezogene Quota-Kontrolle fuer CPU, Speicher, Storage, GPU und Instanzanzahl
-- Cluster-Ressourcenuebersicht fuer Nodes, CPU, Speicher und Storage
-- Tokenbasierter Desktop-Zugriff mit WebSocket-Weiterleitung
-- AI Gateway fuer Modellverwaltung, nachvollziehbare Audit-Logs, Kostenrechnung und Risikokontrolle
-- CSV-basierter Massenimport von Benutzern
-- Mehrsprachige Oberflaeche
+
+### Ressourcenverwaltung
-## AI Gateway
-### Unterstuetzte Modellservice-Plattformen
+Ressourcenverwaltung ist die wiederverwendbare Asset-Schicht fuer AI-Agent-Workspaces. Teams koennen channel und skill vorbereiten, zu bundles zusammensetzen, in Instanzen injizieren und Security-Reviews direkt in diesen Ablauf integrieren.
-ClawManager bringt integrierte Anbieter-Templates fuer folgende Plattformen mit:
+- `Channel`-Verwaltung fuer Workspace-Konnektivitaet und Integrationsvorlagen
+- `Skill`-Verwaltung fuer wiederverwendbare Faehigkeitspakete
+- `Skill Scanner`-Workflows fuer Risikoanalyse und Scan-Jobs
+- Bundle-basierte Ressourcenzusammenstellung fuer reproduzierbare Setups
+- Injection-Snapshots zur Nachverfolgung der tatsaechlich angewendeten Inhalte
-- OpenAI
-- OpenRouter
-- DeepSeek
-- SiliconFlow
-- Moonshot AI
-- Zhipu AI
-- Alibaba DashScope
-- Volcengine Ark
-- Groq
-- Together AI
-- Fireworks AI
-- xAI
-- Perplexity
-- 01.AI
-- MiniMax
-- Local / Internal Endpunkte
+Siehe [Resource Management Guide (English)](./docs/resource-management.md) und [Security / Skill Scanner Guide (English)](./docs/security-skill-scanner.md).
-`Local / Internal` kann auch fuer selbst gehostete OpenAI-kompatible Gateways, Ollama, One API und andere private Modell-Endpunkte verwendet werden.
+## Produktgalerie
+ClawManager ist so gestaltet, dass Administration, Zugriff und AI-Governance nicht wie getrennte Werkzeuge wirken, sondern wie eine zusammenhaengende Produkterfahrung.
-AI Gateway ist die Governance-Ebene fuer den Modellzugriff in ClawManager. Es bietet OpenClaw-Instanzen einen einheitlichen OpenAI-kompatiblen Einstiegspunkt und ergaenzt Upstream-Provider um Richtlinien, Audit und Kostenkontrolle.
+### Admin Console
-- Modellverwaltung fuer regulaere und sichere Modelle sowie Provider-Anbindung, Aktivierung, Endpoint-Konfiguration und Preisrichtlinien
-- End-to-End-Audit- und Trace-Aufzeichnungen fuer Requests, Responses, Routing-Entscheidungen und Risiko-Treffer
-- Eingebaute Kostenrechnung mit Token-Erfassung und Nutzungsschaetzung
-- Risikokontrolle ueber konfigurierbare Regeln mit automatischen Aktionen wie `block` und `route_secure_model`
+Die Admin-Konsole vereint Nutzer, Quotas, Runtime-Operationen, Security-Kontrollen und plattformweite Richtlinien in einer Oberflaeche. Sie ist die zentrale Arbeitsflaeche fuer Teams, die AI-Agent-Infrastruktur im grossen Massstab betreiben.
-Screenshots, die komplette Funktionsaufstellung und den Ablauf der Modellwahl und des Routings findest du in [docs/aigateway.md](./docs/aigateway.md).
+
+
+
-## Produktablauf
+### Portal Access
-1. Ein Administrator definiert Benutzer, Quotas und Runtime-Image-Richtlinien.
-2. Ein Benutzer erstellt eine OpenClaw- oder Linux-Desktop-Instanz.
-3. ClawManager erstellt und verfolgt die Kubernetes-Ressourcen.
-4. Der Benutzer greift ueber die Plattform auf den Desktop zu.
-5. Administratoren ueberwachen Zustand und Kapazitaet ueber das Dashboard.
+Das Portal bietet Nutzern einen klaren Einstiegspunkt in ihre Workspaces. Der Zugriff erfolgt browserbasiert, waehrend Runtime-Zustand und Plattformsicht erhalten bleiben, ohne dass Infrastrukturdetails direkt exponiert werden.
-## Architektur
+
+
+
-```text
-Browser
- -> ClawManager Frontend
- -> ClawManager Backend
- -> MySQL
- -> Kubernetes API
- -> Pod / PVC / Service
- -> OpenClaw / Webtop / Linux Desktop Runtime
-```
+### AI Gateway
-## Konfigurationshinweise
+AI Gateway integriert Modell-Governance direkt in die Workspace-Erfahrung. Audit-Trails, Kostentransparenz und risikobasiertes Routing machen AI-Nutzung zu einem Teil der Plattform statt zu einer losen Einzelintegration.
-- Instanz-Services laufen im internen Kubernetes-Netzwerk
-- Desktop-Zugriff geht ueber den authentifizierten Backend-Proxy
-- Runtime-Images koennen in den Systemeinstellungen ueberschrieben werden
-- Das Backend sollte idealerweise innerhalb des Clusters deployt werden
+
+
+
-Wichtige Backend-Umgebungsvariablen:
+## So funktioniert es
-- `SERVER_ADDRESS`
-- `SERVER_MODE`
-- `DB_HOST`
-- `DB_PORT`
-- `DB_USER`
-- `DB_PASSWORD`
-- `DB_NAME`
-- `JWT_SECRET`
+1. Administratoren definieren Governance-Richtlinien und wiederverwendbare Ressourcen.
+2. Nutzer erstellen oder betreten verwaltete AI-Agent-Workspaces auf Kubernetes.
+3. Agents verbinden sich mit der Control Plane und melden Runtime-Zustaende.
+4. Channel, skill und bundle werden kompiliert und auf Instanzen angewendet.
+5. AI-Traffic fliesst ueber das AI Gateway und erhaelt Audit-, Risiko- und Kostenkontrollen.
-### CSV-Importvorlage
+## Entwicklerueberblick
-```csv
-Username,Email,Role,Max Instances,Max CPU Cores,Max Memory (GB),Max Storage (GB),Max GPU Count (optional)
-```
+ClawManager ist eine Kubernetes-native Plattform mit React-Frontend, Go-Backend, MySQL fuer Zustandsdaten sowie Integrationen wie `skill-scanner` und Object Storage. Die Codebasis ist nach Produktsubsystemen organisiert, daher ist der schnellste Einstieg, mit dem passenden Guide zu beginnen und danach in den Code zu gehen.
-Hinweise:
+- Frontend fuer Admin- und Nutzeroberflaechen unter `frontend/`
+- Backend-Services, Handler, Repositorys und Migrationen unter `backend/`
+- Deployment-Assets unter `deployments/`
+- Produktdokumentation und Medien unter `docs/`
-- `Email` ist optional
-- `Max GPU Count (optional)` ist optional
-- alle anderen Spalten sind erforderlich
-
-## Benutzerhandbuch
+Siehe [Developer Guide (English)](./docs/developer-guide.md).
-Dieses Handbuch ist die Betriebsanleitung fuer Deployment und Erstinbetriebnahme von ClawManager.
-Es beschreibt kurz die Umgebungsvorbereitung, k3s/Standard-Kubernetes-Bereitstellung, Web-Start, Initialisierung nach dem ersten Login, OpenClaw-Instanzerstellung, wichtige Konsolenmodule sowie typische Probleme und Loesungswege.
+## Dokumentation
-- [Deutsches Benutzerhandbuch](./docs/use_guide_de.md)
+- [Benutzerhandbuch](./docs/use_guide_de.md)
+- [Deployment Guide (English)](./docs/deployment.md)
+- [Admin and User Guide (English)](./docs/admin-user-guide.md)
+- [Agent Control Plane Guide (English)](./docs/agent-control-plane.md)
+- [AI Gateway Guide (English)](./docs/aigateway.md)
+- [Security / Skill Scanner Guide (English)](./docs/security-skill-scanner.md)
+- [Resource Management Guide (English)](./docs/resource-management.md)
+- [Developer Guide (English)](./docs/developer-guide.md)
## Lizenz
-Dieses Projekt ist unter der MIT License veroeffentlicht.
+Dieses Projekt steht unter der MIT License.
## Open Source
Issues und Pull Requests sind willkommen.
+
+## Star History
+
+
+
+
+
+
+
+
diff --git a/README.ja.md b/README.ja.md
index ef313fd..97945f8 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -5,7 +5,7 @@
- チーム規模からクラスター規模まで、OpenClaw と Linux デスクトップランタイムを一元管理するための Kubernetes-first コントロールプレーンです。
+ ClawManager は、AI エージェントインスタンス管理のための Kubernetes ネイティブなコントロールプレーンです。ガバナンス付きの AI アクセス、ランタイムオーケストレーション、そして複数の Agent Runtime にまたがる再利用可能なリソース管理を提供します。
- 팀 규모부터 클러스터 규모까지 OpenClaw와 Linux 데스크톱 런타임을 통합 관리하기 위한 Kubernetes-first 제어 평면입니다.
+ ClawManager는 AI Agent 인스턴스 관리를 위한 Kubernetes 네이티브 컨트롤 플레인으로, 거버넌스가 적용된 AI 접근, 런타임 오케스트레이션, 그리고 여러 Agent Runtime 전반에 걸친 재사용 가능한 리소스 관리를 제공합니다.
@@ -18,214 +18,187 @@
-
+
-## News
-
-- [2026-03-26]: 🚀🚀 AI Gateway 문서와 개요를 업데이트했습니다. 모델 거버넌스, 감사 추적, 비용 정산, 위험 제어를 정리했습니다. 자세한 내용은 [AI Gateway](#ai-gateway)를 참고하세요.
-- [2026-03-20]: 🎉🎉 ClawManager 릴리스 —— ClawManager는 현재 가상 데스크톱 관리 플랫폼으로 제공되며, 일괄 배포, Webtop 지원, 데스크톱 포털 접근, 런타임 이미지 설정, OpenClaw 메모리/환경설정 Markdown 백업 및 마이그레이션, 클러스터 리소스 개요, 다국어 문서를 지원합니다.
-
-ClawManager는 Kubernetes 위에서 데스크톱 런타임의 배포, 운영, 접근을 한곳에서 관리할 수 있게 해줍니다.
+
60초 안에 보는 ClawManager
-다음과 같은 환경에 적합합니다.
+
+
+
-- 여러 사용자를 위한 데스크톱 인스턴스를 만들어야 하는 경우
-- quota, 이미지, 라이프사이클을 중앙에서 관리해야 하는 경우
-- 데스크톱 서비스를 클러스터 내부에 유지하고 싶은 경우
-- Pod를 직접 노출하지 않고 안전한 브라우저 접근을 제공하고 싶은 경우
+
+ 빠른 Agent 프로비저닝, Skill 관리와 스캔, AI Gateway 거버넌스를 짧게 확인할 수 있습니다.
+
-## 선택하는 이유
+## 최신 업데이트
-- 사용자, quota, 인스턴스, 런타임 이미지를 하나의 관리 화면에서 운영
-- OpenClaw 메모리와 설정의 가져오기/내보내기 지원
-- 서비스를 직접 노출하지 않고 플랫폼을 통한 안전한 데스크톱 접근
-- AI Gateway를 통한 통제된 모델 접근, 감사 추적, 비용 분석, 위험 제어
-- Kubernetes에 자연스럽게 맞는 배포 및 운영 흐름
-- 관리자 주도 배포와 셀프서비스 생성 모두 지원
+최근의 중요한 제품 및 문서 업데이트입니다.
-## 빠른 시작
+- [2026-04-08] 플랫폼에 Skill 관리와 Skill 스캔 워크플로우가 추가되었습니다. 자세한 내용은 [Merged PR #52](https://github.com/Yuan-lab-LLM/ClawManager/pull/52)를 참고하세요.
+- [2026-03-26] AI Gateway 문서를 업데이트하여 모델 거버넌스, 감사와 추적, 비용 계산, 리스크 제어 설명을 강화했습니다. 자세한 내용은 [AI Gateway Guide](./docs/aigateway.md)를 참고하세요.
+- [2026-03-20] ClawManager는 AI Agent 워크스페이스를 위한 더 넓은 컨트롤 플레인으로 발전했으며, 런타임 제어, 재사용 가능한 리소스, 보안 스캔 워크플로우가 강화되었습니다.
-### 사전 조건
+> ClawManager가 여러분의 팀에 도움이 된다면, 프로젝트에 Star를 남겨 더 많은 사용자와 개발자가 발견할 수 있도록 도와주세요.
-- 사용 가능한 Kubernetes 클러스터
-- `kubectl get nodes` 가 정상 동작해야 함
+
-### 배포
+
+## 제품 소개
-저장소에 포함된 매니페스트를 그대로 적용합니다.
+ClawManager는 AI Agent 인스턴스 운영을 Kubernetes 위로 확장하고, 그 런타임 기반 위에 3개의 상위 컨트롤 플레인을 제공합니다. 팀은 이를 통해 AI 접근을 통제하고, Agent를 통해 런타임 동작을 오케스트레이션하며, 스캔 가능하고 재사용 가능한 channel 및 skill 리소스로 워크스페이스 기능을 제공할 수 있습니다.
-```bash
-kubectl apply -f deployments/k8s/clawmanager.yaml
-kubectl get pods -A
-kubectl get svc -A
-```
+다음과 같은 팀에 적합합니다.
-**참고:** 두 가지 배포 매니페스트를 제공합니다. 환경에 따라 선택하세요:
-- `deployments/k8s/clawmanager.yaml` - 리소스가 충분한 표준 Kubernetes 클러스터용입니다. MinIO 객체 스토리지와 Skill Scanner 스킬 관리를 포함합니다.
-- `deployments/k3s/clawmanager.yaml` - K3s 클러스터 또는 리소스 제한 환경용입니다. Skill Scanner를 포함하지만 MinIO 대신 로컬 파일 시스템을 사용하여 저장합니다.
+- 여러 사용자를 대상으로 AI Agent 인스턴스를 운영하는 플랫폼 팀
+- 런타임 가시성, 명령 배포, desired state 제어가 필요한 운영 팀
+- 수동 설정 대신 재사용 가능한 리소스로 Agent 워크스페이스를 제공하고 싶은 개발 팀
-## 소스 코드에서 빌드
+
+## 시작하기
-저장소에 포함된 Kubernetes 매니페스트 대신 소스 코드에서 ClawManager를 실행하거나 패키징하려면:
+ClawManager는 이제 표준 Kubernetes 환경과 경량 클러스터 환경 모두에 대해 더 명확한 진입 경로를 제공합니다. 먼저 자신의 환경에 맞는 배포 경로를 선택한 뒤, 첫 로그인 및 기본 사용 흐름으로 이어가면 됩니다.
-### 프런트엔드
+- 표준 Kubernetes 배포: [deployments/k8s/clawmanager.yaml](./deployments/k8s/clawmanager.yaml)
+- K3s / 경량 클러스터 배포: [deployments/k3s/clawmanager.yaml](./deployments/k3s/clawmanager.yaml)
+- 첫 로그인 및 기본 사용 흐름: [사용자 가이드](./docs/use_guide_ko.md)
+- 배포 설명 및 아키텍처 배경: [Deployment Guide (English)](./docs/deployment.md)
-```bash
-cd frontend
-npm install
-npm run build
-```
+## 세 가지 컨트롤 플레인
-### 백엔드
+
+### AI Gateway
-```bash
-cd backend
-go mod tidy
-go build -o bin/clawreef cmd/server/main.go
-```
+AI Gateway는 ClawManager에서 모델 접근을 거버넌스하는 컨트롤 플레인입니다. 관리되는 Agent Runtime에 통합된 OpenAI 호환 진입점을 제공하고, 상위 모델 제공자 위에 정책, 감사, 비용 제어를 추가합니다.
-### Docker 이미지
+- 모델 트래픽을 위한 통합 진입점
+- 보안 모델 라우팅과 정책 기반 모델 선택
+- 엔드투엔드 감사 및 추적 기록
+- 내장된 비용 계산과 사용량 분석
+- 차단 또는 라우팅 전환이 가능한 리스크 제어 규칙
-저장소 루트에서 전체 애플리케이션 이미지를 빌드합니다.
+[AI Gateway Guide (English)](./docs/aigateway.md)를 참고하세요.
-```bash
-docker build -t clawmanager:latest .
-```
+
+### Agent Control Plane
-### 기본 계정
+Agent Control Plane은 관리되는 AI Agent 인스턴스를 위한 런타임 오케스트레이션 계층입니다. 각 인스턴스를 등록, 상태 보고, 명령 수신, 그리고 플랫폼 측 desired state와의 정렬이 가능한 관리형 런타임으로 만듭니다.
-- 기본 관리자 계정: `admin / admin123`
-- 가져온 관리자 사용자의 기본 비밀번호: `admin123`
-- 가져온 일반 사용자의 기본 비밀번호: `user123`
+- 보안 부트스트랩과 세션 라이프사이클 기반 Agent 등록
+- 하트비트 기반 런타임 상태 및 헬스 리포팅
+- 컨트롤 플레인과 인스턴스 간 desired state 동기화
+- 시작, 중지, 설정 적용, 헬스체크, Skill 작업을 위한 명령 배포
+- 인스턴스 단위의 Agent 상태, channel, skill, 명령 이력 가시화
-### 첫 사용 순서
+[Agent Control Plane Guide (English)](./docs/agent-control-plane.md)를 참고하세요.
-1. 관리자 계정으로 로그인합니다.
-2. 사용자를 생성하거나 가져오고 quota를 할당합니다.
-3. 시스템 설정에서 런타임 이미지 카드를 검토하거나 업데이트합니다.
-4. 일반 사용자로 로그인해 인스턴스를 생성합니다.
-5. Portal View 또는 Desktop Access를 통해 데스크톱에 접근합니다.
+
+### 리소스 관리
-## 주요 기능
+리소스 관리는 AI Agent 워크스페이스를 위한 재사용 가능한 자산 계층입니다. 팀은 channel과 skill을 준비하고, bundle로 조합하고, 인스턴스에 주입하며, 그 과정에 보안 검토를 자연스럽게 포함시킬 수 있습니다.
-- 인스턴스 라이프사이클 관리: 생성, 시작, 중지, 재시작, 삭제, 조회, 동기화
-- 지원 런타임: `openclaw`, `webtop`, `ubuntu`, `debian`, `centos`, `custom`
-- 관리자 화면에서의 런타임 이미지 카드 관리
-- CPU, 메모리, 스토리지, GPU, 인스턴스 수에 대한 사용자 단위 quota 제어
-- 노드, CPU, 메모리, 스토리지를 위한 클러스터 리소스 개요
-- 토큰 기반 데스크톱 접근과 WebSocket 포워딩
-- AI Gateway를 통한 모델 관리, 추적 가능한 감사 로그, 비용 정산, 위험 제어
-- CSV 기반 대량 사용자 가져오기
-- 다국어 인터페이스
+- `Channel` 관리: 워크스페이스 연결과 통합 템플릿
+- `Skill` 관리: 재사용 가능한 기능 패키지
+- `Skill Scanner` 워크플로우: 리스크 검토와 스캔 작업
+- bundle 기반 리소스 조합: 반복 가능한 워크스페이스 구성
+- 주입 스냅샷을 통한 실제 적용 결과 추적
-## AI Gateway
-### 지원되는 모델 서비스 플랫폼
+[Resource Management Guide (English)](./docs/resource-management.md)와 [Security / Skill Scanner Guide (English)](./docs/security-skill-scanner.md)를 참고하세요.
-ClawManager에는 다음 모델 서비스 플랫폼용 템플릿이 내장되어 있습니다.
+## 제품 갤러리
-- OpenAI
-- OpenRouter
-- DeepSeek
-- SiliconFlow
-- Moonshot AI
-- Zhipu AI
-- Alibaba DashScope
-- Volcengine Ark
-- Groq
-- Together AI
-- Fireworks AI
-- xAI
-- Perplexity
-- 01.AI
-- MiniMax
-- Local / Internal 엔드포인트
+ClawManager는 관리, 접근, AI 거버넌스를 서로 분리된 도구로 다루지 않고, 하나의 일관된 제품 경험으로 묶도록 설계되었습니다.
-`Local / Internal` 모드는 자체 호스팅 OpenAI-compatible 게이트웨이, Ollama, One API, 기타 내부 모델 엔드포인트 연결에도 사용할 수 있습니다.
+### 관리 콘솔
+관리 콘솔은 사용자, 쿼터, 런타임 작업, 보안 제어, 플랫폼 수준 정책을 하나의 화면으로 묶습니다. 대규모 AI Agent 인프라를 운영하는 팀의 핵심 작업 공간입니다.
-AI Gateway는 ClawManager에서 모델 접근을 다루는 거버넌스 평면입니다. OpenClaw 인스턴스에 단일 OpenAI 호환 진입점을 제공하고, 상위 Provider 위에 정책, 감사, 비용 제어를 추가합니다.
+
+
+
-- 일반 모델과 보안 모델 관리, Provider 연결, 활성화, 엔드포인트 설정, 가격 정책
-- 요청, 응답, 라우팅 결정, 위험 히트를 포함한 엔드 투 엔드 감사 및 추적 기록
-- 토큰 집계와 사용량 추정을 포함한 내장 비용 정산
-- 설정 가능한 규칙 기반 위험 제어와 `block`, `route_secure_model` 같은 자동 동작
+### Portal Access
-스크린샷, 전체 기능 설명, 모델 선택 및 라우팅 흐름은 [docs/aigateway.md](./docs/aigateway.md)를 참고하세요.
+Portal은 사용자에게 일관된 워크스페이스 진입점을 제공합니다. 브라우저 기반으로 접근하면서도 컨트롤 플레인과 동기화된 런타임 상태를 확인할 수 있어, 사용자가 인프라 세부 사항을 직접 다루지 않아도 됩니다.
-## 사용 흐름
+
+
+
-1. 관리자가 사용자, quota, 런타임 이미지 정책을 정의합니다.
-2. 사용자가 OpenClaw 또는 Linux 데스크톱 인스턴스를 생성합니다.
-3. ClawManager가 Kubernetes 리소스를 생성하고 상태를 추적합니다.
-4. 사용자가 플랫폼을 통해 데스크톱에 접근합니다.
-5. 관리자가 대시보드에서 상태와 용량을 모니터링합니다.
+### AI Gateway
-## 아키텍처
+AI Gateway는 모델 사용 거버넌스를 워크스페이스 경험 자체에 통합합니다. 감사 로그, 비용 가시성, 리스크 라우팅을 제공하여 AI 사용을 개별 통합이 아닌 플랫폼 기능으로 다룰 수 있게 합니다.
-```text
-Browser
- -> ClawManager Frontend
- -> ClawManager Backend
- -> MySQL
- -> Kubernetes API
- -> Pod / PVC / Service
- -> OpenClaw / Webtop / Linux Desktop Runtime
-```
+
+
+
-## 설정 메모
+## 동작 방식
-- 인스턴스 서비스는 Kubernetes 내부 네트워크에 유지됩니다
-- 데스크톱 접근은 인증된 백엔드 프록시를 통해 전달됩니다
-- 런타임 이미지는 시스템 설정에서 덮어쓸 수 있습니다
-- 백엔드는 가능하면 클러스터 내부에 배치하는 것이 좋습니다
+1. 관리자가 거버넌스 정책과 재사용 가능한 리소스를 정의합니다.
+2. 사용자가 Kubernetes에서 관리되는 AI Agent 워크스페이스를 생성하거나 진입합니다.
+3. Agent가 컨트롤 플레인에 연결해 런타임 상태를 보고합니다.
+4. Channel, skill, bundle이 컴파일되어 인스턴스에 적용됩니다.
+5. AI 트래픽은 AI Gateway를 통해 전달되며, 감사, 리스크, 비용 제어가 함께 적용됩니다.
-주요 백엔드 환경 변수:
+## 개발자 개요
-- `SERVER_ADDRESS`
-- `SERVER_MODE`
-- `DB_HOST`
-- `DB_PORT`
-- `DB_USER`
-- `DB_PASSWORD`
-- `DB_NAME`
-- `JWT_SECRET`
+ClawManager는 React 프런트엔드, Go 백엔드, 상태 저장용 MySQL, 그리고 `skill-scanner` 및 오브젝트 스토리지 통합을 포함한 Kubernetes 네이티브 플랫폼입니다. 코드베이스는 제품 서브시스템 단위로 구성되어 있으므로, 관련 가이드에서 시작한 뒤 코드로 들어가는 방식이 가장 효율적입니다.
-### CSV 가져오기 템플릿
+- 프런트엔드의 관리자 및 사용자 화면은 `frontend/`
+- 백엔드 서비스, handler, repository, migration은 `backend/`
+- 배포 자산은 `deployments/`
+- 제품 문서와 이미지 자산은 `docs/`
-```csv
-Username,Email,Role,Max Instances,Max CPU Cores,Max Memory (GB),Max Storage (GB),Max GPU Count (optional)
-```
+[Developer Guide (English)](./docs/developer-guide.md)를 참고하세요.
-메모:
+## 문서
-- `Email` 은 선택 사항입니다
-- `Max GPU Count (optional)` 은 선택 사항입니다
-- 나머지 열은 모두 필수입니다
-
-## 사용 가이드
+- [사용자 가이드](./docs/use_guide_ko.md)
+- [Deployment Guide (English)](./docs/deployment.md)
+- [Admin and User Guide (English)](./docs/admin-user-guide.md)
+- [Agent Control Plane Guide (English)](./docs/agent-control-plane.md)
+- [AI Gateway Guide (English)](./docs/aigateway.md)
+- [Security / Skill Scanner Guide (English)](./docs/security-skill-scanner.md)
+- [Resource Management Guide (English)](./docs/resource-management.md)
+- [Developer Guide (English)](./docs/developer-guide.md)
-이 가이드는 ClawManager 배포와 초기 사용을 위한 운영 문서입니다.
-환경 준비, k3s/표준 Kubernetes 배포 절차, 웹 페이지 실행, 최초 로그인 초기 설정, OpenClaw 인스턴스 생성, 콘솔 주요 모듈 설명, 자주 발생하는 문제 해결 방법을 간단히 담고 있습니다.
+## 라이선스
-- [한국어 사용 가이드](./docs/use_guide_ko.md)
+이 프로젝트는 MIT License로 공개됩니다.
-## 라이선스
+## 오픈소스
-이 프로젝트는 MIT License로 배포됩니다.
+Issue와 Pull Request를 환영합니다.
-## 오픈 소스
+## Star History
-issue와 pull request를 환영합니다.
+
+
+
+
+
+
+
diff --git a/README.md b/README.md
index 59e8316..c367dfe 100644
--- a/README.md
+++ b/README.md
@@ -5,20 +5,20 @@
- A Kubernetes-first control plane for managing OpenClaw and Linux desktop runtimes at team and cluster scale.
+ A Kubernetes-native control plane for AI agent instance management, with governed AI access, runtime orchestration, and reusable resources across multiple agent runtimes.
-## News
-
-- [2026-03-26]: 🚀🚀 AI Gateway documentation and overview were refreshed, including model governance, audit and trace, cost accounting, and risk control. See [AI Gateway](#ai-gateway).
-- [2026-03-20]: 🎉🎉 ClawManager Release — ClawManager is now a virtual desktop management platform featuring batch deployment, Webtop support, desktop portal access, runtime image settings, OpenClaw memory/preferences Markdown backup and migration, cluster resource overview, and multilingual documentation.
-
-## What It Is
-
-ClawManager helps teams deploy, operate, and access desktop runtimes on Kubernetes from one place.
-
-It is built for environments where you need to:
-
-- create desktop instances for multiple users
-- control quotas, runtime images, and lifecycle centrally
-- keep desktop services inside the cluster
-- give users secure browser access without exposing pods directly
-
-## Why Users Pick It
-
-- One admin panel for users, quotas, instances, and runtime images
-- OpenClaw support with import/export for memory and preferences
-- Secure desktop access through the platform instead of direct pod exposure
-- AI Gateway governance for controlled model access, audit trails, cost analysis, and risk controls
-- Kubernetes-native deployment and operations flow
-- Works for both admin-managed rollout and self-service instance creation
+
See ClawManager in 60 Seconds
+
+
+
-## Quick Start
+
+ A quick look at fast agent provisioning, skill management and scanning, and AI Gateway governance.
+
-### Prerequisites
+## What's New
-- A working Kubernetes cluster
-- `kubectl get nodes` works
+Recent highlights from the latest product and documentation updates.
-### Deploy
+- [2026-04-08] Added skill management and skill scanning workflows to the platform, via [Merged PR #52](https://github.com/Yuan-lab-LLM/ClawManager/pull/52).
+- [2026-03-26] AI Gateway documentation was refreshed with stronger coverage for model governance, audit and trace, cost accounting, and risk control. See the [AI Gateway Guide](./docs/aigateway.md).
+- [2026-03-20] ClawManager evolved into a broader control plane for AI agent workspaces, with stronger runtime control, reusable resources, and security scanning workflows.
-Apply the bundled manifest:
+> If ClawManager is useful to your team, please star the project to help more users and contributors discover it.
-```bash
-kubectl apply -f deployments/k8s/clawmanager.yaml
-kubectl get pods -A
-kubectl get svc -A
-```
+
-**Note:** We provide two deployment manifests. Choose based on your environment:
-- `deployments/k8s/clawmanager.yaml` - For standard Kubernetes clusters with sufficient resources. Includes MinIO for object storage and Skill Scanner for skill management.
-- `deployments/k3s/clawmanager.yaml` - For K3s clusters or resource-constrained environments. Includes Skill Scanner, but uses local filesystem for storage instead of MinIO.
-## Build From Source
+## Product Tour
-If you want to run or package ClawManager from source instead of using the bundled Kubernetes manifest:
+ClawManager brings AI agent instance operations to Kubernetes and layers three higher-level control planes on top of that runtime foundation. Teams use it to govern AI access, orchestrate runtime behavior through agents, and manage reusable channels and skills with scanning and bundle-based delivery.
-### Frontend
+It is designed for:
-```bash
-cd frontend
-npm install
-npm run build
-```
+- platform teams running AI agent instances for multiple users
+- operators who need runtime visibility, command dispatch, and desired-state control
+- builders who want governed AI access and reusable resource injection instead of manual per-instance setup
-### Backend
+## Get Started
-```bash
-cd backend
-go mod tidy
-go build -o bin/clawreef cmd/server/main.go
-```
+ClawManager now has clearer entry points for both full Kubernetes deployments and lightweight cluster setups. If you want to evaluate the product quickly, start with the guide that matches your environment and then follow the first-use walkthrough.
-### Docker Image
+- Standard Kubernetes deployment: [deployments/k8s/clawmanager.yaml](./deployments/k8s/clawmanager.yaml)
+- K3s or lightweight deployment: [deployments/k3s/clawmanager.yaml](./deployments/k3s/clawmanager.yaml)
+- Operations-oriented quick start and first login flow: [User Guide](./docs/use_guide_en.md)
+- Deployment notes and architecture-level context: [Deployment Guide](./docs/deployment.md)
-Build the full application image from the repository root:
+## Three Control Planes
-```bash
-docker build -t clawmanager:latest .
-```
+### AI Gateway
-### Default Accounts
+AI Gateway is the governance plane for model access inside ClawManager. It gives managed agent runtimes a unified OpenAI-compatible entry point while adding policy and audit controls on top of upstream providers.
-- Default admin account: `admin / admin123`
-- Default password for imported admin users: `admin123`
-- Default password for imported regular users: `user123`
+- Unified gateway entry for model traffic
+- Secure model routing and policy-aware model selection
+- End-to-end audit and trace records
+- Built-in cost accounting and usage analysis
+- Risk control rules that can block or reroute requests
-### First Use
+See the [AI Gateway Guide](./docs/aigateway.md).
-1. Log in as admin.
-2. Create or import users and assign quotas.
-3. Review or update runtime image cards in system settings.
-4. Log in as a user and create an instance.
-5. Access the desktop through Portal View or Desktop Access.
+### Agent Control Plane
-## Main Capabilities
+Agent Control Plane is the runtime orchestration layer for managed AI agent instances. It turns each instance into a managed runtime that can register, report status, receive commands, and stay aligned with platform-side desired state.
-- Instance lifecycle management: create, start, stop, restart, delete, inspect, and sync
-- Runtime types: `openclaw`, `webtop`, `ubuntu`, `debian`, `centos`, `custom`
-- Runtime image card management from the admin panel
-- User quota control for CPU, memory, storage, GPU, and instance count
-- Cluster resource overview for nodes, CPU, memory, and storage
-- Token-based desktop access with WebSocket forwarding
-- AI Gateway for model management, traceable audit logs, cost accounting, and risk control
-- CSV-based bulk user import
-- Multilingual interface
+- Agent registration with secure bootstrap and session lifecycle
+- Heartbeat-driven runtime status and health reporting
+- Desired-state synchronization between the control plane and the instance
+- Runtime command dispatch for start, stop, config apply, health checks, and skill operations
+- Instance-level visibility into agent status, channels, skills, and command history
-## AI Gateway
+See the [Agent Control Plane Guide](./docs/agent-control-plane.md).
-AI Gateway is the governance plane for model access inside ClawManager. It gives OpenClaw instances a single OpenAI-compatible entry point while adding policy, audit, and cost controls on top of upstream providers.
+### Resource Management
-- Model management for regular and secure models, provider onboarding, activation, endpoint configuration, and pricing policy
-- End-to-end audit and trace records for requests, responses, routing decisions, and risk hits
-- Built-in cost accounting with token tracking and estimated usage analysis
-- Risk control with configurable rules and automated actions such as `block` and `route_secure_model`
+Resource Management is the reusable asset layer for AI agent workspaces. It helps teams prepare channels and skills once, organize them into bundles, inject them into instances, and keep security review in the loop.
-### Supported Model Service Platforms
+- Channel management for workspace connectivity and integration templates
+- Skill management for reusable packaged capabilities
+- Skill Scanner workflows for risk review and scan operations
+- Bundle-based resource composition for repeatable workspace setup
+- Injection snapshots and runtime-level visibility into what was applied
-ClawManager includes built-in vendor templates for:
+See the [Resource Management Guide](./docs/resource-management.md) and the [Security / Skill Scanner Guide](./docs/security-skill-scanner.md).
-- OpenAI
-- OpenRouter
-- DeepSeek
-- SiliconFlow
-- Moonshot AI
-- Zhipu AI
-- Alibaba DashScope
-- Volcengine Ark
-- xAI
-- Together AI
-- Fireworks AI
-- Perplexity
-- 01.AI
-- MiniMax
-- Local / Internal endpoints
+## Product Gallery
-`Local / Internal` can also be used for self-hosted OpenAI-compatible gateways, Ollama, One API, and other private model endpoints.
+The product is designed to feel coherent across administration, workspace access, and AI governance. Instead of treating these as separate tools, ClawManager brings them into one control surface.
-For screenshots, the full feature breakdown, and the model selection and routing flow, see [docs/aigateway.md](./docs/aigateway.md).
+### Admin Console
-## Product Flow
+The admin console brings together users, quotas, runtime operations, security controls, and platform-level policies in one place. It is the operational center for teams running AI agent infrastructure at scale.
-1. An admin defines users, quotas, and runtime image policies.
-2. A user creates an OpenClaw or Linux desktop instance.
-3. ClawManager creates and tracks the Kubernetes resources.
-4. The user accesses the desktop through the platform.
-5. Admins monitor health and capacity from the dashboard.
+
+
+
-## Architecture
+### Portal Access
-```text
-Browser
- -> ClawManager Frontend
- -> ClawManager Backend
- -> MySQL
- -> Kubernetes API
- -> Pod / PVC / Service
- -> OpenClaw / Webtop / Linux Desktop Runtime
-```
+The portal experience gives users a clean entry point into their workspaces, with browser-based access and runtime visibility that stays connected to the control plane instead of exposing infrastructure details directly.
-## Configuration Notes
+
+
+
-- Instance services stay on Kubernetes internal networking
-- Desktop access goes through the authenticated backend proxy
-- Runtime images can be overridden from system settings
-- Backend deployment is best kept inside the cluster
+### AI Gateway
-Common backend environment variables:
+AI Gateway extends the workspace experience with governed model access, audit trails, cost visibility, and risk-aware routing, making AI usage manageable as part of the platform rather than an isolated integration.
-- `SERVER_ADDRESS`
-- `SERVER_MODE`
-- `DB_HOST`
-- `DB_PORT`
-- `DB_USER`
-- `DB_PASSWORD`
-- `DB_NAME`
-- `JWT_SECRET`
+
+
+
-### CSV Import Template
+## How It Works
-```csv
-Username,Email,Role,Max Instances,Max CPU Cores,Max Memory (GB),Max Storage (GB),Max GPU Count (optional)
-```
+1. Admins define governance policies and reusable resources.
+2. Users create or enter managed AI agent workspaces on Kubernetes.
+3. Agents connect back to the control plane and report runtime state.
+4. Channels, skills, and bundles are compiled and applied to instances.
+5. AI traffic flows through AI Gateway with audit, risk, and cost controls.
-Notes:
+## Developer Snapshot
-- `Email` is optional
-- `Max GPU Count (optional)` is optional
-- all other columns are required
+ClawManager is built as a Kubernetes-native platform with a React frontend, a Go backend, MySQL for state, and supporting services such as skill-scanner and object storage integrations. The repository is organized around product subsystems rather than a single monolith page, so the best developer experience is to start from the relevant guide and then move into the code.
-## User Guide
+- Frontend app and admin/user surfaces live under `frontend/`
+- Backend services, handlers, repositories, and migrations live under `backend/`
+- Deployment assets live under `deployments/`
+- Supporting product docs live under `docs/`
-This guide is an operations-oriented handbook for ClawManager deployment and first-time use.
-It covers environment preparation, k3s/Kubernetes deployment paths, web startup, first login setup, OpenClaw instance creation, common console modules, and quick troubleshooting tips.
+See the [Developer Guide](./docs/developer-guide.md).
-- [English User Guide](./docs/use_guide_en.md)
+## Documentation
+- [User Guide](./docs/use_guide_en.md)
+- [Deployment Guide](./docs/deployment.md)
+- [Admin and User Guide](./docs/admin-user-guide.md)
+- [Agent Control Plane Guide](./docs/agent-control-plane.md)
+- [AI Gateway Guide](./docs/aigateway.md)
+- [Security / Skill Scanner Guide](./docs/security-skill-scanner.md)
+- [Resource Management Guide](./docs/resource-management.md)
+- [Developer Guide](./docs/developer-guide.md)
## License
@@ -235,7 +189,6 @@ This project is licensed under the MIT License.
Issues and pull requests are welcome.
-
## Star History
diff --git a/README.zh-CN.md b/README.zh-CN.md
index eb6badf..7373f67 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -5,7 +5,7 @@
-```text
-Browser
- -> ClawManager Frontend
- -> ClawManager Backend
- -> MySQL
- -> Kubernetes API
- -> Pod / PVC / Service
- -> OpenClaw / Webtop / Linux Desktop Runtime
-```
+### AI Gateway
-## 配置说明
+AI Gateway 将模型访问治理纳入工作空间体验本身，提供审计记录、成本可见性与风险路由能力，让 AI 使用成为平台能力的一部分，而不是零散接入。
-- 实例服务保留在 Kubernetes 集群内部网络
-- 桌面访问通过已认证的后端代理转发
-- 运行时镜像可以在系统设置中覆盖
-- 后端最好部署在集群内部
+
+
+
-常用后端环境变量：
+## 工作方式
-- `SERVER_ADDRESS`
-- `SERVER_MODE`
-- `DB_HOST`
-- `DB_PORT`
-- `DB_USER`
-- `DB_PASSWORD`
-- `DB_NAME`
-- `JWT_SECRET`
+1. 管理员先定义治理策略与可复用资源。
+2. 用户在 Kubernetes 上创建或进入受管 AI Agent 工作空间。
+3. Agent 回连控制平面并上报运行时状态。
+4. Channel、skill 与 bundle 被编译并应用到实例中。
+5. AI 流量通过 AI Gateway 进入上游服务，并附带审计、风险与成本控制。
-### CSV 导入模板
+## 开发者概览
-```csv
-Username,Email,Role,Max Instances,Max CPU Cores,Max Memory (GB),Max Storage (GB),Max GPU Count (optional)
-```
+ClawManager 是一个 Kubernetes 原生平台，包含 React 前端、Go 后端、MySQL 状态存储，以及 `skill-scanner` 与对象存储等支撑组件。代码库按产品子系统组织，因此更适合从对应能力的指南切入，再进入代码实现。
-说明：
+- 前端管理界面与用户界面位于 `frontend/`
+- 后端服务、handler、repository 与 migration 位于 `backend/`
+- 部署资产位于 `deployments/`
+- 产品文档与素材位于 `docs/`
-- `Email` 为可选项
-- `Max GPU Count (optional)` 为可选项
-- 其他列均为必填项
-
-## 使用手册
+参见 [Developer Guide（英文）](./docs/developer-guide.md)。
-本手册是 ClawManager 的部署与上手操作文档。
-内容涵盖环境准备、k3s/标准 Kubernetes 部署流程、Web 页面启动、首次登录初始化、OpenClaw 实例创建、控制台核心模块说明，以及常见问题与排查建议。
+## 文档
-- [简体中文使用手册](./docs/use_guide_cn.md)
+- [用户指南](./docs/use_guide_cn.md)
+- [Deployment Guide（英文）](./docs/deployment.md)
+- [Admin and User Guide（英文）](./docs/admin-user-guide.md)
+- [Agent Control Plane Guide（英文）](./docs/agent-control-plane.md)
+- [AI Gateway Guide（英文）](./docs/aigateway.md)
+- [Security / Skill Scanner Guide（英文）](./docs/security-skill-scanner.md)
+- [Resource Management Guide（英文）](./docs/resource-management.md)
+- [Developer Guide（英文）](./docs/developer-guide.md)
## 许可证
-本项目基于 MIT License 发布。
+本项目基于 MIT License 开源。
-## 开源
+## 开源协作
-欢迎提交 issue 和 pull request。
+欢迎提交 Issue 与 Pull Request。
## Star History
diff --git a/docs/admin-user-guide.md b/docs/admin-user-guide.md
new file mode 100644
index 0000000..e986a4a
--- /dev/null
+++ b/docs/admin-user-guide.md
@@ -0,0 +1,36 @@
+# Admin and User Guide
+
+This guide maps the main product surfaces for administrators and end users. It is the best starting point when you want to understand how ClawManager is experienced in day-to-day use rather than how it is deployed.
+
+## Admin Experience
+
+Administrators use ClawManager to:
+
+- manage users, quotas, and platform-wide policies
+- review instances and cluster-level operations
+- govern AI Gateway models, audit trails, cost analysis, and risk rules
+- manage Security Center and `skill-scanner` operations
+- prepare reusable resources that users can apply to workspaces
+
+## User Experience
+
+End users use ClawManager to:
+
+- create or access OpenClaw workspaces
+- open workspaces through the portal experience
+- inspect runtime status, agent signals, and recent command activity
+- attach or remove skills from an instance when permitted
+- consume platform-governed AI access through AI Gateway
+
+## Product Areas
+
+- [AI Gateway Guide](./aigateway.md)
+- [Agent Control Plane Guide](./agent-control-plane.md)
+- [Resource Management Guide](./resource-management.md)
+- [Security / Skill Scanner Guide](./security-skill-scanner.md)
+
+## Suggested Walkthrough
+
+1. Start with the AI Gateway overview if your team cares most about model governance.
+2. Review Agent Control Plane if your focus is runtime visibility and operations.
+3. Review Resource Management and Security Center if you want reusable channels, skills, and scan-backed workflows.
diff --git a/docs/agent-control-plane.md b/docs/agent-control-plane.md
new file mode 100644
index 0000000..8442580
--- /dev/null
+++ b/docs/agent-control-plane.md
@@ -0,0 +1,43 @@
+# Agent Control Plane Guide
+
+Agent Control Plane is the runtime orchestration layer for OpenClaw instances in ClawManager. It allows the platform to understand live runtime state, distribute commands, and keep each managed workspace aligned with the desired state defined by the control plane.
+
+## Core Responsibilities
+
+- agent bootstrap and registration for OpenClaw instances
+- authenticated session lifecycle between the runtime agent and the platform
+- heartbeat-driven runtime and health reporting
+- desired power state and desired config revision tracking
+- command dispatch and completion tracking for runtime operations
+
+## Runtime Signals
+
+The control plane keeps a runtime view that includes:
+
+- agent identity, version, and last heartbeat
+- runtime status and OpenClaw status
+- current and desired config revision
+- reported summary data such as agent, channel, and skill counts
+- recent command history and execution outcomes
+
+## Typical Commands
+
+Examples of platform-driven runtime actions include:
+
+- start, stop, and restart operations
+- config revision apply and reload
+- health checks and system info collection
+- skill install, update, removal, quarantine, and inventory refresh
+
+## Where It Shows Up in the Product
+
+- instance detail views for agent status and runtime summaries
+- runtime command history and execution feedback
+- workflows that apply config revisions or skill-related changes to a workspace
+
+## Related Guides
+
+- [Admin and User Guide](./admin-user-guide.md)
+- [Resource Management Guide](./resource-management.md)
+- [Security / Skill Scanner Guide](./security-skill-scanner.md)
+- [Developer Guide](./developer-guide.md)
diff --git a/docs/deployment.md b/docs/deployment.md
new file mode 100644
index 0000000..634c48a
--- /dev/null
+++ b/docs/deployment.md
@@ -0,0 +1,50 @@
+# Deployment Guide
+
+ClawManager is packaged as a Kubernetes-first platform. This guide is the operational entry point for deploying the control plane, locating the relevant manifests in the repository, and understanding which services are expected to come up in a working environment.
+
+## Deployment Paths
+
+Choose the deployment path that matches your environment:
+
+- Standard Kubernetes: [`deployments/k8s/clawmanager.yaml`](../deployments/k8s/clawmanager.yaml)
+- K3s or lightweight clusters: [`deployments/k3s/clawmanager.yaml`](../deployments/k3s/clawmanager.yaml)
+- End-to-end first-use walkthrough: [User Guide](./use_guide_en.md)
+
+## What Gets Deployed
+
+- ClawManager frontend and backend
+- MySQL for application state
+- MinIO for object storage-backed features
+- `skill-scanner` for skill analysis workflows
+- Kubernetes Services used for portal, gateway, and supporting traffic paths
+
+## Repository Entry Points
+
+- Kubernetes manifest: [`deployments/k8s/clawmanager.yaml`](../deployments/k8s/clawmanager.yaml)
+- K3s manifest: [`deployments/k3s/clawmanager.yaml`](../deployments/k3s/clawmanager.yaml)
+- Container startup script: [`deployments/container/start.sh`](../deployments/container/start.sh)
+- Nginx config: [`deployments/nginx/nginx.conf`](../deployments/nginx/nginx.conf)
+
+## Deployment Workflow
+
+1. Choose the deployment path: standard Kubernetes or K3s/lightweight.
+2. Prepare the cluster, storage strategy, and image source strategy for that environment.
+3. Review the bundled manifest and adjust secrets, images, storage classes, and ingress exposure for your environment.
+4. Deploy the platform components into the cluster.
+5. Wait for the core services to become ready.
+6. Validate frontend access, AI Gateway management pages, Security Center connectivity, and runtime creation flows.
+
+## Operational Notes
+
+- ClawManager is designed around in-cluster services and platform-mediated access rather than direct pod exposure.
+- Resource Management features depend on object storage and `skill-scanner` being available.
+- Production environments should review images, credentials, TLS, persistence, and networking policies before rollout.
+
+## Related Guides
+
+- [Admin and User Guide](./admin-user-guide.md)
+- [Agent Control Plane Guide](./agent-control-plane.md)
+- [AI Gateway Guide](./aigateway.md)
+- [Security / Skill Scanner Guide](./security-skill-scanner.md)
+- [Resource Management Guide](./resource-management.md)
+- [Developer Guide](./developer-guide.md)
diff --git a/docs/developer-guide.md b/docs/developer-guide.md
new file mode 100644
index 0000000..f31b569
--- /dev/null
+++ b/docs/developer-guide.md
@@ -0,0 +1,30 @@
+# Developer Guide
+
+This guide is the codebase orientation page for contributors. ClawManager spans frontend, backend, deployment assets, and supporting product documentation, so the fastest way to get productive is to start from the subsystem you want to change.
+
+## Repository Map
+
+- `frontend/`: React application, admin surfaces, portal views, and product UI
+- `backend/`: Go services, handlers, repositories, migrations, and platform logic
+- `deployments/`: Kubernetes manifests, container bootstrap, and nginx config
+- `docs/`: product-facing guides and screenshots
+
+## Suggested Entry Points
+
+- AI governance work: [`docs/aigateway.md`](./aigateway.md)
+- runtime orchestration work: [Agent Control Plane Guide](./agent-control-plane.md)
+- reusable resource workflows: [Resource Management Guide](./resource-management.md)
+- security scanning work: [Security / Skill Scanner Guide](./security-skill-scanner.md)
+
+## Common Areas of Change
+
+- frontend pages and navigation for product surfaces such as AI Gateway, Security Center, and Config Center
+- backend services for agents, commands, resources, and scanning
+- migrations and repository logic when new control-plane state is introduced
+- deployment manifests when platform components or images change
+
+## Related Guides
+
+- [Deployment Guide](./deployment.md)
+- [Admin and User Guide](./admin-user-guide.md)
+- [AI Gateway Guide](./aigateway.md)
diff --git a/docs/resource-management.md b/docs/resource-management.md
new file mode 100644
index 0000000..dc5d83a
--- /dev/null
+++ b/docs/resource-management.md
@@ -0,0 +1,30 @@
+# Resource Management Guide
+
+Resource Management is the reusable asset layer for OpenClaw workspaces in ClawManager. It is centered on channels, skills, bundles, and the snapshots used to compile those assets into instance-ready configuration.
+
+## Main Resource Types
+
+- `Channels` for workspace connectivity and integration templates
+- `Skills` for reusable packaged capabilities
+- `Bundles` for composing repeatable resource sets
+- injection snapshots for tracking the compiled result applied to an instance
+
+## Core Workflows
+
+1. Create or import channels and skills in the OpenClaw Config Center.
+2. Organize selected resources into reusable bundles.
+3. Review scan posture for skills through Security Center.
+4. Apply resources or bundles to OpenClaw workspaces.
+5. Inspect runtime state and instance-level resource results after injection.
+
+## How It Connects to the Platform
+
+- Resource Management defines what should be delivered to a workspace.
+- Agent Control Plane applies and tracks those changes at runtime.
+- Security Center and `skill-scanner` help review the risk posture of reusable skills before broad rollout.
+
+## Related Guides
+
+- [Security / Skill Scanner Guide](./security-skill-scanner.md)
+- [Agent Control Plane Guide](./agent-control-plane.md)
+- [Admin and User Guide](./admin-user-guide.md)
diff --git a/docs/security-skill-scanner.md b/docs/security-skill-scanner.md
new file mode 100644
index 0000000..7f89131
--- /dev/null
+++ b/docs/security-skill-scanner.md
@@ -0,0 +1,30 @@
+# Security / Skill Scanner Guide
+
+Security Center is the review and scanning surface for skill assets in ClawManager. It works with `skill-scanner` to help teams understand asset coverage, risk posture, and scanning status before skills are reused across workspaces.
+
+## What It Covers
+
+- skill asset inventory across the platform
+- scan status, coverage, and recent scan jobs
+- risk-level distribution for discovered and uploaded skills
+- scanner configuration, including external analysis integrations where configured
+
+## Main Workflows
+
+1. Review the asset inventory and identify high-risk or unscanned skills.
+2. Start incremental or full scans from Security Center.
+3. Inspect recent scan jobs and detailed outcomes.
+4. Tune scanner configuration and analysis integrations.
+5. Feed scanning results back into skill approval and workspace rollout decisions.
+
+## Why It Matters
+
+- keeps reusable skills visible and reviewable
+- adds a security checkpoint to the resource supply chain
+- supports scale by replacing ad hoc per-instance trust decisions with centralized scanning workflows
+
+## Related Guides
+
+- [Resource Management Guide](./resource-management.md)
+- [Agent Control Plane Guide](./agent-control-plane.md)
+- [AI Gateway Guide](./aigateway.md)
+ 
- 
- 
+ Produktueberblick |
+ AI Gateway |
+ Agent Control Plane |
+ Ressourcenverwaltung |
+ Erste Schritte
+
+
+
+ Explore the Product |
+ AI Gateway |
+ Agent Control Plane |
+ Resource Management |
+ Get Started