環境変数

Clowld Space はプロセス起動時に環境変数を読み込みます。変更後は、該当する API・Web・デーモンのプロセスを再起動してください。Docker Compose の docker compose restart は .env を再読み込みしません。up -d でコンテナを再作成して初めて反映されます。

このページにはデプロイ運用者向けの設定のみを載せています。テスト用変数や内部実行用の変数は扱いません。グループ別のリファレンスとして使い、完全なデプロイ手順はセルフホストクイックスタートを参照してください。

プロダクションの最小構成

DATABASE_URL=postgres://user:password@postgres:5432/clowld?sslmode=require
JWT_SECRET=<long-random-secret>
APP_ENV=production
FRONTEND_ORIGIN=https://clowld.example.com
CLOWLD_APP_URL=https://clowld.example.com
CLOWLD_PUBLIC_URL=https://api.clowld.example.com

さらにメールサービスを 1 つ選ぶ必要があります。選ばない場合、認証コードと招待はサーバーログに書き込まれるだけです。

API とデータベース

Kubernetes で shutdown hold を設定する場合、terminationGracePeriodSeconds は hold と実際のシャットダウンにかかる時間の合計より大きくしてください。

primary とレプリカの接続上限は独立しています。全 API プロセスの合計が PostgreSQL クラスターの接続上限に収まるように設定してください。レプリカ接続はデフォルトで 5 分後に再作成され、昇格後に読み取り専用状態を再検証します。接続失敗時はインフラストラクチャが透過的に primary へフォールバックし、短時間のパッシブサーキットを開きます。バックグラウンドのデータベースプローブは追加されません。アプリケーションはレプリカデータの最大経過時間を保証しないため、データベース層でレプリケーション遅延を監視し、整合性が必要な読み取りは primary に残してください。

公開アドレスとブラウザアクセス

フロントエンドと API が異なる host を使い、ブラウザが API ドメインへ直接アクセスする構成では、COOKIE_DOMAIN の設定が必須です。設定しないとブラウザが CSRF cookie を読めず、すべての書き込みリクエストが 403 CSRF validation failed を返す一方、読み取りは正常に動きます。値には、両方の host を同時にカバーできる最も狭い親ドメインを使ってください（.example.com より .agent.example.com）。この設定はログインセッション cookie をそのドメイン配下のすべての host に広げるため、それらの host がすべて同一の信頼できる運用主体のものである場合にのみ使えます。変更後は両方の host で古い cookie を削除し、再ログインしてください。セルフホストクイックスタートの同一オリジン構成（ブラウザは app ドメインのみアクセス）に従う場合は、空のままで構いません。IP アドレスは指定しないでください。ブラウザは Domain が IP の cookie を無視します。

メールとログイン

Resend

SMTP

SMTP_HOST が空でない限り、SMTP が Resend より優先されます。

Google OAuth

サインアップ範囲

allowlist の正確な判定順序はログインとサインアップを参照してください。

添付ファイルストレージ

S3_BUCKET が未設定の場合、Clowld Space はローカルディスクを使います。

S3 または互換ストレージ

内部ネットワークの MinIO など、ブラウザから endpoint に直接到達できない場合は ATTACHMENT_DOWNLOAD_MODE=proxy を使ってください。

ローカルディスク

CloudFront

Redis とレート制限

リバースプロキシ配下のデプロイでは、実際のプロキシのネットワーク範囲を設定してください。すべての送信元を無条件に信頼してはいけません。クライアントが転送元 IP を偽装できてしまいます。

認証レート制限には REDIS_URL が必要です。未設定の場合、起動ログに認証レート制限が無効であることが表示されます。招待制限は Redis なしでもプロセス内メモリで動作し、Redis を設定すると複数レプリカで割り当てを共有します。設定済みの Redis が一時的に利用できない場合、認証レート制限はフェイルオープンしますが、招待作成は保護なしでメールを送らず、再試行可能な 503 を返します。

外部連携

GITHUB_APP_ID と秘密鍵を設定しなくても、PR の関連付け・ミラー・マージ時のステータス変更は通常どおり動きますが、カードに CI とマージ可否のステータスが表示されず、「GitHub から選択」のリポジトリ入口も無効になります。

設定手順は GitHub 連携、Lark Bot、Slack Bot、Telegram Botを参照してください。

サーバーサイド LLM

このグループは、会話タイトルなどサーバー側の補助生成機能の設定です。エージェントの実行時に使う AI コーディングツールの資格情報ではありません。

CLOWLD_LLM_MAX_RETRIES はリトライポリシーの唯一の設定元です。未設定ならデフォルトの 2 回、0 なら 1 回の呼び出しにつきリクエストは 1 回だけ、1〜5 ならリトライは最大その回数までになります。これは割り当てではなく上限です。消費するのはリトライ対象の失敗だけで、成功や呼び出し側自身のデッドラインによって早く終わることもあります。それ以外の値（負数、非数値、5 超過）は静かに補正されるのではなく起動に失敗します。上限はレイテンシ予算です。バックオフは 0.5 秒から始まり 8 秒を上限に倍増するため、これより大きい予算は呼び出し側自身のタイムアウトを超え、リトライ可能な失敗をタイムアウトに変えてしまいます。リトライの対象は接続失敗と HTTP 408、409、429、5xx で、それ以外の 4xx はそのまま返されます。サーバーは起動時に有効なポリシーを llm retry policy として記録しますが、その行に資格情報は含まれません。

