从/health到/agent-pushStar-Office-UI的10个核心API接口完整参考【免费下载链接】Star-Office-UIA pixel office for your OpenClaw: turn invisible work states into a cozy little space with characters, daily notes, and guest agents. Code under MIT; art assets for non-commercial learning only.项目地址: https://gitcode.com/gh_mirrors/st/Star-Office-UIStar-Office-UI 是一个像素风格的 AI 办公室状态看板把 AI 助手看不见的工作状态变成一间可爱的像素办公室角色会随状态走动、气泡会实时播报、还有昨日小记和访客 Agent。这一切的神经系统全部靠后端 Flask 服务的一组 HTTP 接口驱动。本文用一张清单讲透 10 个核心 API 接口从最简单的/health健康检查到访客状态推送的/agent-push新手照着就能把自己的 Agent 接进办公室。一、先认识办公室接口背后的画面在写请求之前先花 10 秒理解画面逻辑。Star 是办公室的主人角色状态idle/writing/error等会自动映射到不同区域状态所在区域说明idle休息区 breakroom待命、自动回归writing/researching/executing/syncing工作区 writing正在干活error故障区 error出问题了所有接口都由 backend/app.py 中的 Flask 应用统一提供默认监听http://127.0.0.1:19000可通过环境变量STAR_BACKEND_PORT改端口。二、10个核心API接口逐个拆解1. GET /health —— 30秒上手的健康检查最简单的第一个接口用来确认后端还活着GET /health返回内容很简单status: ok、服务名和时间戳。官方自带的 healthcheck.sh 就是靠curl http://127.0.0.1:19000/health判断服务健康挂了自动重启。你可以把它写进自己的定时任务当办公室门禁灯用。2. GET /status —— 读取主人 Star 的当前状态GET /status返回state.json里的状态state、detail、progress、updated_at如果检测到 OpenClaw 工作区的IDENTITY.md还会附带officeName字段。前端正是靠轮询它来驱动主角动作。这里有两个新手友好的防卡死机制自动待命工作态writing 等超过ttl_seconds默认 300 秒没更新自动回落到idle避免角色永远趴在工位上兼容旧版这是单 Agent 时代保留下来的经典接口任何老脚本都还能用。3. POST /set_state —— 手动切状态的控制面板接口POST /set_state接收state和detail两个字段写回state.json。它主要给前端控制面板用日常测试更推荐直接用仓库自带的命令行脚本一行命令就能切状态python3 set_state.py writing 正在整理文档 python3 set_state.py error 发现问题排查中脚本实现在 set_state.py原理就是直接改状态文件state.sample.json 里有一份初始模板首次启动会自动生成state.json。4. GET /agents —— 多 Agent 列表访客渲染的数据源GET /agents返回整个办公室的 Agent 列表含主人和所有访客前端靠它创建、更新、移除屏幕上的每个角色。响应字段包括agentId、name、state、authStatus、lastPushAt等。这个接口访问时还会顺手做两件事在 backend/app.py 中实现超时未批准的访客自动清退并释放其接入密钥5 分钟没推送的在线访客自动标记为 offline画面上的角色会下工。5. POST /join-agent —— 用接入密钥加入办公室访客 Agent 的进门接口POST /join-agent请求体name必填、joinKey必填、state、detail。后端会校验密钥有效性、是否过期、同一密钥的并发上限默认 3 个在线通过后直接自动批准授权 24 小时并返回你的agentId。密钥从哪来管理员在 join-keys.sample.json 的格式下配置密钥可复用、可设过期时间和并发上限。拿到密钥后仓库自带脚本 office-agent-push.py 会自动完成 join 和后续推送你只需填JOIN_KEY和AGENT_NAME两个变量。6. POST /agent-push —— 访客状态推送整篇文章的核心POST /agent-push必填字段agentId、joinKey、state可选detail、name。这是访客保持在线的唯一通道典型用法是每 15~30 秒推送一次状态词会自动归一化working/busy→writingrun/exec→executing未知值一律回idle容错性很好offline状态的访客再次推送时自动复活回approved离线只是人没来不是被开除每次推送都会刷新lastPushAt超过 5 分钟没动静才会被判离线返回体里的area字段告诉你角色当前站在哪个区域。office-agent-push.py 里还藏着一个贴心设计本地状态文件太久没更新默认 600 秒会自动回idle避免假工作中骗过看办公室的人。7. POST /leave-agent —— 访客主动离开POST /leave-agent传agentId推荐或name把访客移出办公室同时释放其接入密钥供别人复用。配合/join-agent的 403/404 响应构成完整的进出闭环被拒绝、被移除后推送脚本会停止工作并清理本地缓存。8. GET /yesterday-memo —— 昨日小记GET /yesterday-memo办公室墙上贴着一张昨日小记卡片数据就来自这个接口。它会读取项目上级目录memory/下的日期日志2026-03-05.md这种格式优先取昨天的没有则回落到最近的一天。解析逻辑在 backend/memo_utils.py 中会做内容清洗脱敏后展示为卡片文案。9. POST /agent-approve —— 批准访客管理员POST /agent-approve传agentId把待批准访客设为approved默认授权 24 小时。虽然/join-agent目前对有效密钥是进门即批准但保留手动批准口意味着管理员随时可以收紧策略比如改回先申请、后审批的模式。10. POST /agent-reject —— 拒绝访客管理员POST /agent-reject传agentId访客被标记rejected、从列表移除并且其接入密钥被释放。这是管理员的请出办公室按钮——被拒绝后访客的/agent-push会收到 403推送脚本自动退出。三、把10个接口串成一条工作流整组接口其实只有 3 条主线记住就够用了自检线/health保活 /status读主人状态 /set_state切状态访客线/join-agent进门 →/agent-push持续上报 →/leave-agent离场管理线/agents看全场 /agent-approve//agent-reject管权限/yesterday-memo补上昨天干了啥。四、新手上手3步接入自己的Agent第 1 步确认服务健康。请求GET /health拿到ok再请求GET /status确认能读到状态。第 2 步拿接入密钥。让办公室管理员在join-keys.json里发你一个密钥格式见 join-keys.sample.json。第 3 步推送循环。最省事的方式是直接用仓库自带的 office-agent-push.py填入JOIN_KEY和AGENT_NAME运行后脚本自动先/join-agent拿到agentId然后每 15 秒/agent-push一次。它还会自动从本地state.json或/status读取你机器上的真实状态完全不用手写请求。如果更习惯手动调接口记住调用顺序即可先 join 拿agentId再 push最后 leave 清理。完整流程文档可参考 docs/STAR_OFFICE_UI_OVERVIEW.md部署自动化流程见 SKILL.md。五、安全与实用小贴士别把隐私写进detail它会被渲染在气泡里、可被任何人拉取只写在做什么别写在哪做的。生产环境会自动安全加固backend/security_utils.py 会在生产模式下检查FLASK_SECRET_KEY和侧边栏密码强度弱密码直接拒绝启动。资产相关接口有密码保护生图换背景、替换素材等/assets/*接口需要侧边栏验证码默认密码1234生产环境会直接报错记得改。缓存策略已内置API 和 HTML 全部no-cache静态资源长缓存你轮询拿到的永远是最新状态不用操心 CDN 缓存。持久化靠文件状态、访客列表、密钥分别存在state.json、agents-state.json、join-keys.json读写逻辑在 backend/store_utils.py备份这几个文件就等于备份了整个办公室。总结Star-Office-UI 的 10 个核心 API 接口覆盖了健康检查、状态读写、多 Agent 进出场、权限管理和昨日小记五大场景。对新用户来说最常用的其实就是 4 个/health保活、/status看状态、/join-agent进门、/agent-push报到——把这四个跑通你的 AI 助手就正式入职这间像素办公室了。【免费下载链接】Star-Office-UIA pixel office for your OpenClaw: turn invisible work states into a cozy little space with characters, daily notes, and guest agents. Code under MIT; art assets for non-commercial learning only.项目地址: https://gitcode.com/gh_mirrors/st/Star-Office-UI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考