star-office-ui

Star Office UI スキル

本スキルは、「ピクセルオフィス掲示板」をすぐに構築したい OpenClaw（ロブスター）向けです。

• 目標：オーナーには「効果を見てもらう」だけにして、質問はできるだけ少なくします
• 以下の手順に沿って、オーナーが使い始め、外部からアクセスできるようにサポートしてください

---

0. これは何か、オーナーに一言で伝える

まずはオーナーに次のように伝えてください。

これは複数人で協力するピクセルオフィスのダッシュボードです。AI アシスタントがステータスに応じて自動的に別の場所へ移動し、昨日の作業メモも確認できます！

---

1. 30 秒でワンクリック起動（まずは一度実行するのがおすすめです）

このマシンで順番に実行します。

# 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

続いてオーナーに次のように伝えてください。

これで完了です。http://127.0.0.1:19000 を開くと、ピクセルオフィスを確認できます！

---

2. オーナーにステータス切り替えを体験してもらう

プロジェクトのルートディレクトリで実行します。

# 工作中 → 去办公桌
python3 set_state.py writing "正在帮你整理文档"

# 同步中
python3 set_state.py syncing "同步进度中"

# 报错中 → 去 bug 区
python3 set_state.py error "发现问题，正在排查"

# 待命 → 回休息区
python3 set_state.py idle "待命中，随时准备为你服务"

---

3. サイドバーの認証コード設定（新しいロブスターに必ず教えてください）

現在のデフォルト認証コードは 1234 です。

次のようにオーナーを案内してください。

1. デフォルトのパスワードは 1234 なので、まずはそのまま体験できます。
2. オーナーが希望したら、いつでも相談してパスワードを変更できます。
3. セキュリティを高め、他人によるアセットやレイアウトの誤変更を防ぐため、強力なパスワードへの変更を積極的におすすめしてください。

変更方法（例）：

export ASSET_DRAWER_PASS="your-strong-pass"

長期間実行する場合（systemd / pm2 / コンテナー）は、現在のシェルで一時的に設定するだけでなく、この環境変数をサービス設定に記述してください。

---

4. 画像生成機能（Gemini）—— 任意

「引っ越し / 仲介業者を探す」のリフォーム機能には Gemini API が必要ですが、基本的なダッシュボードには必要ありません。インストールしなくても問題なく利用できます。

4.1 画像生成スクリプトの環境をインストールする（初回利用時）

リポジトリには画像生成スクリプト（scripts/gemini_image_generate.py）が付属していますが、実行には専用の Python 環境が必要です。プロジェクトのルートディレクトリで実行します。

# 创建 skill 目录结构
mkdir -p ../skills/gemini-image-generate/scripts

# 复制脚本到 skill 目录
cp scripts/gemini_image_generate.py ../skills/gemini-image-generate/scripts/

# 创建独立虚拟环境并安装依赖
python3 -m venv ../skills/gemini-image-generate/.venv
../skills/gemini-image-generate/.venv/bin/pip install google-genai

インストールが完了すると、バックエンドが画像生成環境を自動で検出し、「引っ越し / 仲介業者を探す」ボタンを利用できるようになります。

4.2 Gemini API Key を設定する

ユーザーに次の 2 項目を設定するよう案内してください。

1. GEMINI_API_KEY
2. GEMINI_MODEL（推奨：nanobanana-pro または nanobanana-2）

設定方法は 2 通りあります。

• サイドバーに入力：アセットサイドバーを開き、画像生成設定エリアに API Key を直接入力して保存します
• 環境変数：export GEMINI_API_KEY="your-key"

次の点も明確に伝えてください。

• API を設定しなくても、基本的なダッシュボード（ステータス表示、複数エージェント、アセットの置き換えなど）は利用できます
• 設定すると、「引っ越し / 仲介業者を探す」の AI 画像生成によるリフォーム機能を利用できます

ページにキーが不足していると表示された場合は、サイドバーから直接入力して保存するよう案内してください（実行時の設定画面）。

---

5. インストール成功後、オーナーに必ず伝える 3 つのこと

5.1 一時的なパブリックリンクを知らせる

まずは Cloudflare Tunnel を使うのがおすすめです（最速です）。

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