CLOWLD_LLM_DISABLE_THINKING は、モデルの推論（thinking）パスが長く、アシスト呼び出しのレイテンシ予算を圧迫する gateway 向けの設定です。true（または 1）にすると、サーバーはすべてのリクエストボディに chat_template_kwargs: {"enable_thinking": false} を付加します。このフィールドを転送する gateway（vLLM/sglang 系のデプロイや、GLM/Qwen 系の一部 LiteLLM ルート）は thinking パスを省略します。標準の OpenAI endpoint は未知のボディフィールドを拒否するため、上流が受け付ける場合のみ有効にしてください。GPT-5.6 系モデルはフォローアップ質問のリクエストではサーバーが既に reasoning_effort: none を付けます。チャットの自動タイトル生成は推論フィールドを送信しません。本設定がそれに影響するのは、構成された上流が chat_template_kwargs を受け付ける場合だけです。指定できる値は true/false と 1/0（大文字小文字を区別しない）で、それ以外は起動に失敗します。起動ログにはリトライポリシーと併せて有効な状態が記録されます。

このレイヤーを使う機能は 2 つで、どちらも設定した endpoint にチャット内容を送信します。

• 会話タイトルの自動生成 — 新しいチャットセッションでユーザーが最初に送ったメッセージを、そのまま送信します。添付ファイルは含まれません。
• フォローアップ質問（エージェントの返信の下に表示されるボタン） — 会話の末尾を送信します。最大 6 メッセージで、対象の返信は 3000 文字、それより古いメッセージは各 800 文字が上限です。

API key と base URL の両方が空の場合、このレイヤーは無効で、上流へのリクエストは一切送信しません。上記 2 機能も内容を送信しません。会話は最初のメッセージからクライアントが生成したタイトルを使い、フォローアップ質問ボタンは表示されません。その他の機能には影響しません。

デーモン設定

以下の変数は、エージェントを実行するコンピューター上で読み込まれます。API コンテナ内ではありません。

デーモンがエージェントの実行に注入する内部コンテキストについては、作業ランタイム環境を参照してください。

@/home/clowld/clowld_workspaces/clowld-spac-8e9e35d1c531/cs-534-ff75298c9d0f/workdir/combined_env_ja.txt

CLOWLD_CLAUDE_PATH=/opt/bin/claude
CLOWLD_CLAUDE_ARGS=--max-turns 40

Cursor の検証済みバックグラウンドクリーンアップには、Linux 6.9 以降（プロセスグループ pidfd）、macOS カーネルによるプロセス識別子の照会と audit token を用いたシグナル送信のサポート、または Windows で正常に割り当てられた入れ子の Job Object が必要です。macOS では各プロセスへのシグナル送信にカーネルが検証する PID version を用いるため、同一セッションのグループに参加する必要はありません。これらの macOS API は非公開であり、プロセス捕捉時に確認されます。所有権を確保できなかったバックグラウンドプロセスは元のツール結果を返し、ツール watchdog が 0 の場合も含めて通常の idle watchdog に従います。すでに所有している作業は、クリーンアップを確認できない場合も実行中のままです。ツール watchdog を 0 にした場合はこの境界自体が存在せず、所有済みのバックグラウンド作業が生きている限り実行は継続します。その場合の実行は CLOWLD_AGENT_TIMEOUT だけに制限され、これも既定値は 0 です。

所有している Cursor のバックグラウンドプロセスは、実行が正常に完了したときにも停止されます。したがって、その実行が起動したバックグラウンドサーバーが意図的に終了処理後まで生き残ることはありません。macOS は保持された元の親プロセスの識別子によって後から生まれた子プロセスを認識できますが、観測前に中間プロセスが消えた連鎖は証明できません。そのようなプロセス、追跡対象のグループから外れた作業、および継続的な所有権や送信のエラーは、バックグラウンド作業を残す可能性があります。確認できなかったクリーンアップはログに記録され、「クリーンアップ成功」による回復ウィンドウを与えることはありません。数値の PID やプロセスグループだけを根拠に未知のプロセスを終了させることはありません。

優先順位はコマンドラインフラグ → 環境変数 → ~/.clowld-space/cli/config.json → 組み込みデフォルトです。watchdog の動作はデーモンとランタイムを参照してください。

デーモン設定の永続化

デーモン側のよく使う設定は、シェルの環境変数に頼らず ~/.clowld-space/cli/config.json に書き込むこともできます。名前付きプロファイルの設定ファイルは ~/.clowld-space/cli/profiles/<name>/config.json にあります:

clowld config set poll_interval 10s
clowld config show

サポートされるキー:

値のルール:

• duration 系のキーは正の Go duration（10s、2h など）を受け付け、0s と負の値は拒否されます。唯一の例外は agent_timeout で、0s は有効な値として実行時間上限を明示的に無効化します。
• 空文字列を渡すと永続化された値がクリアされ、環境変数または組み込みデフォルトに戻ります。例: clowld config set poll_interval ""。
• max_concurrent_tasks には非負の整数が必要です。
• 相対パスの workspaces_root は保存時に絶対パスへ変換されます。

可観測性と分析

次のステップ

• ログインとサインアップ — ログイン方式とサインアップ制限。
• トラブルシューティング — デプロイ問題の症状別診断。
• デーモンとランタイム — デーモン側の対応する設定。

Clowld Space

• 会社管理と参加申請: CLOWLD_COMPANY_GOVERNANCE_ENABLED, CLOWLD_COMPANY_NAME, CLOWLD_COMPANY_EMAIL_DOMAINS, CLOWLD_COMPANY_CEO_EMAIL.
• モデル価格: MODEL_PRICING_TIMEZONE, MODEL_PRICING_LITELLM_URL, MODEL_PRICING_MODELS_URL.