简而言之：Star-Office-UI 就是给 OpenClaw（龙虾）配的一间"像素办公室"。

平时我们看 Agent 在干嘛，多半只能盯着日志滚动；而它把这些"看不见的状态"，变成了办公室里角色的位置、动作和气泡提示。打开网页就能一眼看到：谁在忙、谁在待命、昨天大概做了什么。

---

适用场景

• 你想把 Agent 的运行状态从"黑盒日志"变成一个直观的可视化看板
• 你有多个 Agent，需要一个能"展示协作状态"的窗口（录屏、演示、直播都很友好）
• 你希望手机上也能随手看一眼当前状态
• 你偶尔需要把一个可访问链接发给别人体验（可选开公网）

---

核心功能

功能	说明
状态可视化	Agent 状态变化会驱动角色移动到办公室不同区域，并用气泡显示当前在做什么
多 Agent 加入	支持访客列表和 join key 机制，让多个 Agent 同时出现在同一间办公室里
昨日小记	可以把最近可用的工作记录展示出来（可做基础脱敏），方便快速回顾
移动端适配	手机浏览体验也不错，适合当"常驻看板"
公网访问（可选）	需要分享时可以用 Cloudflare Tunnel 临时开个外网地址
资产与布局自定义（进阶）	可以替换美术资产、调整布局，让办公室更像你自己的
生图装修（可选）	接入 Gemini API 后可以玩"装修房间"等能力（基础看板不依赖 API）

---

效果预览

更推荐先本地跑通，再考虑对外分享

---

运行环境

项目	配置
系统	Windows
Python	Python 3
环境管理	venv
运行方式	本地运行（暂不计划公网访问）

---

安装与运行

整体就两条路：

• 手动部署：你在本机照着命令一步步跑起来
• 让龙虾自动部署（OpenClaw Skill）：你只发一句话，剩下的让龙虾自己搞定

方式一：手动部署（自行安装）

1. 下载代码

若网络环境有问题可通过网盘下载：

git clone https://github.com/ringhyacinth/Star-Office-UI.git
cd Star-Office-UI

2. 安装依赖

python3 -m pip install -r backend/requirements.txt

3. 初始化状态文件（首次运行必做）

cp state.sample.json state.json

4. 启动后端

cd backend
python3 app.py

5. 打开页面

访问：http://127.0.0.1:19000

6. 快速验证

手动切换几次状态感受一下，在项目根目录执行：

python3 set_state.py writing "正在整理文档"
python3 set_state.py syncing "同步进度中"
python3 set_state.py error "发现问题，排查中"
python3 set_state.py idle "待命中"

7. 公网访问（可选）

如果你需要给别人体验，跑一个临时外网地址就行：

cloudflared tunnel --url http://127.0.0.1:19000

拿到 https://xxx.trycloudflare.com 后即可分享。

8. 安全配置（建议）

1. 侧边栏默认验证码为 1234

2. 如果要公网或长期使用，建议改成强密码：

   export ASSET_DRAWER_PASS="your-strong-pass"
   

3. 若长期运行（systemd / pm2 / 容器），把环境变量写进服务配置里

9. 验证安装（可选）

python3 scripts/smoke_test.py --base-url http://127.0.0.1:19000

所有检查显示 OK 就说明跑通了。

---

方式二：让龙虾安装（更推荐给 OpenClaw 用户）

如果你已经在用 OpenClaw，这个方式最省事：你只要发一句话，clone、装依赖、启动、状态同步等都由龙虾自动完成。

把下面这句话发给你的龙虾：

请按照这个 SKILL.md 帮我完成 Star Office UI 的部署：
https://github.com/ringhyacinth/Star-Office-UI/blob/master/SKILL.md

然后等龙虾回传访问地址：

• 通常是本机地址：http://127.0.0.1:19000
• 如果龙虾顺带配了对外访问，也可能会给你一个公网链接

验收建议：

• 让龙虾切换几次状态，确认角色会移动并显示气泡
• 任务结束后切回 idle，看板会一直很清爽

---

OpenClaw 深度集成：状态自动同步规则

如果你希望"龙虾做事时自动切状态"，可以在 SOUL.md（或 Agent 规则文件）里加一段约定，让 Agent 自己维护状态：

## Star Office 状态同步规则
- 接到任务时：先执行 `python3 set_state.py <状态> "<描述>"` 再开始工作
- 完成任务后：执行 `python3 set_state.py idle "待命中"` 再回复

状态与区域映射（常用）

状态	区域	说明
idle	休息区	待命 / 完成任务
writing	工作区	写代码 / 写文档
researching	工作区	搜索 / 调研
executing	工作区	执行命令 / 跑任务
syncing	工作区	同步 / 推送
error	Bug 区	报错 / 排查

---

邀请其他 Agent 加入办公室（可选）

1. Join Key

服务会根据 join-keys.sample.json 生成运行时 join-keys.json（若不存在）。

每个 key 默认支持最多 3 人同时在线，可自行调整。

2. 访客运行推送脚本

访客下载 office-agent-push.py，配置并运行：

JOIN_KEY = "ocj_starteam02"
AGENT_NAME = "访客龙虾"
OFFICE_URL = "https://office.hyacinth.im"

然后执行：

python3 office-agent-push.py

---

资源获取地址

资源	链接
项目地址（GitHub）	https://github.com/ringhyacinth/Star-Office-UI
源码网盘（夸克）	https://pan.quark.cn/s/638192798d99

---

附录：OpenClaw 部署教程（网盘资源）

• 教程资源（夸克）：https://pan.quark.cn/s/27bc36f9c4a8

这份教程更像一条"从建立认知到跑通闭环"的入门路线：先帮你读懂 OpenClaw 的文档体系和模块边界，再带你按主线把本地运行跑通，最后补齐生产里最常用的配置（模型、消息平台、技能、记忆等）。如果后续想往多 Agent 协作、Docker 部署和安全配置走，也有对应内容和常见问题排查。