tugcantopaloglu/openclaw-dashboard
🔐 OpenClaw AI 에이전트를 위한 안전한 실시간 모니터링 대시보드. 인증, TOTP MFA, 비용 추적, 라이브 피드, 메모리 브라우저 등.
OpenClaw 에이전트를 위한 아름답고 안전하며 실시간 모니터링 대시보드입니다. 세션 추적, API 사용량 모니터링, 비용 확인, 메모리 파일 관리, 시스템 상태 확인을 한곳에서 수행할 수 있습니다.
| 개요 | 세션 | 비용 |
|---|---|---|
 |  |  |
| 속도 제한 | 라이브 피드 | 로그 |
|---|---|---|
 |  |  |
git clone https://github.com/tugcantopaloglu/openclaw-dashboard.git cd openclaw-dashboard
export WORKSPACE_DIR=/path/to/your/openclaw/workspace
node server.js
`http://localhost:7000`을 브라우저에서 방문하세요. 처음 방문 시 사용자 이름과 비밀번호를 생성하는 **등록 화면**이 나타납니다. 등록 후에는 자격 증명으로 로그인합니다.
## 📦 설치
### 사전 요구 사항
- **Node.js** v18 이상 (`node --version`으로 확인)
- **OpenClaw** 설치 및 실행 중
- **Systemd** (선택 사항, Linux에서 서비스 설치용)
#### 선택적 종속성
| 도구 | 필요 용도 | 설치 방법 |
|------|-----------|-----------|
| `jq` | Docker 관리 페이지 | `sudo apt install jq` |
| `tmux` | Claude CLI 사용량 스크레이퍼 | `sudo apt install tmux` |
| `python3` | Claude CLI 사용량 파서 | 일반적으로 사전 설치됨 |
| `docker` | Docker 관리 페이지 | [docs.docker.com](https://docs.docker.com/engine/install/) |
### 수동 설치
1. **저장소 클론** ```bash
git clone https://github.com/tugcantopaloglu/openclaw-dashboard.git
cd openclaw-dashboard
서버가 출력합니다: ``` 🚀 Dashboard running on http://localhost:7000 🔑 Recovery token: abc123def456...
**복구 토큰 저장** — 비밀번호를 잊어버릴 경우 필요합니다.
4. **대시보드 접속**
`http://localhost:7000`을 열고 계정을 등록하세요.
### Systemd 서비스 (install.sh)
대시보드를 자동 시작 및 충돌 복구 기능이 있는 시스템 서비스로 실행하려면:```bash
sudo ./install.sh
이 작업은 다음을 수행합니다:
/etc/systemd/system/agent-dashboard.service 생성/etc/systemd/system/agent-dashboard.service.d/override.conf에 재정의 설정 생성로그 보기:```bash journalctl -u agent-dashboard -f
### Docker```bash
# Build
docker build -t openclaw-dashboard .
# Run
docker run -d \
--name openclaw-dashboard \
-p 3001:3001 \
-e WORKSPACE_DIR=/app/workspace \
-e DASHBOARD_ALLOW_HTTP=true \
-v ~/.openclaw:/home/node/.openclaw:ro \
-v ~/.openclaw/workspace:/app/workspace \
openclaw-dashboard
Docker 관리 페이지 접근을 위해 Docker socket을 전달하십시오:```bash
docker run -d
--name openclaw-dashboard
-p 3001:3001
-e WORKSPACE_DIR=/app/workspace
-e DASHBOARD_ALLOW_HTTP=true
-v ~/.openclaw:/home/node/.openclaw:ro
-v ~/.openclaw/workspace:/app/workspace
-v /var/run/docker.sock:/var/run/docker.sock:ro
--group-add $(stat -c '%g' /var/run/docker.sock)
openclaw-dashboard
### 환경 변수
| 변수 | 설명 | 기본값 |
|----------|-------------|---------|
| `DASHBOARD_PORT` | 서버 포트 | `7000` |
| `DASHBOARD_TOKEN` | 비밀번호 재설정을 위한 복구 토큰 | 시작 시 자동 생성 |
| `WORKSPACE_DIR` | OpenClaw 작업 공간 경로 | `$OPENCLAW_WORKSPACE` 또는 현재 디렉터리 |
| `OPENCLAW_DIR` | OpenClaw 설정 디렉터리 | `~/.openclaw` |
| `OPENCLAW_AGENT` | 모니터링할 에이전트 ID | `main` |
| `DASHBOARD_ALLOW_HTTP` | 로컬이 아닌 IP의 HTTP 허용 | `false` |
**예시:**```bash
# Custom port
DASHBOARD_PORT=8080 node server.js
# Custom recovery token
DASHBOARD_TOKEN=my_secret_token_12345 node server.js
# Different workspace
WORKSPACE_DIR=/mnt/data/openclaw node server.js
대시보드는 보안 서버 측 세션과 함께 사용자 이름 및 비밀번호 인증을 사용합니다.
http://localhost:7000)을 방문하세요.localStorage 사용).sessionStorage 사용).무차별 대입 공격을 방지하려면:
시간 기반 일회용 비밀번호(TOTP)로 추가 보안 계층을 제공합니다.
활성화 후, 모든 로그인 시 다음이 필요합니다:
인증 앱에 접근할 수 없는 경우(휴대폰 분실, 앱 제거 등):
중요: 작업 공간이 다른 곳에 있다면 경로 /root/clawd/data/credentials.json를 조정하세요.
비밀번호를 잊은 경우:
복구 토큰(DASHBOARD_TOKEN)은 서버 시작 시 출력됩니다. 여러 위치에서 찾을 수 있습니다:
journalctl -u agent-dashboard | grep "Recovery token"
출력:```
🔑 Recovery token: 3e6b91f352418b486a9aa9d82fbbc1b1
cat /etc/systemd/system/agent-dashboard.service.d/override.conf
찾기:```ini
Environment=DASHBOARD_TOKEN=3e6b91f352418b486a9aa9d82fbbc1b1
수동으로 설정한 경우:```bash echo $DASHBOARD_TOKEN
### 비밀번호 변경
로그인 상태에서 비밀번호를 변경하려면:
1. **보안** 페이지로 이동합니다.
2. **현재 비밀번호**를 입력합니다.
3. **새 비밀번호**를 입력합니다.
4. **"비밀번호 변경"**을 클릭합니다.
5. 다른 모든 세션이 무효화됩니다 (다른 곳에서 다시 로그인해야 함).
### 완전 계정 초기화 (최후의 수단)
모든 것이 잠겨 있고 로그인할 수 없는 경우:
1. **서버에 SSH로 접속하세요**
2. **자격 증명 파일을 삭제하세요**: ```bash
rm /root/clawd/data/credentials.json
경고: 이 작업은 사용자 이름, 비밀번호 및 MFA 설정을 삭제합니다. 메모리 파일과 감사 로그는 영향을 받지 않습니다.
대시보드는 보안 모범 사례를 기반으로 구축되었습니다:
data/audit.log에 기록됨*) 허용 안 함.bak 파일 생성대시보드는 로컬 또는 Tailscale 접근을 위해 설계되었습니다:
http://localhost:7000http://100.x.x.x:7000
DASHBOARD_ALLOW_HTTP=true 설정)기본적으로 대시보드는 로컬이 아닌 IP의 HTTP 접근을 차단합니다. 예외:
다른 네트워크의 경우, 대시보드는 HTTPS 또는 X-Forwarded-Proto: https 헤더(리버스 프록시로부터)를 요구합니다.
모든 IP에서 HTTP를 허용하려면 (권장되지 않음):```bash DASHBOARD_ALLOW_HTTP=true node server.js
### 공용 인터넷에 노출하지 마십시오
**이 대시보드는 공용 인터넷 노출에 대해 보안이 강화되지 않았습니다.** 인증 및 속도 제한이 있지만, 사설 네트워크용으로 설계되었습니다. 노출해야 한다면:
- HTTPS와 함께 리버스 프록시(nginx, Caddy) 사용
- IP 허용 목록 추가
- 대신 VPN(Tailscale, WireGuard) 고려
## 🛠️ 문제 해결
### "너무 많은 로그인 실패"
**문제:** "너무 많은 로그인 시도가 실패했습니다. 나중에 다시 시도하십시오."라는 메시지가 표시됩니다.
**해결 방법:**
- 소프트 잠금이 해제될 때까지 **15분** 기다리십시오.
- 속도 제한을 초기화하려면 서비스를 다시 시작하십시오: ```bash
systemctl restart agent-dashboard
문제: 비밀번호가 변경되었지만 로그인할 수 없습니다.
해결 방법: 복구 토큰을 사용하여 "비밀번호를 잊으셨나요?" 절차를 진행하여 새 비밀번호를 설정하세요.
문제: 6자리 TOTP 코드가 거부됩니다.
해결 방법:
문제: 브라우저에 빈 페이지 또는 연결 오류가 표시됩니다.
해결 방법:
반환해야 합니다: ```json {"authenticated": false, "requiresRegistration": false}
### "HTTPS 필요" 오류
**문제:** 브라우저에 "HTTPS 필요. localhost, Tailscale을 통해 접속하거나 HTTPS를 활성화하세요."라고 표시됩니다.
**해결 방법:**
- **localhost**를 통해 접속: `http://localhost:7000`
- **Tailscale**을 통해 접속: `http://100.x.x.x:7000`
- 환경 변수에 `DASHBOARD_ALLOW_HTTP=true` 설정 (권장하지 않음) ```bash
# Add to /etc/systemd/system/agent-dashboard.service.d/override.conf
Environment=DASHBOARD_ALLOW_HTTP=true
# Reload and restart
systemctl daemon-reload
systemctl restart agent-dashboard
문제: 새 코드를 가져온 후 대시보드에 빈 페이지가 표시됩니다.
해결 방법:
Ctrl+Shift+R (Windows/Linux) 또는 Cmd+Shift+R (macOS)대시보드는 프로그래밍 방식 액세스를 위한 REST API를 제공합니다. 모든 엔드포인트는 Authorization: Bearer <sessionToken> 헤더를 통한 인증이 필요합니다.
GET /api/auth/status — 인증 상태 확인POST /api/auth/login — 사용자 이름/비밀번호로 로그인 (+ MFA가 활성화된 경우 TOTP)POST /api/auth/register — 새 계정 등록 (자격 증명이 없는 경우에만)POST /api/auth/reset-password — 복구 토큰으로 비밀번호 재설정다른 모든 엔드포인트는 인증이 필요합니다:
GET /api/config — 대시보드 구성GET /api/sessions — 모든 에이전트 세션 목록GET /api/usage — 5시간 롤링 윈도우 사용량 데이터GET /api/costs — 일별, 모델별, 세션별 지출 데이터GET /api/system — 시스템 상태 메트릭GET /api/memory-files — 메모리 파일 목록GET /api/memory-file?path=<path> — 메모리 파일 읽기GET /api/key-files — 작업 공간 파일 목록 (스킬, 구성)GET /api/key-file?path=<name> — 작업 공간 파일 읽기POST /api/key-file — 작업 공간 파일에 쓰기 (백업 포함)GET /api/crons — 크론 작업 목록POST /api/cron/<id>/toggle — 크론 작업 활성화/비활성화자세한 요청/응답 예제는 이 README의 이전 버전을 참조하거나 브라우저의 Network 탭에서 API를 탐색하세요.
대시보드는 작업 공간 디렉토리에 데이터를 저장합니다:
자격 증명 파일 구조:```json { "username": "admin", "passwordHash": "pbkdf2_sha512$100000$...", "salt": "...", "mfaSecret": "BASE32SECRET..." // Only if MFA enabled }
## 🔗 OpenClaw 통합
대시보드는 자동으로 다음을 감지합니다:
- **세션** - `$OPENCLAW_DIR/agents/$AGENT_ID/sessions/`에서
- **Cron 작업** - `$OPENCLAW_DIR/cron/jobs.json`에서
- **메모리 파일** - `$WORKSPACE_DIR/MEMORY.md`, `HEARTBEAT.md`, `memory/*.md`에서
- **Git 저장소** - `$WORKSPACE_DIR/projects/*/`에서
- **건강 데이터** - `$WORKSPACE_DIR/data/health-history.json`에 저장됨
### 필수 파일
대시보드는 다음 파일이 존재할 때 가장 잘 작동합니다:
- `$WORKSPACE_DIR/MEMORY.md` - 에이전트 장기 메모리
- `$WORKSPACE_DIR/HEARTBEAT.md` - Heartbeat 작업 목록
- `$WORKSPACE_DIR/memory/YYYY-MM-DD.md` - 일일 메모 노트
- `$WORKSPACE_DIR/scripts/scrape-claude-usage.sh` - Claude 사용량 스크래퍼
- `$WORKSPACE_DIR/scripts/parse-claude-usage.py` - Claude 사용량 파서
- `$WORKSPACE_DIR/scripts/scrape-gemini-usage.sh` - Gemini 사용량 스크래퍼
- `$WORKSPACE_DIR/scripts/parse-gemini-usage.py` - Gemini 사용량 파서
## ⌨️ 키보드 단축키
| 키 | 동작 |
|-----|--------|
| `1` | 개요로 전환 |
| `2` | 세션으로 전환 |
| `3` | 비용으로 전환 |
| `4` | 속도 제한으로 전환 |
| `5` | 메모리로 전환 |
| `6` | 파일로 전환 |
| `7` | 라이브 피드로 전환 |
| `8` | 로그로 전환 |
| `9` | 보안으로 전환 |
| `Space` | 피드 일시정지/재개 (라이브 피드 페이지에서) |
| `/` | 검색 상자 포커스 |
| `Esc` | 모달 및 오버레이 닫기 |
| `?` | 키보드 단축키 도움말 표시 |
## 🤝 기여하기
기여를 환영합니다! 다음 지침을 따라주세요:
1. 저장소를 **Fork** 하세요
2. 기능 브랜치를 **생성**하세요 (`git checkout -b feature/amazing-feature`)
3. 변경 사항을 **커밋**하세요 (`git commit -m 'Add amazing feature'`)
4. 브랜치에 **Push**하세요 (`git push origin feature/amazing-feature`)
5. Pull Request를 **열어**주세요
### 개발 환경 설정```bash
git clone https://github.com/tugcantopaloglu/openclaw-dashboard.git
cd openclaw-dashboard
export WORKSPACE_DIR=/path/to/test/workspace
node server.js
대시보드에는 빌드 단계가 없습니다. server.js 또는 index.html을 편집하고 다시 로드하세요.
MIT 라이선스 - 자세한 내용은 LICENSE 파일을 참조하세요.
✨로 만든 Tuğcan Topaloğlu
jq (Docker 페이지), tmux + python3 (Claude CLI 사용량 스크레이퍼), docker (Docker 관리)POST /api/cron/<id>/runGET /api/logs?service=<service>&lines=<N> — 시스템 로그 가져오기POST /api/action/<action> — 빠른 작업 실행 (restart-openclaw, restart-dashboard 등)POST /api/claude-usage-scrape — Claude 사용량 스크랩 실행GET /api/claude-usage — 마지막으로 스크랩한 Claude 사용량 가져오기POST /api/gemini-usage-scrape — Gemini 사용량 스크랩 실행GET /api/gemini-usage — 마지막으로 스크랩한 Gemini 사용량 가져오기GET /api/live — 실시간 메시지의 Server-Sent Events 스트림GET /api/notifications?limit=<N> — 알림 센터용 감사 로그 이벤트POST /api/reauth — 민감한 페이지(보안, 구성) 재인증GET /api/openclaw-config — OpenClaw 구성 파일 읽기PUT /api/openclaw-config — 자동 백업 및 게이트웨이 재시작으로 구성 저장GET /api/sys-security — 시스템 보안 정보 (UFW, 포트, fail2ban, SSH 로그)GET /api/docker — Docker 컨테이너, 이미지 및 시스템 사용량 목록POST /api/docker/action — Docker 작업 (컨테이너 시작/중지/재시작, 정리)GET /api/services — systemd 서비스 목록POST /api/services/action — 서비스 작업 (시작/중지/재시작, 화이트리스트만)| 파일 | 용도 |
|---|
data/credentials.json | 사용자 이름 + 해시된 비밀번호 + MFA 비밀 |
data/audit.log | 보안 감사 추적 (10MB에서 자동 순환) |
data/health-history.json | 스파크라인용 CPU/RAM/온도/디스크 기록 |
data/claude-usage.json | 마지막으로 스크랩한 Claude 사용량 데이터 |
data/gemini-usage.json | 마지막으로 스크랩한 Gemini 사용량 데이터 |