エンジン設定 (Engine Configuration)

自身のマシン上で Griptape Nodes エンジンを実行する際、各種設定を管理するためのユーティリティが用意されています。より高度なプロジェクトを構築・管理したり、チームメンバーとプロジェクトを共有したりする上で、設定がどのように読み込まれるかを理解することは非常に重要です。

インストール時に、gtn init が自動的に実行されています。

特定の設定項目をお探しの場合は、カテゴリ別に型、デフォルト値、環境変数、および説明を一覧化した設定リファレンスを参照してください。

エディタ内での設定編集

設定を変更する最も推奨される方法は、エディタに内蔵されている Configuration Editor（設定エディタ）を使用することです：

エディタのヘッダーにある Settings メニューを開き、All Settings を選択します。このサブメニューには、特定のカテゴリの設定エディタを直接開く項目（Engine Settings や Library Settings など）も用意されています。
左サイドバーからカテゴリを選択します（Editor Settings、Engine Settings、File System、Libraries、Library Settings、MCP Servers、API Keys & Secrets）。上部の検索ボックスを使用して設定名で絞り込むこともできます。
値を変更します。設定エディタが自動的に設定ファイルへ書き込みを行います。

一部の設定はエンジンの再起動後にのみ有効になります（static_server_base_url がその一例です。静的ファイルサーバーの設定を参照）。

このページの以降のセクションでは、設定エディタが裏側で書き込んでいるファイル、環境変数、およびそれらのマージ優先順位について詳しく解説します。セットアップを自動化する場合、ヘッドレスで実行する場合、またはチームで設定を共有する場合にのみ、これらを直接編集してください。

設定の読み込み順序 (Configuration Loading)

Griptape Nodes は、環境変数および設定ファイルから設定を読み込む際に特定の検索順序を採用しています。この仕組みを理解することが、環境を適切に管理するための鍵となります。

環境変数 (.env) 環境変数は、API キーなどの機密性の高いシークレットを安全に保管するために使用されます。Griptape Nodes は自動的に env ファイルを読み込み、これらのシークレットをアプリケーションで利用できるようにします。
- メインの .env ファイルは、システム全体のユーザー設定ディレクトリから読み込まれます: xdg_config_home() / "griptape_nodes" / ".env"（通常は ~/.config/griptape_nodes/.env）。
- このファイルは GT_CLOUD_API_KEY、OPENAI_API_KEY などのシークレット用です。
  
  通常、これらのファイルを直接編集する必要はありません。Griptape Nodes は Settings ダイアログを通じて環境変数を自動管理します。
設定ファイル (griptape_nodes_config.json) 設定ファイルには、ノードライブラリの配置場所など、Griptape Nodes の動作に不可欠な情報や、使い勝手をカスタマイズするためのユーザー環境設定が保持されます。
- 設定ファイルが見つからない場合、Griptape Nodes は組み込みのデフォルト値を使用して動作します。
- 設定ファイルは常に JSON 形式（griptape_nodes_config.json）です。最大 3 つの設定ファイル、ランタイムオーバーライド、および環境変数から読み込まれ、優先順位に従ってマージされます：
- 読み込み順序（数値が小さいものが先に読み込まれ、数値が大きいものが上書きします）：
  1. 組み込みデフォルト (Built-in defaults) — アプリケーションに標準で組み込まれている初期値。
  2. ユーザー設定 (User config) — ~/.config/griptape_nodes/griptape_nodes_config.json。このマシン全体に適用されるグローバル設定。
  3. プロジェクト隣接設定 (Project-adjacent config) — <project_dir>/griptape_nodes_config.json。プロジェクトがアクティブになった際に読み込まれます。プロジェクトファイルと一緒に共通のデフォルト設定を配布する場合に使用します。
  4. ワークスペース設定 (Workspace config) — <workspace_dir>/griptape_nodes_config.json。ワークスペースが解決された後に読み込まれます。共有プロジェクト設定よりも優先される、ユーザーごとの個別オーバーライドに使用します。ワークスペースディレクトリがプロジェクトディレクトリと同一である場合、このファイルはプロジェクト隣接設定と同一であるとみなされ、二重に読み込まれることはありません。
  5. プロジェクトごとのワークスペースオーバーライド (Per-project workspace override) — アクティブなプロジェクトのパスが（ユーザー設定内の）project_workspaces マッピングのキーと一致する場合、そのワークスペースディレクトリが適用されます。これは workspace_directory のみを設定し、上記の設定ファイルのすべての値を上書きします。ファイルとして保持されるものではないため、gtn self info では runtime レイヤーとして表示され、アクティブな間は設定画面で workspace_directory を編集しても変更できません。プロジェクトテンプレート独自の workspace_dir や、親プロジェクトから継承されたワークスペースも同様に適用されます。これらを宣言していないプロジェクトを開いた場合、ユーザー設定で指定済みの値に固定されます（ユーザー設定としてレポートされ、編集可能であり、次回プロジェクトを開いたときに有効になります）。詳細はワークスペースを参照してください。
  6. 環境変数 (Environment variables) — GTN_CONFIG_* プレフィックス（最優先）。詳細は後述します。