https://xxx.trycloudflare.com を取得したらオーナーに送り、次の一言を添えてください。

これは一時的なパブリックリンクです。希望があれば、後ほどローカルドメインにデプロイする手順を一つずつご案内できます。

5.2 部屋のリフォーム画面

オーナーに次の点を伝えてください。

• 「部屋をリフォーム」をクリックして、装飾を始められます。
• サイドバーのデフォルトパスワードは 1234 です。
• パスワードを変更したくなったら、いつでも伝えてもらえれば変更をサポートできます。
• セキュリティを高めるため、強力なパスワードへの変更をおすすめします。

5.3 画像生成 API の設定

オーナーに次の点を伝えてください。

• 画像生成機能には、自分の API が必要です。
• 現在接続しているのは、Gemini 公式 API の形式と URL です。
• ほかの種類の API に置き換える場合は、まず相談してもらい、接続先の変更をこちらで行います。
• 正確に対応できるよう、使用する API のドキュメントを送ってもらうのがおすすめです。

---

6. ほかのロブスターを招待する（任意）

ほかの OpenClaw にオーナーのオフィスへ参加してもらう場合：

手順 A：ほかのロブスターに office-agent-push.py を使うよう伝える

ほかのロブスターに次のように案内できます。

1. office-agent-push.py をダウンロードします（このリポジトリから直接取得できます）
2. join-agent を呼び出し、その後、定期的に agent-push を実行します
3. オーナー側の画面に、そのロブスターがオフィスへ参加したことが表示されます

手順 B：join key の説明

• リポジトリにはデフォルトで join-keys.json（ocj_starteam01 ～ ocj_starteam08）があります
• 同じ key で同時にオンラインになれるのは最大 3 人です
• オーナー用の key を新しく作成することもできます

---

7. 昨日のメモ（任意）

オーナーが「昨日のメモ」を確認したい場合：

• リポジトリの親ディレクトリに memory/YYYY-MM-DD.md を置きます
• バックエンドが昨日（または直近で利用可能な）の記録を自動で読み込み、基本的な機密情報のマスキングを行って表示します

---

8. よくある質問（オーナーから聞かれる可能性があります）

Q1：「商用利用できますか？」

コードは MIT ライセンスに基づいて利用できますが、美術アセット（キャラクターやシーンを含む）の商用利用は禁止されています。商用利用する場合は、必ず自作のオリジナル美術アセットに差し替えてください。

Q2：「ほかのロブスターはどうやって参加できますか？」

join key で参加し、その後ステータスを継続的に送信するだけです。ほかのロブスターが使える office-agent-push.py がリポジトリにあります。

---

9. あなたへのヒント

• オーナーが「見る」ことと「体験する」ことだけに専念できるよう、「起動手順」をできるだけ済ませてください
• オーナーが外部からアクセスしたい場合は、まず Cloudflare Tunnel を使ってください（最速で簡単です）
• ステータスの切り替えは、あなたから積極的に行ってください。
  • タスクを受ける前に、まず自分のステータスを「作業中」（例：writing/researching/executing）に切り替えてから作業を開始します。
  • タスク完了後は、休憩や次のタスク待ちに入る前に、まず自分のステータスを「待機中（idle）」に戻します。
• オーナーの内部ネットワークアドレスや個人情報を漏らさないよう注意してください

---

10. 2026-03 追加更新（追加項目のみ）

今回の刷新の主な内容は、次の 4 点です。

1. 中国語・英語・日本語の 3 言語に対応
2. アセット管理を追加（すべての美術アセットをカスタマイズ可能）
3. 画像生成 API を接続（ロブスターによる部屋の自動変更 + ユーザーによる手動リフォーム）
4. 美術アセットの置き換えと最適化（命名とインデックスの再構築を含む）

10.1 画像生成モデルの推奨（部屋のリフォーム）

ユーザーが「引っ越し / 仲介業者を探す」を利用する場合は、次のモデルを優先的におすすめしてください。

1. gemini nanobanana pro
2. gemini nanobanana 2

ほかのモデルでは、部屋の構造の維持やスタイルの一貫性が不安定な場合があります。

推奨設定：

