@ww-ai-lab/openclaw-office 2026.3.27 → 2026.4.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.en.md +239 -0
- package/README.md +128 -169
- package/dist/assets/{ActivityHeatmap-COHupmFH.js → ActivityHeatmap-BDFjAQ43.js} +1 -1
- package/dist/assets/{CostPieChart-KSbH5jhn.js → CostPieChart-Bq2Q_XUG.js} +1 -1
- package/dist/assets/{NetworkGraph-i5pzMg_W.js → NetworkGraph-BE0tqU7M.js} +1 -1
- package/dist/assets/{TokenLineChart-Zxfb5igK.js → TokenLineChart-S8FEhT9d.js} +1 -1
- package/dist/assets/{generateCategoricalChart-C9oChPU9.js → generateCategoricalChart-3lV5YNJ4.js} +1 -1
- package/dist/assets/index-C6AnyloZ.js +482 -0
- package/dist/assets/index-CF14MXrb.css +1 -0
- package/dist/index.html +2 -2
- package/package.json +1 -1
- package/README.zh.md +0 -288
- package/dist/assets/index-9p12WfSA.js +0 -482
- package/dist/assets/index-DbkdCwsF.css +0 -1
package/README.en.md
ADDED
|
@@ -0,0 +1,239 @@
|
|
|
1
|
+
# OpenClaw Office
|
|
2
|
+
|
|
3
|
+
> [中文文档](./README.md)
|
|
4
|
+
|
|
5
|
+
> Visualize AI agent collaboration as a real-time digital twin office.
|
|
6
|
+
|
|
7
|
+
**OpenClaw Office** is the visual monitoring and management frontend for the [OpenClaw](https://github.com/openclaw/openclaw) Multi-Agent system. It renders Agent work status, collaboration links, tool calls, and resource consumption through an isometric-style virtual office scene, along with a full-featured console for system management and a Chat workspace for real-time Agent conversations.
|
|
8
|
+
|
|
9
|
+
**Core Metaphor:** Agent = Digital Employee | Office = Agent Runtime | Desk = Session | Meeting Pod = Collaboration Context
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## Features
|
|
14
|
+
|
|
15
|
+
### Virtual Office
|
|
16
|
+
|
|
17
|
+
- **2D Floor Plan** — SVG-rendered isometric office with desk zones, hot desks, meeting areas, and rich furniture (desks, chairs, sofas, plants, coffee cups)
|
|
18
|
+
- **Agent Avatars** — Deterministically generated SVG avatars from agent IDs with real-time status animations (idle, working, speaking, tool calling, error)
|
|
19
|
+
- **Collaboration Lines** — Visual connections showing inter-Agent message flow
|
|
20
|
+
- **Speech Bubbles** — Live Markdown text streaming and tool call display
|
|
21
|
+
- **Side Panels** — Agent details, Token line charts, cost pie charts, activity heatmaps, SubAgent relationship graphs, event timelines
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
### Chat Workspace
|
|
26
|
+
|
|
27
|
+
- Dedicated Chat workspace accessible via top navigation (`/#/chat`), with the dock bar retained as a quick-entry surface
|
|
28
|
+
- Session management — create new sessions, switch history, route by Agent, support multi-Agent parallel conversations
|
|
29
|
+
- Real-time streaming — stream AI responses with abort/resend support
|
|
30
|
+
- Persistent chat history — server-side per-day sharded cache (`~/.openclaw/office-cache/chat/`), stable across browsers, devices, and refreshes
|
|
31
|
+
- Tool call visualization — inline Agent tool call status (calling/completed), collapsible for detail viewing
|
|
32
|
+
- Slash commands — `/help`, `/new`, `/reset`, `/model`, `/think`, `/export` and more
|
|
33
|
+
- Attachments — support for images and arbitrary file attachments
|
|
34
|
+
- Utilities — search, Markdown export, focus mode, pinned-reference workflows
|
|
35
|
+
|
|
36
|
+
### Console
|
|
37
|
+
|
|
38
|
+
Full system management interface with dedicated pages:
|
|
39
|
+
|
|
40
|
+
| Page | Features |
|
|
41
|
+
| ------------- | -------------------------------------------------------------------------------------------------------------- |
|
|
42
|
+
| **Dashboard** | Overview stats, alert banners, Channel/Skill overview, quick navigation |
|
|
43
|
+
| **Agents** | Agent list/create/delete, detail tabs (Overview, Channels, Cron, Skills, Tools, Files) |
|
|
44
|
+
| **Channels** | Channel cards, configuration dialogs, stats, WhatsApp QR binding |
|
|
45
|
+
| **Skills** | Skill marketplace, install options, skill detail dialogs |
|
|
46
|
+
| **Cron** | Scheduled task management and statistics |
|
|
47
|
+
| **Settings** | Provider management (add/edit/model editor), appearance, Gateway, developer, advanced, about, update |
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
### Other
|
|
56
|
+
|
|
57
|
+
- **i18n** — Full Chinese/English bilingual support with runtime language switching
|
|
58
|
+
- **Mock Mode** — Develop without a live Gateway connection
|
|
59
|
+
- **Responsive** — Mobile-optimized with automatic 2D fallback
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## Tech Stack
|
|
64
|
+
|
|
65
|
+
| Layer | Technology |
|
|
66
|
+
| ---------------- | ----------------------------------------------- |
|
|
67
|
+
| Build Tool | Vite 6 |
|
|
68
|
+
| UI Framework | React 19 |
|
|
69
|
+
| 2D Rendering | SVG + CSS Animations |
|
|
70
|
+
| State Management | Zustand 5 + Immer |
|
|
71
|
+
| Styling | Tailwind CSS 4 |
|
|
72
|
+
| Routing | React Router 7 |
|
|
73
|
+
| Charts | Recharts |
|
|
74
|
+
| i18n | i18next + react-i18next |
|
|
75
|
+
| Real-time | Native WebSocket (connects to OpenClaw Gateway) |
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## Prerequisites
|
|
80
|
+
|
|
81
|
+
- **Node.js 22+**
|
|
82
|
+
- **pnpm** (package manager)
|
|
83
|
+
- **[OpenClaw](https://github.com/openclaw/openclaw)** installed and configured
|
|
84
|
+
|
|
85
|
+
OpenClaw Office is a companion frontend that connects to a running OpenClaw Gateway. It does **not** start or manage the Gateway itself.
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
## Quick Launch
|
|
90
|
+
|
|
91
|
+
The fastest way to run OpenClaw Office — no cloning required:
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
# Run directly (one-time)
|
|
95
|
+
npx @ww-ai-lab/openclaw-office
|
|
96
|
+
|
|
97
|
+
# Or install globally
|
|
98
|
+
npm install -g @ww-ai-lab/openclaw-office
|
|
99
|
+
openclaw-office
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
### Gateway Token Auto-Detection
|
|
103
|
+
|
|
104
|
+
If [OpenClaw](https://github.com/openclaw/openclaw) is installed locally, the Gateway auth token is **automatically detected** from `~/.openclaw/openclaw.json` — no manual configuration needed.
|
|
105
|
+
|
|
106
|
+
You can also provide the token explicitly:
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
openclaw-office --token <your-gateway-token>
|
|
110
|
+
# or via environment variable
|
|
111
|
+
OPENCLAW_GATEWAY_TOKEN=<token> openclaw-office
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
### CLI Options
|
|
115
|
+
|
|
116
|
+
| Flag | Description | Default |
|
|
117
|
+
| --------------------- | --------------------- | ---------------------- |
|
|
118
|
+
| `-t, --token <token>` | Gateway auth token | auto-detected |
|
|
119
|
+
| `-g, --gateway <url>` | Gateway WebSocket URL | `ws://localhost:18789` |
|
|
120
|
+
| `-p, --port <port>` | Server port | `5180` |
|
|
121
|
+
| `--host <host>` | Bind address | `0.0.0.0` |
|
|
122
|
+
| `-h, --help` | Show help | — |
|
|
123
|
+
|
|
124
|
+
> **Note:** This serves the pre-built production bundle. For development with hot reload, see [Development](#development) below.
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## Quick Start (from source)
|
|
129
|
+
|
|
130
|
+
### 1. Install Dependencies
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
pnpm install
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
### 2. Configure Gateway Connection
|
|
137
|
+
|
|
138
|
+
Create a `.env.local` file (gitignored) with your Gateway connection details:
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
cat > .env.local << 'EOF'
|
|
142
|
+
VITE_GATEWAY_URL=ws://localhost:18789
|
|
143
|
+
VITE_GATEWAY_TOKEN=<your-gateway-token>
|
|
144
|
+
EOF
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Get your Gateway token:
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
openclaw config get gateway.auth.token
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
### 3. Start the Gateway
|
|
154
|
+
|
|
155
|
+
Ensure the OpenClaw Gateway is running on the configured address (default `localhost:18789`). You can start it via:
|
|
156
|
+
|
|
157
|
+
- The OpenClaw macOS app
|
|
158
|
+
- `openclaw gateway run` CLI command
|
|
159
|
+
- Other deployment methods (see [OpenClaw documentation](https://github.com/openclaw/openclaw))
|
|
160
|
+
|
|
161
|
+
### 4. Start the Dev Server
|
|
162
|
+
|
|
163
|
+
```bash
|
|
164
|
+
pnpm dev
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
Open `http://localhost:5180` in your browser.
|
|
168
|
+
|
|
169
|
+
### Environment Variables
|
|
170
|
+
|
|
171
|
+
| Variable | Required | Default | Description |
|
|
172
|
+
| ----------------------- | ------------------------------------- | ---------------------- | ------------------------------------ |
|
|
173
|
+
| `VITE_GATEWAY_URL` | No | `ws://localhost:18789` | Gateway WebSocket address |
|
|
174
|
+
| `VITE_GATEWAY_WS_PATH` | No | `/gateway-ws` | Browser-side reverse proxy WS path |
|
|
175
|
+
| `VITE_GATEWAY_TOKEN` | Yes (when connecting to real Gateway) | — | Gateway auth token |
|
|
176
|
+
| `VITE_MOCK` | No | `false` | Enable mock mode (no Gateway needed) |
|
|
177
|
+
|
|
178
|
+
### Mock Mode (No Gateway)
|
|
179
|
+
|
|
180
|
+
To develop without a running Gateway, enable mock mode:
|
|
181
|
+
|
|
182
|
+
```bash
|
|
183
|
+
VITE_MOCK=true pnpm dev
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
This uses simulated Agent data for UI development.
|
|
187
|
+
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
## Development
|
|
191
|
+
|
|
192
|
+
### Commands
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
pnpm install # Install dependencies
|
|
196
|
+
pnpm dev # Start dev server (port 5180)
|
|
197
|
+
pnpm build # Production build
|
|
198
|
+
pnpm test # Run tests
|
|
199
|
+
pnpm test:watch # Test watch mode
|
|
200
|
+
pnpm typecheck # TypeScript type check
|
|
201
|
+
pnpm lint # Oxlint linting
|
|
202
|
+
pnpm format # Oxfmt formatting
|
|
203
|
+
pnpm check # lint + format check
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
### Architecture
|
|
207
|
+
|
|
208
|
+
OpenClaw Office connects to the Gateway via WebSocket and follows this data flow:
|
|
209
|
+
|
|
210
|
+
```
|
|
211
|
+
OpenClaw Gateway ──WebSocket──> ws-client.ts ──> event-parser.ts ──> Zustand Store ──> React Components
|
|
212
|
+
│ │
|
|
213
|
+
└── RPC (agents.list, chat.send, ...) ──> rpc-client.ts ──────────────>─┘
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
The Gateway broadcasts real-time events (`agent`, `presence`, `health`, `heartbeat`) and responds to RPC requests. The frontend maps Agent lifecycle events to visual states (idle, working, speaking, tool_calling, error) and renders them in the office scene.
|
|
217
|
+
|
|
218
|
+
### Session Synchronization Strategy
|
|
219
|
+
|
|
220
|
+
- Real-time Agent and SubAgent state, 2D office walking animation, and meeting-zone movement are driven directly by WebSocket `agent` events
|
|
221
|
+
- `sessions.list` is no longer used as a high-frequency real-time driver; it is used for immediate sync after connection and a **60-second** low-frequency reconciliation pass to recover from missed events and reconnect drift, while reusing the same response for token aggregation
|
|
222
|
+
- This strategy reduces Gateway CPU pressure and avoids letting high-frequency full-session scans interfere with other RPC probes
|
|
223
|
+
|
|
224
|
+
---
|
|
225
|
+
|
|
226
|
+
## Contributing
|
|
227
|
+
|
|
228
|
+
Contributions are welcome! Whether it's new visualization effects, console features, or performance optimizations.
|
|
229
|
+
|
|
230
|
+
1. Fork this repository
|
|
231
|
+
2. Create a feature branch (`git checkout -b feature/cool-effect`)
|
|
232
|
+
3. Commit your changes (use [Conventional Commits](https://www.conventionalcommits.org/))
|
|
233
|
+
4. Open a Pull Request
|
|
234
|
+
|
|
235
|
+
---
|
|
236
|
+
|
|
237
|
+
## License
|
|
238
|
+
|
|
239
|
+
[MIT](./LICENSE)
|
package/README.md
CHANGED
|
@@ -1,52 +1,50 @@
|
|
|
1
1
|
# OpenClaw Office
|
|
2
2
|
|
|
3
|
-
> [
|
|
3
|
+
> [English](./README.en.md)
|
|
4
4
|
|
|
5
|
-
>
|
|
5
|
+
> 将 AI 智能体的协作逻辑具象化为实时的数字孪生办公室。
|
|
6
6
|
|
|
7
|
-
**OpenClaw Office**
|
|
7
|
+
**OpenClaw Office** 是 [OpenClaw](https://github.com/openclaw/openclaw) Multi-Agent 系统的可视化监控与管理前端。它通过等距投影（Isometric）风格的虚拟办公室场景，实时展示 Agent 的工作状态、协作链路、工具调用和资源消耗，同时提供完整的控制台管理界面和 Chat 对话工作区。
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
**核心隐喻：** Agent = 数字员工 | 办公室 = Agent 运行时 | 工位 = Session | 会议室 = 协作上下文
|
|
10
10
|
|
|
11
11
|
---
|
|
12
12
|
|
|
13
|
-
##
|
|
13
|
+
## 功能概览
|
|
14
14
|
|
|
15
|
-
###
|
|
15
|
+
### 虚拟办公室
|
|
16
16
|
|
|
17
|
-
- **2D
|
|
18
|
-
- **
|
|
19
|
-
-
|
|
20
|
-
-
|
|
21
|
-
-
|
|
22
|
-
- **Side Panels** — Agent details, Token line charts, cost pie charts, activity heatmaps, SubAgent relationship graphs, event timelines
|
|
17
|
+
- **2D 平面图** — SVG 渲染的等距办公室场景，包含工位区、临时工位、会议区和丰富的家具（桌椅/沙发/植物/咖啡杯）
|
|
18
|
+
- **Agent 头像** — 基于 agentId 确定性生成的 SVG 头像，支持实时状态动画（空闲/工作中/发言/工具调用/错误）
|
|
19
|
+
- **协作连线** — Agent 间消息传递的可视化连接
|
|
20
|
+
- **气泡面板** — 实时 Markdown 文本流和工具调用展示
|
|
21
|
+
- **侧边面板** — Agent 详情、Token 折线图、成本饼图、活跃热力图、子 Agent 关系图、事件时间轴
|
|
23
22
|
|
|
24
|
-
|
|
23
|
+
|
|
25
24
|
|
|
26
|
-
|
|
27
|
-
- Session switching, new-session creation, agent targeting, live streaming transcript, and abort support
|
|
28
|
-
- Slash commands, image attachments, search, export, focus mode, and pinned-reference workflows
|
|
25
|
+
### Chat 对话工作区
|
|
29
26
|
|
|
30
|
-
|
|
27
|
+
- 顶部导航可直达的独立 Chat 工作区（`/#/chat`），底部停靠栏保留为快捷入口
|
|
28
|
+
- 会话管理 — 创建新会话、切换历史会话、按 Agent 路由，支持多 Agent 并行对话
|
|
29
|
+
- 实时流式转录 — 流式展示 AI 回复，支持中止/重发
|
|
30
|
+
- 聊天历史持久化 — 服务端按天分片缓存聊天记录（`~/.openclaw/office-cache/chat/`），跨浏览器/设备/刷新稳定可见
|
|
31
|
+
- 工具调用可视化 — 在对话流中嵌入 Agent 工具调用状态（调用中/已完成），可折叠查看
|
|
32
|
+
- 斜杠命令 — `/help`、`/new`、`/reset`、`/model`、`/think`、`/export` 等快捷指令
|
|
33
|
+
- 附件支持 — 支持图片及任意文件附件
|
|
34
|
+
- 辅助功能 — 搜索、导出 Markdown、专注模式、消息置顶引用
|
|
31
35
|
|
|
32
|
-
|
|
36
|
+
### 控制台
|
|
33
37
|
|
|
34
|
-
|
|
38
|
+
完整的系统管理界面：
|
|
35
39
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
|
43
|
-
|
|
|
44
|
-
| **Dashboard** | Overview stats, alert banners, Channel/Skill overview, quick navigation |
|
|
45
|
-
| **Agents** | Agent list/create/delete, detail tabs (Overview, Channels, Cron, Skills, Tools, Files) |
|
|
46
|
-
| **Channels** | Channel cards, configuration dialogs, stats, WhatsApp QR binding |
|
|
47
|
-
| **Skills** | Skill marketplace, install options, skill detail dialogs |
|
|
48
|
-
| **Cron** | Scheduled task management and statistics |
|
|
49
|
-
| **Settings** | Provider management (add/edit/model editor, system-discovered providers like OpenAI Codex OAuth), appearance, Gateway, developer, advanced, about, update |
|
|
40
|
+
| 页面 | 功能 |
|
|
41
|
+
| ------------- | -------------------------------------------------------------------------------------------------------------------- |
|
|
42
|
+
| **Dashboard** | 概览统计卡片、告警横幅、Channel/Skill 概览、快捷导航 |
|
|
43
|
+
| **Agents** | Agent 列表/创建/删除，详情多 Tab（Overview/Channels/Cron/Skills/Tools/Files） |
|
|
44
|
+
| **Channels** | 渠道卡片、配置对话框、统计、WhatsApp QR 绑定流程 |
|
|
45
|
+
| **Skills** | 技能市场、安装选项、技能详情 |
|
|
46
|
+
| **Cron** | 定时任务管理和统计 |
|
|
47
|
+
| **Settings** | Provider 管理（添加/编辑/模型编辑器）、外观/Gateway/开发者/高级/关于/更新 |
|
|
50
48
|
|
|
51
49
|
|
|
52
50
|
|
|
@@ -54,235 +52,196 @@ Full system management interface with dedicated pages:
|
|
|
54
52
|
|
|
55
53
|
|
|
56
54
|
|
|
57
|
-
###
|
|
55
|
+
### 其他特性
|
|
58
56
|
|
|
59
|
-
-
|
|
60
|
-
- **Mock
|
|
61
|
-
-
|
|
57
|
+
- **国际化** — 完整的中英文双语支持，运行时语言切换
|
|
58
|
+
- **Mock 模式** — 无需连接 Gateway 即可开发
|
|
59
|
+
- **响应式** — 移动端优化，自动切换 2D 模式
|
|
62
60
|
|
|
63
61
|
---
|
|
64
62
|
|
|
65
|
-
##
|
|
66
|
-
|
|
67
|
-
|
|
|
68
|
-
|
|
|
69
|
-
|
|
|
70
|
-
| UI
|
|
71
|
-
| 2D
|
|
72
|
-
|
|
|
73
|
-
|
|
|
74
|
-
|
|
|
75
|
-
|
|
|
76
|
-
|
|
|
77
|
-
|
|
|
78
|
-
| Real-time | Native WebSocket (connects to OpenClaw Gateway) |
|
|
63
|
+
## 技术栈
|
|
64
|
+
|
|
65
|
+
| 层 | 技术 |
|
|
66
|
+
| -------- | ------------------------------------------- |
|
|
67
|
+
| 构建工具 | Vite 6 |
|
|
68
|
+
| UI 框架 | React 19 |
|
|
69
|
+
| 2D 渲染 | SVG + CSS Animations |
|
|
70
|
+
| 状态管理 | Zustand 5 + Immer |
|
|
71
|
+
| 样式 | Tailwind CSS 4 |
|
|
72
|
+
| 路由 | React Router 7 |
|
|
73
|
+
| 图表 | Recharts |
|
|
74
|
+
| 国际化 | i18next + react-i18next |
|
|
75
|
+
| 实时通信 | 原生 WebSocket（对接 OpenClaw Gateway） |
|
|
79
76
|
|
|
80
77
|
---
|
|
81
78
|
|
|
82
|
-
##
|
|
79
|
+
## 前提条件
|
|
83
80
|
|
|
84
81
|
- **Node.js 22+**
|
|
85
|
-
- **pnpm
|
|
86
|
-
- **[OpenClaw](https://github.com/openclaw/openclaw)**
|
|
82
|
+
- **pnpm**（包管理器）
|
|
83
|
+
- **[OpenClaw](https://github.com/openclaw/openclaw)** 已安装并配置
|
|
87
84
|
|
|
88
|
-
OpenClaw Office
|
|
85
|
+
OpenClaw Office 是一个配套前端，连接到正在运行的 OpenClaw Gateway。它**不会**启动或管理 Gateway。
|
|
89
86
|
|
|
90
87
|
---
|
|
91
88
|
|
|
92
|
-
##
|
|
89
|
+
## 快捷启动
|
|
93
90
|
|
|
94
|
-
|
|
91
|
+
无需克隆仓库，最快速的运行方式：
|
|
95
92
|
|
|
96
93
|
```bash
|
|
97
|
-
#
|
|
94
|
+
# 直接运行（一次性使用）
|
|
98
95
|
npx @ww-ai-lab/openclaw-office
|
|
99
96
|
|
|
100
|
-
#
|
|
97
|
+
# 或全局安装
|
|
101
98
|
npm install -g @ww-ai-lab/openclaw-office
|
|
102
99
|
openclaw-office
|
|
103
100
|
```
|
|
104
101
|
|
|
105
|
-
### Gateway Token
|
|
102
|
+
### Gateway Token 自动检测
|
|
106
103
|
|
|
107
|
-
|
|
104
|
+
如果本地已安装 [OpenClaw](https://github.com/openclaw/openclaw)，Gateway 认证 token 会从 `~/.openclaw/openclaw.json` **自动读取**，无需手动配置。
|
|
108
105
|
|
|
109
|
-
|
|
106
|
+
也可以手动指定 token：
|
|
110
107
|
|
|
111
108
|
```bash
|
|
112
|
-
openclaw-office --token
|
|
113
|
-
#
|
|
109
|
+
openclaw-office --token <你的-gateway-token>
|
|
110
|
+
# 或通过环境变量
|
|
114
111
|
OPENCLAW_GATEWAY_TOKEN=<token> openclaw-office
|
|
115
112
|
```
|
|
116
113
|
|
|
117
|
-
### CLI
|
|
114
|
+
### CLI 参数
|
|
118
115
|
|
|
119
|
-
|
|
|
120
|
-
| --------------------- |
|
|
121
|
-
| `-t, --token <token>` | Gateway
|
|
122
|
-
| `-g, --gateway <url>` | Gateway WebSocket
|
|
123
|
-
| `-p, --port <port>` |
|
|
124
|
-
| `--host <host>` |
|
|
125
|
-
| `-h, --help` |
|
|
116
|
+
| 参数 | 说明 | 默认值 |
|
|
117
|
+
| --------------------- | ---------------------- | ---------------------- |
|
|
118
|
+
| `-t, --token <token>` | Gateway 认证 token | 自动检测 |
|
|
119
|
+
| `-g, --gateway <url>` | Gateway WebSocket 地址 | `ws://localhost:18789` |
|
|
120
|
+
| `-p, --port <port>` | 服务端口 | `5180` |
|
|
121
|
+
| `--host <host>` | 绑定地址 | `0.0.0.0` |
|
|
122
|
+
| `-h, --help` | 显示帮助 | — |
|
|
126
123
|
|
|
127
|
-
>
|
|
124
|
+
> **说明：** 此方式运行的是预构建的生产版本。如需热重载开发，请参见下方 [开发](#开发) 部分。
|
|
128
125
|
|
|
129
126
|
---
|
|
130
127
|
|
|
131
|
-
##
|
|
128
|
+
## 快速开始（从源码）
|
|
132
129
|
|
|
133
|
-
### 1.
|
|
130
|
+
### 1. 安装依赖
|
|
134
131
|
|
|
135
132
|
```bash
|
|
136
133
|
pnpm install
|
|
137
134
|
```
|
|
138
135
|
|
|
139
|
-
### 2.
|
|
136
|
+
### 2. 配置 Gateway 连接
|
|
140
137
|
|
|
141
|
-
|
|
138
|
+
创建 `.env.local` 文件（已在 `.gitignore` 中，不会被提交），填入 Gateway 连接信息：
|
|
142
139
|
|
|
143
140
|
```bash
|
|
144
141
|
cat > .env.local << 'EOF'
|
|
145
142
|
VITE_GATEWAY_URL=ws://localhost:18789
|
|
146
|
-
VITE_GATEWAY_TOKEN
|
|
143
|
+
VITE_GATEWAY_TOKEN=<你的 gateway token>
|
|
147
144
|
EOF
|
|
148
145
|
```
|
|
149
146
|
|
|
150
|
-
|
|
147
|
+
获取 Gateway token：
|
|
151
148
|
|
|
152
149
|
```bash
|
|
153
150
|
openclaw config get gateway.auth.token
|
|
154
151
|
```
|
|
155
152
|
|
|
156
|
-
### 3.
|
|
153
|
+
### 3. 启动 Gateway
|
|
157
154
|
|
|
158
|
-
|
|
155
|
+
确保 OpenClaw Gateway 在配置的地址上运行（默认 `localhost:18789`）。可通过以下方式启动：
|
|
159
156
|
|
|
160
|
-
- OpenClaw
|
|
161
|
-
-
|
|
157
|
+
- OpenClaw macOS 应用
|
|
158
|
+
- `openclaw gateway run` CLI 命令
|
|
159
|
+
- 其他部署方式（参见 [OpenClaw 文档](https://github.com/openclaw/openclaw)）
|
|
162
160
|
|
|
163
|
-
|
|
161
|
+
### 4. 启动开发服务器
|
|
164
162
|
|
|
165
163
|
```bash
|
|
166
|
-
|
|
164
|
+
pnpm dev
|
|
167
165
|
```
|
|
168
166
|
|
|
169
|
-
|
|
167
|
+
在浏览器中打开 `http://localhost:5180`。
|
|
170
168
|
|
|
171
|
-
###
|
|
169
|
+
### 环境变量
|
|
172
170
|
|
|
173
|
-
|
|
171
|
+
| 变量 | 必须 | 默认值 | 说明 |
|
|
172
|
+
| ----------------------- | ------------------------- | ---------------------- | -------------------------------- |
|
|
173
|
+
| `VITE_GATEWAY_URL` | 否 | `ws://localhost:18789` | Gateway WebSocket 地址 |
|
|
174
|
+
| `VITE_GATEWAY_WS_PATH` | 否 | `/gateway-ws` | 浏览器侧反向代理 WS 路径 |
|
|
175
|
+
| `VITE_GATEWAY_TOKEN` | 是（连接真实 Gateway 时） | — | Gateway 认证 token |
|
|
176
|
+
| `VITE_MOCK` | 否 | `false` | 启用 Mock 模式（不需要 Gateway） |
|
|
174
177
|
|
|
175
|
-
|
|
176
|
-
- `openclaw gateway run` CLI command
|
|
177
|
-
- Other deployment methods (see [OpenClaw documentation](https://github.com/openclaw/openclaw))
|
|
178
|
+
### Mock 模式（无需 Gateway）
|
|
178
179
|
|
|
179
|
-
|
|
180
|
+
如需在没有运行中的 Gateway 的情况下开发，启用 Mock 模式：
|
|
180
181
|
|
|
181
182
|
```bash
|
|
182
|
-
pnpm dev
|
|
183
|
+
VITE_MOCK=true pnpm dev
|
|
183
184
|
```
|
|
184
185
|
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
### Environment Variables
|
|
186
|
+
这会使用模拟的 Agent 数据进行 UI 开发。
|
|
188
187
|
|
|
189
|
-
|
|
190
|
-
| -------------------- | ------------------------------------- | ---------------------- | ------------------------------------ |
|
|
191
|
-
| `VITE_GATEWAY_URL` | No | `ws://localhost:18789` | Gateway WebSocket address |
|
|
192
|
-
| `VITE_GATEWAY_WS_PATH` | No | `/gateway-ws` | Browser-side reverse proxy WS path |
|
|
193
|
-
| `VITE_GATEWAY_TOKEN` | Yes (when connecting to real Gateway) | — | Gateway auth token |
|
|
194
|
-
| `VITE_MOCK` | No | `false` | Enable mock mode (no Gateway needed) |
|
|
188
|
+
---
|
|
195
189
|
|
|
196
|
-
|
|
190
|
+
## 开发
|
|
197
191
|
|
|
198
|
-
|
|
192
|
+
### 命令
|
|
199
193
|
|
|
200
194
|
```bash
|
|
201
|
-
|
|
195
|
+
pnpm install # 安装依赖
|
|
196
|
+
pnpm dev # 启动开发服务器 (port 5180)
|
|
197
|
+
pnpm build # 构建生产版本
|
|
198
|
+
pnpm test # 运行测试
|
|
199
|
+
pnpm test:watch # 测试 watch 模式
|
|
200
|
+
pnpm typecheck # TypeScript 类型检查
|
|
201
|
+
pnpm lint # Oxlint 检查
|
|
202
|
+
pnpm format # Oxfmt 格式化
|
|
203
|
+
pnpm check # lint + format 检查
|
|
202
204
|
```
|
|
203
205
|
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
---
|
|
206
|
+
### 架构
|
|
207
207
|
|
|
208
|
-
|
|
208
|
+
OpenClaw Office 通过 WebSocket 连接 Gateway，数据流如下：
|
|
209
209
|
|
|
210
210
|
```
|
|
211
|
-
OpenClaw-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
│ ├── i18n/ # Internationalization (zh/en)
|
|
215
|
-
│ ├── gateway/ # Gateway communication layer
|
|
216
|
-
│ │ ├── ws-client.ts # WebSocket client + auth + reconnect
|
|
217
|
-
│ │ ├── rpc-client.ts # RPC request wrapper
|
|
218
|
-
│ │ ├── event-parser.ts # Event parsing + state mapping
|
|
219
|
-
│ │ └── mock-adapter.ts # Mock mode adapter
|
|
220
|
-
│ ├── store/ # Zustand state management
|
|
221
|
-
│ │ ├── office-store.ts # Main store (Agent state, connection, UI)
|
|
222
|
-
│ │ └── console-stores/ # Per-page console stores
|
|
223
|
-
│ ├── components/
|
|
224
|
-
│ │ ├── layout/ # AppShell, ConsoleLayout, Sidebar, TopBar
|
|
225
|
-
│ │ ├── office-2d/ # 2D SVG floor plan + furniture
|
|
226
|
-
│ │ ├── office-3d/ # 3D R3F scene
|
|
227
|
-
│ │ ├── overlays/ # HTML overlays (speech bubbles)
|
|
228
|
-
│ │ ├── panels/ # Detail/metrics/chart panels
|
|
229
|
-
│ │ ├── chat/ # Shared chat workspace UI (page + dock)
|
|
230
|
-
│ │ ├── console/ # Console feature components
|
|
231
|
-
│ │ ├── pages/ # Console route pages
|
|
232
|
-
│ │ └── shared/ # Shared components
|
|
233
|
-
│ ├── hooks/ # Custom React hooks
|
|
234
|
-
│ ├── lib/ # Utility library
|
|
235
|
-
│ └── styles/ # Global styles
|
|
236
|
-
├── public/ # Static assets
|
|
237
|
-
├── tests/ # Test files
|
|
238
|
-
├── package.json
|
|
239
|
-
├── vite.config.ts
|
|
240
|
-
└── tsconfig.json
|
|
211
|
+
OpenClaw Gateway ──WebSocket──> ws-client.ts ──> event-parser.ts ──> Zustand Store ──> React 组件
|
|
212
|
+
│ │
|
|
213
|
+
└── RPC (agents.list, chat.send, ...) ──> rpc-client.ts ──────────────>─┘
|
|
241
214
|
```
|
|
242
215
|
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
## Development
|
|
216
|
+
Gateway 广播实时事件（`agent`、`presence`、`health`、`heartbeat`）并响应 RPC 请求。前端将 Agent 生命周期事件映射为可视化状态（idle/working/speaking/tool_calling/error），在办公室场景中渲染。
|
|
246
217
|
|
|
247
|
-
###
|
|
218
|
+
### Session 同步策略
|
|
248
219
|
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
pnpm build # Production build
|
|
253
|
-
pnpm test # Run tests
|
|
254
|
-
pnpm test:watch # Test watch mode
|
|
255
|
-
pnpm typecheck # TypeScript type check
|
|
256
|
-
pnpm lint # Oxlint linting
|
|
257
|
-
pnpm format # Oxfmt formatting
|
|
258
|
-
pnpm check # lint + format check
|
|
259
|
-
```
|
|
220
|
+
- Agent 与子 Agent 的实时状态、2D 办公室小人走动和会议区移动效果，默认由 WebSocket `agent` 事件直接驱动
|
|
221
|
+
- `sessions.list` 不再用于高频实时驱动，而是作为连接建立后的立即同步和 **60 秒一次** 的低频 reconciliation，用于修复漏事件、断线恢复后的 session 漂移，并复用同一响应构建 token 统计
|
|
222
|
+
- 该策略用于降低 Gateway CPU 压力，避免高频全量扫描影响其他 RPC probe
|
|
260
223
|
|
|
261
|
-
|
|
224
|
+
---
|
|
262
225
|
|
|
263
|
-
|
|
226
|
+
## 微信交流群
|
|
264
227
|
|
|
265
|
-
|
|
266
|
-
OpenClaw Gateway ──WebSocket──> ws-client.ts ──> event-parser.ts ──> Zustand Store ──> React Components
|
|
267
|
-
│ │
|
|
268
|
-
└── RPC (agents.list, chat.send, ...) ──> rpc-client.ts ──────────────>─┘
|
|
269
|
-
```
|
|
228
|
+
**微信养虾技术交流群**：欢迎扫码加群，与大家一起交流养虾实践、技术心得与实际真实的业务应用等。
|
|
270
229
|
|
|
271
|
-
|
|
230
|
+
<img src="./assets/weixin.png" alt="微信养虾技术交流群二维码" width="300" />
|
|
272
231
|
|
|
273
232
|
---
|
|
274
233
|
|
|
275
|
-
##
|
|
234
|
+
## 贡献
|
|
276
235
|
|
|
277
|
-
|
|
236
|
+
欢迎任何贡献！无论是新的可视化效果、控制台功能还是性能优化。
|
|
278
237
|
|
|
279
|
-
1. Fork
|
|
280
|
-
2.
|
|
281
|
-
3.
|
|
282
|
-
4.
|
|
238
|
+
1. Fork 本仓库
|
|
239
|
+
2. 创建特性分支 (`git checkout -b feature/cool-effect`)
|
|
240
|
+
3. 提交更改（使用 [Conventional Commits](https://www.conventionalcommits.org/) 格式）
|
|
241
|
+
4. 开启 Pull Request
|
|
283
242
|
|
|
284
243
|
---
|
|
285
244
|
|
|
286
|
-
##
|
|
245
|
+
## 许可证
|
|
287
246
|
|
|
288
247
|
[MIT](./LICENSE)
|