- オーバーライド優先順位: 後から読み込まれたファイルの設定が、先に読み込まれたファイルの設定を上書きします。
デフォルト値とマージの挙動 Griptape Nodes には、デフォルトのワークスペースディレクトリを含む様々なオプションの組み込みデフォルト値が用意されています。検出された設定ファイルから読み込まれた値によって上書きされない限り、これらのデフォルト値が使用されます。
- 最初に検出された設定ファイルから読み込まれた設定が、組み込みのデフォルト値を上書きします。
- いずれの検索パスにも設定ファイルが見つからない場合、アプリケーションは組み込みのデフォルト値のみを使用します。
- 重要なデフォルト値の 1 つが workspace_directory であり、読み込まれた設定ファイルで指定されていない場合は <current_working_directory>/GriptapeNodes がデフォルトとなります。
- 値が空であるということは、そのファイルではその設定を指定していないことを意味します。設定値をクリアすることはファイルからそのエントリを削除することと同等であり、リストの次のファイル（または組み込みデフォルト）が代わりに適用されます。手動でエントリを削除する必要はありません。
ランタイム管理 (ConfigManager) 初期設定の読み込み後、ConfigManager が最終的に解決された設定（特にワークスペースディレクトリ）を使用して実行時の操作を処理します。登録されたワークフローなどのユーザー固有の変更を、ワークスペース内の設定ファイルに書き戻す役割を担います。
- 設定が読み込まれると、ConfigManager は最終解決された workspace_directory を使用します。
- 実行時に行われた変更（カスタムワークフローの登録など）は、通常 ConfigManager によってこの解決された workspace_directory 内の griptape_nodes_config.json ファイルに保存されます。

読み込みシナリオの例

設定ファイルがどのように検索され読み込まれるかを説明する具体例です：

シナリオ 1: デフォルト設定を使用する場合

gtn init を実行し、デフォルト設定をそのまま受け入れます。
gtn init は ~/.config/griptape_nodes/griptape_nodes_config.json と ~/.config/griptape_nodes/.env を作成します。.json ファイル内の workspace_directory は <initを実行した現在のディレクトリ>/GriptapeNodes を指すように設定されます。
その後、/home/user/my_project/ から gtn を実行します。

ファイル構造:

/home/user/
    my_project/          <-- 'gtn' 実行時の CWD（カレントディレクトリ）
        GriptapeNodes/   <-- デフォルトワークスペース（ランタイム保存設定を含む場合あり）
        my_flow.graph.json
    .config/
        griptape_nodes/
            .env                     # 環境変数用として読み込み
            griptape_nodes_config.json # workspace_directory = /home/user/my_project/GriptapeNodes を保持