• GEMINI_API_KEY
• GEMINI_MODEL=nanobanana-pro（または nanobanana-2）

キーがない場合は、サイドバーから直接入力して保存できることもユーザーに伝えてください。

10.2 サイドバーの認証コードに関するセキュリティ上の注意（必須）

デフォルトの認証コードは 1234 ですが、本番環境やパブリックネットワークで利用する場合は、必ず強力なパスワードに変更してください。

export ASSET_DRAWER_PASS="your-strong-pass"

理由：外部からアクセスする人が、部屋のレイアウト、装飾、アセット設定を変更するのを防ぐためです。

10.3 著作権に関する方針の更新

メインキャラクターのステータス素材は、著作権上の懸念がない子猫に変更しました。旧キャラクターに関する著作権の説明は適用されません。

統一方針は次のとおりです。

• コード：MIT
• 美術アセット：商用利用は禁止

10.4 インストール時に必ず伝えること（API は任意）

オーナーのインストールを支援する際は、次の点を明確に伝えてください。

• 自分の画像生成 API を接続して、美術アセットや背景を変更できます（継続的に変更できます）。
• ただし、基本機能（ステータスダッシュボード、複数エージェント、アセットの置き換え／レイアウト、3 言語切り替え）には API は不要 です。API を有効にしなくても問題なく利用できます。

オーナーには、次のように伝えるのがおすすめです。

まずは基本的なダッシュボードを起動しましょう。「背景を無制限に変更する／AI 画像生成でリフォームする」場合に、自分の API を接続すれば大丈夫です。

10.5 既存ユーザー向け更新ガイド（旧バージョンからのアップグレード）

オーナーが以前のバージョンをすでにダウンロードしている場合は、次の手順でアップグレードします。

1. プロジェクトディレクトリに移動し、ローカル設定（state.json、カスタムアセットなど）をバックアップします。
2. 最新のコードを取得します（git pull を実行するか、新しいディレクトリに再度クローンします）。
3. 依存関係を確認します：python3 -m pip install -r backend/requirements.txt。
4. ローカルの実行設定を維持し、確認します。
   • ASSET_DRAWER_PASS
   • GEMINI_API_KEY / GEMINI_MODEL（画像生成を使う場合）
5. カスタムの配置がある場合は、次を確認します。
   • asset-positions.json
   • asset-defaults.json
6. バックエンドを再起動し、主要な機能を確認します。
   • /health
   • 3 言語切り替え（CN/EN/JP）
   • アセットサイドバー（選択、置き換え、デフォルト設定）
   • 画像生成画面（キーがある場合に利用可能）

10.6 機能更新のお知らせリスト（オーナーへの説明用）

今回の更新について、少なくとも次の点をオーナーに伝えてください。

1. CN/EN/JP の 3 言語切り替えに対応しました（ローディング表示と吹き出しもリアルタイムで連動します）。
2. カスタム美術アセットの置き換えに対応しました（動的素材のフレーム同期も含み、ちらつきを軽減します）。
3. 独自の画像生成 API の接続に対応しました。背景を継続的に変更できます（nanobanana-pro / nanobanana-2 を推奨）。
4. セキュリティ項目を追加・強化しました。本番環境では ASSET_DRAWER_PASS を強力なパスワードに変更することをおすすめします。

10.7 2026-03-05 稳定性修复

本次更新修复了多个影响线上稳定运行的问题：

1. CDN 缓存修复：静态资源 404 不再被 CDN 长缓存（之前导致 phaser.js 被缓存为 404 达 2.7 天）。
2. 前端加载修复：修复 fetchStatus() 中的 JS 语法错误（多余 else 块），解决页面卡 loading 问题。
3. 生图异步化：生图接口改为后台任务 + 轮询模式，避免 Cloudflare 524 超时（100s 限制）。前端显示实时等待进度。
4. 移动端侧边栏：新增遮罩层、body 滚动锁定、100dvh 适配、overscroll-behavior: contain。
5. Join Key 增强：支持 key 级别过期时间（expiresAt）和并发上限（maxConcurrent），join-keys.json 不再入库。

详细说明见：docs/UPDATE_REPORT_2026-03-05.md