WW-AI-Lab/openclaw-office

OpenClaw Office

English

AI 에이전트의 협업 로직을 실시간 디지털 트윈 오피스로 구현합니다.

OpenClaw Office는 OpenClaw Multi-Agent 시스템의 시각적 모니터링 및 관리 프론트엔드입니다. 등각 투영 스타일의 가상 오피스 장면을 통해 Agent의 작업 상태, 협업 링크, 도구 호출 및 리소스 소비를 실시간으로 표시하며, 완전한 콘솔 관리 인터페이스와 Chat 대화 작업 공간을 제공합니다.

핵심 은유: Agent = 디지털 직원 | Office = Agent 런타임 | 작업 공간 = Session | 회의실 = 협업 컨텍스트

OpenClaw Office는 OpenClaw를 챗봇에서 Skills 시스템으로 진화시킵니다.

단순한 대화가 아니라 재사용 가능한 스킬을 생성, 개발, 디버그 및 배포하여 각 Agent가 전문 역량을 갖추고 복잡한 작업을 협업할 수 있도록 합니다.

기능 하이라이트

✨ Skill Workbench — Skills 개발 플랫폼

Skill Workbench는 OpenClaw Office의 핵심 차별화 기능입니다. "Skill 생성 / Skill 수정 / 플로우차트 생성 / A2UI 입력 폼"을 하나의 완전한 AI 협업 개발 환경으로 통합하여 OpenClaw를 진정한 프로그래밍 가능한 Skills 시스템으로 만듭니다:

• 3페이지 중첩 라우팅: /skill-workbench(목록) → /skill-workbench/create(생성 마법사) → /skill-workbench/:slug(상세)
• 채팅 사이드바 기반 개발: 사이드바에서 AI와 대화하여 Skill을 생성 및 수정하고, 파일 변경 사항이 실시간으로 디스크에 동기화됩니다.
• FLOWCHART.md 자동 생성: 내장된 skill-workbench-mermaid-guard 가드 스킬로 규격에 맞는 컬러 Mermaid 플로우차트를 한 번에 생성하며, 단일 이미지 및 다중 이미지 모드를 지원합니다.
• 순수 Markdown 다중 이미지 미리보기: 플로우차트 미리보기가 완전히 Markdown 렌더링 체인을 통해 이루어지며, 여러 Mermaid 코드 블록을 한 번에 렌더링합니다.
• A2UI 시각적 입력 폼: 선언적 폼 스키마로, Chat의 `a2ui 코드 블록이 자동으로 인터랙티브 폼으로 렌더링됩니다. 상세 페이지에는 "A2UI 디버그" 탭이 있어 한 번에 생성 및 미리보기가 가능합니다.
• 기본 스킬 자동 설치: 워크벤치에 처음 진입할 때 임베디드 서버가 npm 패키지에 내장된 기본 Skill을 자동으로 ~/.openclaw/workspace/skills/에 복사하므로 수동 설치가 필요 없습니다.

자세한 사용 가이드는 SKILL-WORKBENCH.md를 참조하세요.

!Workflow

!A2UI

가상 오피스

• 2D 평면도 — SVG로 렌더링된 등각 오피스 장면으로, 작업 공간, 임시 작업 공간, 회의실 및 다양한 가구(책상/의자/소파/식물/커피잔)를 포함합니다.
• Agent 아바타 — agentId를 기반으로 결정론적으로 생성된 SVG 아바타로, 실시간 상태 애니메이션(유휴/작업 중/발언/도구 호출/오류)을 지원합니다.
• 협업 연결선 — Agent 간 메시지 전달의 시각적 연결입니다.
• 버블 패널 — 실시간 Markdown 텍스트 스트림 및 도구 호출 표시입니다.
• 사이드 패널 — Agent 상세 정보, Token 꺾은선 그래프, 비용 원형 차트, 활동 히트맵, 하위 Agent 관계도, 이벤트 타임라인입니다.

!office

Chat 대화 작업 공간

• 상단 내비게이션에서 직접 접근 가능한 독립 Chat 작업 공간 (/#/chat), 하단 도크 바에 빠른 실행 아이콘 유지
• 세션 관리 — 새 세션 생성, 이전 세션 전환, Agent별 라우팅, 다중 Agent 병렬 대화 지원
• 실시간 스트리밍 전사 — AI 응답을 스트리밍으로 표시하며 중단/재전송 지원
• 채팅 기록 영구 저장 — 서버가 일별로 채팅 기록을 분할 캐시하여 브라우저/기기/새로고침 간에 안정적으로 표시
• 도구 호출 시각화 — 대화 흐름에 Agent 도구 호출 상태를 포함하며 접어서 볼 수 있음
• 슬래시 명령어 — /help, /new, /reset, /model, /think, /export 등의 빠른 명령어
• 첨부 파일 지원 — 이미지 및 모든 파일 첨부 지원
• 보조 기능 — 검색, Markdown 내보내기, 집중 모드, 메시지 고정 참조
• 동적 폼 인터랙션 (A2UI) — AI 응답의 `a2ui 코드 블록이 자동으로 구조화된 폼으로 렌더링되며, 텍스트, 선택, 파일 업로드 등 다양한 필드 유형을 지원하고 제출 시 구조화된 메시지로 Agent에 다시 전송됩니다.