読み込みプロセス:
1. 組み込みデフォルトを読み込みます。
2. ~/.config/griptape_nodes/griptape_nodes_config.json を読み込み（検出成功！）、デフォルト値の上にマージします。
3. 結果: workspace_directory は /home/user/my_project/GriptapeNodes に設定されます。以降の ConfigManager によるランタイム変更は、/home/user/my_project/GriptapeNodes/griptape_nodes_config.json に保存されます。

シナリオ 2: カスタムワークスペースを使用する場合

gtn init --workspace-directory /data/gtn_work を実行します。
gtn init は ~/.config/griptape_nodes/griptape_nodes_config.json（workspace_directory = "/data/gtn_work" を設定）および ~/.config/griptape_nodes/.env を作成します。
ワークスペース固有の設定を保持するために、手動で /data/gtn_work/griptape_nodes_config.json を作成することもできます。
/home/user/some_dir/ から gtn を実行します。

ファイル構造:

/home/user/
    some_dir/            <-- 'gtn' 実行時の CWD
    .config/
        griptape_nodes/
            .env                     # 環境変数用として読み込み
            griptape_nodes_config.json # workspace_directory = /data/gtn_work を保持
/data/
    gtn_work/            <-- カスタムワークスペース
        griptape_nodes_config.json # ワークスペース設定（ランタイム変更の保存先でもある）
        project_flows/

読み込みプロセス:
1. 組み込みデフォルトを読み込みます。
2. ~/.config/griptape_nodes/griptape_nodes_config.json を読み込み（検出成功！）、デフォルト値の上にマージします。これにより workspace_directory が /data/gtn_work に設定されます。
3. ワークスペースを解決し、/data/gtn_work/griptape_nodes_config.json をワークスペース設定として読み込み、ユーザー設定の上にマージします。
4. 結果: workspace_directory は /data/gtn_work となります。ワークスペース設定内の項目が、このワークスペースにおけるユーザー設定を上書きします。実行時の変更は /data/gtn_work/griptape_nodes_config.json に書き戻されます。

シナリオ 3: ユーザー設定が存在しない場合（組み込みデフォルトのみ）

gtn init を実行していないか、~/.config/griptape_nodes/ を削除した状態です。
アクティブなプロジェクトがない状態で、/home/user/my_project/ から gtn を実行します。

ファイル構造:

/home/user/
    my_project/          <-- 'gtn' 実行時の CWD
        GriptapeNodes/   <-- デフォルトワークスペースの場所
        my_flow.graph.json

読み込みプロセス:
1. 組み込みデフォルトを読み込みます。
2. ~/.config/griptape_nodes/griptape_nodes_config.json をチェックします（見つからないと仮定）。
3. プロジェクトがアクティブではないため、プロジェクト隣接設定も読み込まれません。
4. 結果: アプリケーションは組み込みデフォルトで動作します。workspace_directory はデフォルトである <current_working_directory>/GriptapeNodes = /home/user/my_project/GriptapeNodes にフォールバックし、実行時の変更はそのワークスペース内に作成される griptape_nodes_config.json に保存されます。

環境変数によるオーバーライド

設定値は、GTN_CONFIG_ プレフィックスを付けた環境変数を使用して設定または上書きできます。キーは大文字の設定名となります：

GTN_CONFIG_<SETTING_NAME>=<value>

ネストされた設定（worker、agent、または library などのオブジェクト内に存在する設定）には、パスの各階層をダブルアンダースコア（__）で区切って大文字で指定します：

GTN_CONFIG_<PARENT>__<SUB_KEY>=<value>

シングルアンダースコアではなくダブルアンダースコアが必要な理由は、設定名自体にすでにアンダースコアが含まれているためです。例えば GTN_CONFIG_WORKER_HEARTBEAT_TIMEOUT_S だと、トップレベルの worker_heartbeat_timeout_s なのか、ネストされた worker.heartbeat_timeout_s なのかが曖昧になってしまいます。設定名自体に __ が含まれることはないため、階層が深くなる位置を曖昧さなく特定できます。

