Reference

リファレンス

環境変数、ガイドの擬似コードと実 SDK の差分、主要なエラーと対処、リポジトリ構成をまとめています。 はじめての場合は先に 概要 を読んでください。

環境変数

すべて OSUI_ 接頭辞で、.env からも読み込めます。認証に関わる項目の背景は セキュリティ を参照してください。

変数既定値説明
OSUI_AUTH_TOKEN(任意)設定すると全 API およびコンソールが保護されます。公開 bind 時は必須。
OSUI_HOST / OSUI_PORT127.0.0.1 / 8080バインド先。loopback 以外は token が必須。
OSUI_GATEWAY_ENDPOINT(SDK 自動検出)明示的に gateway を指定する場合に使用。空なら active cluster を読みます。
OSUI_WORKSPACEdefault操作対象ワークスペース。
OSUI_DEMOfalsetrue で demo backend を強制。Vercel / Colab 向け。
OSUI_ALLOW_QUERY_TOKENfalse?token= での認証を許可するか。URL はログ・履歴・Referer に残るため既定で無効。
OSUI_REQUIRE_GATEWAYfalsetrue で demo フォールバックを禁止し、接続できなければ起動を失敗させます。
OSUI_SSE_ENABLEDtrueSSE エンドポイントを公開するか。Cloudflare Quick Tunnel では false を推奨。
OSUI_GATEWAY_CA_CERT / OSUI_GATEWAY_CERT / OSUI_GATEWAY_KEY(任意)CA 検証と mTLS クライアント証明書。CERT と KEY は同時指定が必須。
OSUI_OIDC_ISSUER / OSUI_OIDC_CLIENT_ID / OSUI_OIDC_CLIENT_SECRET / OSUI_OIDC_AUDIENCE(任意)OIDC クライアント認証。リモート gateway へ接続する際に使用します。
OSUI_EXEC_DEFAULT_TIMEOUT / OSUI_EXEC_MAX_TIMEOUT60 / 1800コマンド実行の既定/上限タイムアウト(秒)。
OSUI_PAGE_SIZE100一覧取得時のページサイズ。
OSUI_CORS_ORIGINS[]CORS 許可オリジンの JSON 配列。
OSUI_GATEWAY_CLUSTER(任意)接続先 cluster 名。SDK 側の上書き。

ガイドの訂正点(実 API との差分)

ガイドの擬似コードがそのまま実装できなかった箇所を、実 SDK の仕様に合わせて整理しました。コードを書くときの注意点は以下です。

エラーと対処

主要なエラーが返る状況と、UI 上での挙動・対処法です。トースト通知など UI 上のメッセージはコンソールにも出力されます。

状態発生する場面UI 上の挙動対処
401トークン未設定・不一致(Authorization / Sec-WebSocket-Protocol / ?token=)アクセストークン入力パネルを表示OSUI_AUTH_TOKEN と同じ値を入力
404存在しないサンドボックス、または SSE 無効化時の /exec/streamコンソールに [error] not found を出力一覧から正しい名前を選択
422未実装フィールド(env 等)や不正なペイロード422 の詳細をコンソールに出力サポート対象のフィールドのみ送信
503OSUI_REQUIRE_GATEWAY=true で gateway に到達できない起動に失敗(fail-fast)gateway の起動・endpoint を確認
4401(WS)WebSocket ハンドシェイク時の token 失敗接続切断・再実行可能トークンを確認して再接続

起動経路の失敗(README / LP の手順どおりでない条件)の詳細は USAGE.md のトラブルシューティングも参照してください。

リポジトリ構成

パス内容
src/openshell_ui/core/設定、モード判定、backend factory、OpenShell / demo adapter
src/openshell_ui/api/auth、health/config、CRUD、exec(REST / WebSocket / SSE)
src/openshell_ui/ui/同梱のダッシュボード(HTML / CSS / JS)
deploy/Cloudflare config、Dockerfile、Colab notebook
policy/OpenShell policy(version 1)
site/この LP(GitHub Pages)
.github/CI / Pages ワークフロー、Issue・PR テンプレート
CONTRIBUTING.md / CHANGELOG.md開発参加ガイド / 変更履歴