!chat-a2ui

콘솔

완전한 시스템 관리 인터페이스:

!console-dashboard

!console-agent

!console-setting

기타 기능

• 국제화 — 완전한 중/영문 이중 언어 지원, 런타임 언어 전환
• Mock 모드 — Gateway 연결 없이 개발 가능
• 반응형 — 모바일 최적화, 자동 2D 모드 전환

기술 스택

사전 조건

• Node.js 22+
• OpenClaw 설치 및 실행 중

OpenClaw Office는 OpenClaw의 프론트엔드로, 실행 중인 OpenClaw Gateway에 연결됩니다. Gateway 자체를 시작하거나 관리하지 않습니다.

빠른 시작

저장소를 클론할 필요 없이 가장 빠르게 실행하는 방법:

# 직접 실행 (일회용)
npx @ww-ai-lab/openclaw-office

# 또는 전역 설치
npm install -g @ww-ai-lab/openclaw-office
openclaw-office

Gateway 인증

시작 후 브라우저에 OpenClaw Office의 로그인 인터페이스가 표시되며, Gateway 연결 정보를 입력하여 인증해야 합니다:

1. Gateway URL — Gateway WebSocket 주소, 기본값 ws://localhost:18789 (백엔드 주입 구성에서 미리 채워짐)
2. Access Token — Gateway 인증 토큰 (OpenClaw 구성 파일 ~/.openclaw/openclaw.json의 gateway.auth.token 필드에서 가져옴)
3. Password (선택 사항) — Gateway 비밀번호 (비밀번호 인증이 활성화된 경우)

입력 후 "연결"을 클릭하면 시스템에 진입합니다.

설명: 로컬 배포에서 인증이 활성화되지 않은 경우 Gateway URL을 기본값으로 두고 Token을 비워둔 채 "연결"을 클릭하면 됩니다.

CLI 매개변수

설명: 이 방식은 미리 빌드된 프로덕션 버전을 실행합니다. 핫 리로드 개발이 필요하면 아래 개발 섹션을 참조하세요.

시스템 서비스로 설치 (백그라운드 실행)

OpenClaw Office를 시스템 서비스로 등록하면 부팅/로그인 시 자동으로 시작되며 수동으로 명령어를 실행할 필요가 없습니다. macOS (launchd) 및 Linux (systemd --user)를 지원합니다.

서비스 설치

# 시스템 서비스로 설치 (토큰 자동 감지, 수동 지정 가능)
openclaw-office service install

# 토큰 및 포트 지정
openclaw-office service install --token <your-token> --port 3000

설치가 완료되면 서비스가 즉시 시작되어 백그라운드에서 실행됩니다. 이후 부팅/로그인 시 서비스가 자동으로 시작됩니다.

서비스 관리 명령어

openclaw-office service status              # 서비스 상태 확인
openclaw-office service stop                # 서비스 중지
openclaw-office service start               # 서비스 시작
openclaw-office service restart             # 서비스 재시작
openclaw-office service log                 # 서비스 로그 확인
openclaw-office service log --follow        # 로그 실시간 추적
openclaw-office service uninstall           # 시스템 서비스 제거

팁: 서비스로 설치한 후 Settings 페이지의 "서비스 관리" 패널에서 Gateway 상태를 확인하고 재시작 등의 작업을 수행할 수 있습니다.

Windows (WSL2) 원클릭 시작

시스템 요구 사항: Windows 10 21H2 / Windows 11 + WSL2, Linux 배포판 (예: Ubuntu)

Windows 사용자를 위해 OpenClaw Office는 WSL2 기반 원클릭 배포方案을 제공하며, WSL에서 수동으로 종속성을 구성할 필요가 없습니다:

start-openclaw-office.cmd를 더블 클릭하면 다음 모든 작업이 완료됩니다:

1. 자동 감지 WSL 배포판 (docker-desktop 자동 건너뜀)
2. 자동 설치 Node.js 22+ 및 OpenClaw (WSL에 아직 설치되지 않은 경우)
3. 초기화 구성 OpenClaw Gateway (최초 실행 시 자동으로 토큰 생성)
4. Gateway 서비스 시작 (WSL에서 systemd 방식으로 실행)
5. Office Server 시작 (Windows 본체에서 Node.js로 실행)
6. 브라우저 자동 열기 http://127.0.0.1:5180

PowerShell을 통해 직접 호출할 수도 있습니다 (사용자 정의 매개변수 지원):

# OpenClaw 버전 및 포트 지정.\scripts\start-openclaw-office.ps1 -OpenClawVersion "2026.3.28" -OfficePort 5180 -GatewayPort 18789

# 특정 WSL 배포판 지정.\scripts\start-openclaw-office.ps1 -Distro "Ubuntu-22.04"

빠른 시작 (소스 코드에서)

1. 종속성 설치

pnpm install

2. Gateway 시작

OpenClaw Gateway가 기본 주소(localhost:18789)에서 실행 중인지 확인하세요. 다음 방법으로 시작할 수 있습니다:

• OpenClaw macOS 앱
• openclaw gateway run CLI 명령어
• 기타 배포 방식 (OpenClaw 문서 참조)

팁: 인증 토큰은 미리 구성할 필요가 없습니다. 시작 후 브라우저 로그인 인터페이스에서 입력하면 됩니다.

3. 개발 서버 시작

pnpm dev

브라우저에서 http://localhost:5180을 열고 로그인 인터페이스에서 Gateway Token을 입력한 후 연결하면 시스템에 진입합니다.

기본 주소가 아닌 Gateway(예: 원격 서버)에 연결해야 하는 경우 .env.local 파일을 생성하세요 (.gitignore에 포함되어 있어 커밋되지 않음):

cat >.env.local << 'EOF'
VITE_GATEWAY_URL=ws://192.168.1.100:18789
EOF

환경 변수

Mock 모드 (Gateway 불필요)

실행 중인 Gateway 없이 개발해야 하는 경우 Mock 모드를 활성화하세요:

VITE_MOCK=true pnpm dev

이렇게 하면 모의 Agent 데이터를 사용하여 UI를 개발할 수 있습니다.

개발

명령어

pnpm install              # 종속성 설치
pnpm dev                  # 개발 서버 시작 (port 5180)
pnpm build                # 프로덕션 버전 빌드
pnpm test                 # 테스트 실행
pnpm test:watch           # 테스트 watch 모드
pnpm typecheck            # TypeScript 타입 검사
pnpm lint                 # Oxlint 검사
pnpm format               # Oxfmt 포맷팅
pnpm check                # lint + format 검사

아키텍처

OpenClaw Office는 WebSocket을 통해 Gateway에 연결되며, 데이터 흐름은 다음과 같습니다:

OpenClaw Gateway  ──WebSocket──>  ws-client.ts  ──>  event-parser.ts  ──>  Zustand Store  ──>  React 컴포넌트
     │                                                                          │
     └── RPC (agents.list, chat.send,...)  ──>  rpc-client.ts  ──────────────>─┘

Gateway는 실시간 이벤트(agent, presence, health, heartbeat)를 브로드캐스트하고 RPC 요청에 응답합니다. 프론트엔드는 Agent 생명주기 이벤트를 시각적 상태(idle/working/speaking/tool_calling/error)로 매핑하여 오피스 장면에서 렌더링합니다.

Session 동기화 전략

• Agent 및 하위 Agent의 실시간 상태, 2D 오피스 캐릭터 이동 및 회의실 이동 효과는 기본적으로 WebSocket agent 이벤트에 의해 직접 구동됩니다.
• sessions.list는 더 이상 고빈도 실시간 구동에 사용되지 않으며, 연결 설정 후 즉시 동기화 및 60초마다 한 번씩 저빈도 reconciliation을 수행하여 이벤트 누락, 연결 복구 후 session 드리프트를 수정합니다.
• 이 전략은 Gateway CPU 부하를 줄이고 고빈도 전체 스캔이 다른 RPC 프로브에 영향을 미치는 것을 방지하기 위한 것입니다.

연락 및 교류

이메일로 연락 가능: [email protected]

또한 위챗 공식 계정: 旺哥聊AI

기여

모든 기여를 환영합니다! 새로운 시각 효과, 콘솔 기능 또는 성능 최적화 등 무엇이든 환영합니다.

1. 이 저장소를 Fork하세요.
2. 기능 브랜치를 생성하세요 (git checkout -b feature/cool-effect).
3. 변경 사항을 커밋하세요 (Conventional Commits 형식 사용).
4. Pull Request를 열어주세요.

라이선스

MIT