環境変数によるオーバーライドは最優先の権限を持ちます — ユーザー設定ファイル、プロジェクト隣接設定ファイル、プロジェクトごとのワークスペースオーバーライド、および組み込みデフォルトのすべてを上書きします。

設定例：

設定項目	環境変数
`workspace_directory`	`GTN_CONFIG_WORKSPACE_DIRECTORY`
`libraries_directory`	`GTN_CONFIG_LIBRARIES_DIRECTORY`
`project_file`	`GTN_CONFIG_PROJECT_FILE`
`log_level`	`GTN_CONFIG_LOG_LEVEL`
`storage_backend`	`GTN_CONFIG_STORAGE_BACKEND`
`worker.heartbeat_timeout_s`	`GTN_CONFIG_WORKER__HEARTBEAT_TIMEOUT_S`
`library.lazy_node_loading`	`GTN_CONFIG_LIBRARY__LAZY_NODE_LOADING`
`agent.system_prompt`	`GTN_CONFIG_AGENT__SYSTEM_PROMPT`

これは、設定ファイルを変更することなく設定を注入したいスクリプト環境、コンテナ、および CI/CD パイプラインで非常に便利です：

GTN_CONFIG_PROJECT_FILE=/shared/studio-project.yml gtn
GTN_CONFIG_WORKER__HEARTBEAT_TIMEOUT_S=30 gtn
GTN_CONFIG_LIBRARY__LAZY_NODE_LOADING=false gtn
GTN_CONFIG_AGENT__SYSTEM_PROMPT="Answer tersely." gtn

値は有効化される前にその設定の宣言された型へと自動変換されます。そのため、ブール値設定に対する false は False として扱われ（真と評価される文字列 "false" ではありません）、数値設定に対する 30 はテキストではなく数値の 30 として扱われます。ただし、この変換は GTN_CONFIG_ARTIFACTS__SOME_KEY のようなマッピング値の設定のエントリには適用されません。その値は何でも受け入れられるように型付けされているため、記述されたとおりにそのまま渡されます。ブール値や数値のマッピングエントリを指定したい場合は、代わりに設定ファイルを使用してください。

2 つの制限事項:

リスト値の設定、および大文字と小文字を区別するキー。 リストには Settings モデルが受け付ける文字列表現がないため、app_events.on_app_initialization_complete.libraries_to_register や mcp_servers などのリストを保持する設定は、環境変数からは設定できません。一方、マッピング値の設定は異なり、GTN_CONFIG_<NAME>__<KEY>=<value>（例: GTN_CONFIG_ARTIFACTS__SOME_KEY=1）のようにエントリを設定できます。ただし、変数名全体が小文字に変換されてから設定キーになるため、キーが最初から小文字であるエントリにしか到達できません。そのため、artifacts はこの方法で使用できますが、project_workspaces（キーは大文字小文字を区別するプロジェクト ID またはファイルパス）や secrets_to_register（大文字のシークレット名）は実際には信頼性が低く、nodes.<LibraryName>.<SECRET_NAME> などの宣言された設定外の大文字小文字を区別するパスには一切到達できません。これらを設定する場合は、griptape_nodes_config.json ファイルを直接編集してください。

パース不可能な値は通常設定ファイルへとフォールバックしますが、4 つの設定は例外です。 設定の型に適合しない値（例: GTN_CONFIG_MAX_NODES_IN_PARALLEL=not-a-number）は警告ととも無視され、代わりに設定ファイルレイヤーから値が供給されます。しかし、log_level、workflow_execution_mode、thread_storage_backend、および library.dependency_install_behavior は例外です。これらに認識できない値を指定すると、警告も出ず、設定ファイルへのフォールバックも行われず、自動的にその設定の組み込みデフォルト値になります。

各設定の具体的な環境変数名（ネストされた各サブキーの完全な __ パスを含む）については、設定リファレンスを参照してください。

再帰的検出深度 (`discovery_max_depth`)

projects_to_register、libraries_to_register、または workflows_to_register がディレクトリを指している場合、エンジンは起動時にそのディレクトリを再帰的にスキャンして関連ファイル（それぞれプロジェクトファイル、ライブラリマニフェスト、およびワークフローファイル）を探します。異常に深いツリー（またはシンボリックリンクの循環ループ）によって起動処理が停止してしまわないよう、スキャンの深さには上限が設けられています。discovery_max_depth 設定はこの上限を制御し、デフォルト値は登録ディレクトリの配下 5 階層となっており、通常のディレクトリ構造を余裕をもってカバーします。

通常の設定項目であるため、任意の設定ファイルで指定することも、GTN_CONFIG_DISCOVERY_MAX_DEPTH 環境変数で上書きすることも可能です：

GTN_CONFIG_DISCOVERY_MAX_DEPTH=20 gtn   # より深くネストされた構造をスキャン

値を 0 に設定すると、最上位ディレクトリのみをスキャンします（サブディレクトリはスキャンされません）。

ワークスペースディレクトリ (Workspace Directory)

gtn init の実行時に、ワークスペースディレクトリを指定します。これは、プロジェクト、保存したフロー、およびプロジェクト固有の設定を格納するルートディレクトリとなります。

gtn init はデフォルトとして <current_working_directory>/GriptapeNodes を提案しますが、任意の場所を選択できます。Griptape Nodes は指定された正確なパスを使用し、システム griptape_nodes_config.json に保存されます。

ハードコードされた GriptapeNodes サブディレクトリ内を自動検索するようなことはありません。設定されたパスのみを参照します。

ライブラリのワークスペースからの分離

デフォルトでは、ダウンロードされたライブラリはワークスペース内部の libraries/ フォルダに配置されます。これは libraries_directory が workspace_directory に対する相対パスとして解決されるためです。ワークスペースが低速なドライブやリモートドライブ（ネットワーク共有、マウントされたボリュームなど）上にある場合、エンジンはディスクから頻繁にライブラリコードを読み取るため、そこにライブラリを置くとパフォーマンスが低下する可能性があります。

ワークスペース（プロジェクト、ワークフロー、生成されたアセット）をリモートドライブに置いたまま、libraries_directory を高速なローカルストレージ上の絶対パスに向けることができます。libraries_directory が絶対パスである場合、そのまま使用され、ライブラリの保存先としてワークスペースの場所は無視されます：

{
    "workspace_directory": "/Volumes/team-share/GriptapeNodes",
    "libraries_directory": "/Users/me/.griptape-nodes-libraries"
}

環境変数でも同等に設定できます：

GTN_CONFIG_LIBRARIES_DIRECTORY=/Users/me/.griptape-nodes-libraries gtn

同じ相対パス vs 絶対パスのルールが sandbox_library_directory および static_files_directory にも適用されるため、ワークスペースをリモートに残したまま、これらを個別にローカルストレージへ再配置できます。

ここでの libraries_directory はマシン全体のデフォルトです。個々のプロジェクトは、プロジェクトファイル内の独自の libraries_dir フィールドでこれを上書きできます。この設定値よりもプロジェクトファイルの記述が優先され、プロジェクトとともに持ち運ばれます（子プロジェクトにも継承されます）。エンジン全体でライブラリを再配置したい場合は設定オプションを使用し、特定のプロジェクトやプロジェクトツリーが独自の共有ライブラリの場所を必要とする場合はプロジェクトフィールドを使用してください。

エンジンが公開する変数

上記で説明した変数はすべてあなたが設定するものです。エンジン側も、起動時に自身の環境内にあなたが参照するための変数を 1 つ公開します：

変数名	値
`GTN_DEFAULT_LIBRARIES_ROOT`	デフォルトでライブラリがインストールされるディレクトリの絶対パス

この変数は手動で設定するものではありません。その目的は、マシンごとにパスをハードコードすることなく、プロジェクトファイルからこのエンジンがライブラリを保持している場所を指し示せるようにすることです：

libraries_dir: "${GTN_DEFAULT_LIBRARIES_ROOT}/shared"

これは griptape-nodes init が標準ライブラリをインストールする場所と同じ場所に解決されるため、プロジェクトが独自のコピーをダウンロードする代わりに、既存のライブラリツリーを共有できます。値は常に絶対パスであるため、相対値をワークスペースではなくプロジェクトファイル自身のディレクトリに固定する libraries_dir 内で安全に使用できます。

公開される値には、libraries_directory や GTN_CONFIG_LIBRARIES_DIRECTORY を含む、このエンジンがライブラリをどこに保持しているかを記述する設定が反映されます。プロジェクト自身の libraries_dir は、まさにこの変数を読み取る側のフィールドであるため、意図的に反映されません。また、この値は起動時に一度だけ計算されるため、プロジェクトを開いたときに libraries_directory を変更するプロジェクト隣接設定やワークスペースの griptape_nodes_config.json の内容は反映されません。

Warning

何も設定されていない変数を指定しているプロジェクトファイルは読み込み時に拒否され、プロジェクトを開くことができません。そのため、${GTN_DEFAULT_LIBRARIES_ROOT} を使用するプロジェクトファイルには、それを公開しているエンジンバージョンが必要です。

静的ファイルサーバーの設定 (Static File Server Configuration)

Griptape Nodes の実行時、ローカルの静的ファイルサーバーがワークフローによって生成されたメディアアセット（画像、動画、音声）を配信します。static_server_base_url 設定は、これらのファイルへのリンクを生成する際に使用されるベース URL を制御します。デフォルトでは http://localhost:8124 が使用されますが、トンネル、プロキシを使用する場合やコンテナにデプロイする場合には上書きできます。

この設定を上書きすべきケース

以下のようなシナリオで static_server_base_url の設定が必要になります：

トンネリングサービス: ngrok や Cloudflare Tunnels などのサービスを使用してローカルサーバーを外部に公開する場合
Docker / Kubernetes: 内部アドレスが外部アクセスポイントと異なるコンテナ内で実行する場合
リバースプロキシ: nginx、Apache などのリバースプロキシの背後で実行する場合
リモート開発: リモートマシン上で作業し、ローカルブラウザから UI にアクセスする場合
チームコラボレーション: 生成されたメディアにアクセスする必要があるチームメンバーと実行中のインスタンスを共有する場合

設定方法

静的サーバーのベース URL は、Griptape Nodes UI の Settings ダイアログにある static_server_base_url 設定で指定します。明示的に設定されていない場合は、デフォルトの http://localhost:8124 になります（または、環境変数 STATIC_SERVER_HOST および STATIC_SERVER_PORT が設定されている場合はそれに従います）。デフォルトに戻すにはフィールドをクリアしてください（空の値は未設定として解釈されます）。

この設定を変更した後は、変更を反映するために Griptape Nodes エンジンを再起動する必要があります。

シナリオ例

シナリオ 1: ngrok を使用したローカル開発

生成されたメディアファイルにアクセスする必要がある Webhook 連携をテストしている場合。

ngrok トンネルを起動: ngrok http 8124
発行された URL をコピー（例: https://abc123.ngrok.app）
Griptape Nodes UI の Settings ダイアログを開く
static_server_base_url 設定をコピーした ngrok URL で更新
Griptape Nodes エンジンを再起動: gtn

これでワークフローがメディアを生成した際：

ローカルアクセス: トンネル URL 経由で動作
外部サービス: ngrok URL 経由でメディアを取得可能
CORS: トンネル URL に対して自動設定

エンジン設定 (Engine Configuration)

エディタ内での設定編集

設定の読み込み順序 (Configuration Loading)

読み込みシナリオの例

環境変数によるオーバーライド

再帰的検出深度 (discovery_max_depth)

ワークスペースディレクトリ (Workspace Directory)

ライブラリのワークスペースからの分離

エンジンが公開する変数

静的ファイルサーバーの設定 (Static File Server Configuration)

この設定を上書きすべきケース

設定方法

シナリオ例

再帰的検出深度 (`discovery_max_depth`)