設定リファレンス (Configuration Reference)

Griptape Nodes エンジンのすべての設定項目をカテゴリ別にまとめたリファレンスです。各設定は任意の griptape_nodes_config.json ファイル内に記述できます（読み込み順序については エンジン設定ガイド を参照）。ネストされた設定は、griptape-nodes config show が受け付ける形式であり後述の環境変数名が構築される元となる、完全なドット区切りキーの下に一覧表示されます。設定ファイル内では、そのキーの各部分を JSON オブジェクトとしてネストして記述します。例えば worker.heartbeat_timeout_s は {"worker": {"heartbeat_timeout_s": 30}} と記述し、平坦な "worker.heartbeat_timeout_s" キーは無視されます。GTN_CONFIG_* 環境変数が用意されている設定（ドット区切りの各部分を __ で連結した GTN_CONFIG_<PATH> 形式や、マッピング型設定のエントリを指定する GTN_CONFIG_<NAME>__<KEY> 形式を含む）は、環境変数からオーバーライドすることも可能です。リスト値の設定は設定ファイル内で直接編集する必要があります。マッピングのキーは大文字小文字を区別して照合されますが、環境変数名全体は小文字化されるため、環境変数から到達できるのは最初から小文字のキーのみです（詳細はガイドを参照）。

ファイルシステム (File System)

アプリケーションのディレクトリおよびファイルパス設定

設定名	型	デフォルト値	環境変数	説明
workspace_directory	string	<current_working_directory>/GriptapeNodes	GTN_CONFIG_WORKSPACE_DIRECTORY	プロジェクト、ワークフロー、生成アセットのルートディレクトリ。デフォルトはカレント作業ディレクトリ直下の GriptapeNodes フォルダです。他のファイルシステムパス（libraries_directory、static_files_directory、sandbox_library_directory、synced_workflows_directory）は、絶対パスで指定されない限り、このディレクトリからの相対パスとして解釈されます。
static_files_directory	string	"staticfiles"	GTN_CONFIG_STATIC_FILES_DIRECTORY	静的ファイルディレクトリのパス。ワークスペースディレクトリからの相対パス。
sandbox_library_directory	string	"sandbox_library"	GTN_CONFIG_SANDBOX_LIBRARY_DIRECTORY	サンドボックスライブラリディレクトリのパス（カスタムノード開発時に有用）。相対パスはワークスペースディレクトリ基準で解釈され、絶対パスはそのまま使用されます。
libraries_directory	string	"libraries"	GTN_CONFIG_LIBRARIES_DIRECTORY	ダウンロードされたライブラリを配置するディレクトリのパス。起動時に再帰的に検索されたすべての griptape_nodes_library.json ファイルが自動検出されます。相対パスはワークスペースディレクトリ基準で解釈され、絶対パスはそのまま使用されます。プロジェクトテンプレートの libraries_dir フィールド（親プロジェクトチェーン経由で継承可能）によってこの場所をオーバーライドでき、その場合は子プロジェクトが親のライブラリインストール場所を共有できるようにこの値よりも優先されます。
ffmpeg_directory	string	""	GTN_CONFIG_FFMPEG_DIRECTORY	初回使用時にエンジンが自動ダウンロードする ffmpeg/ffprobe バイナリを保持するディレクトリの絶対パス。他のディレクトリ設定とは異なり、ワークスペースからの相対パスとしては決して解釈されません：ffmpeg キャッシュはワークスペースではなくマシン全体に属するため、すべてのワークスペースとプロジェクトで共有されます。相対パスを指定すると警告ととも​​に無視されます。空（デフォルト）の場合は <XDG_DATA_HOME>/griptape_nodes/ffmpeg を意味します。ダウンロードせずに自前のバイナリを使用する場合は、ffmpeg、ffprobe、および空の installed.crumb ファイルを格納した bin/<platform>/ ディレクトリを含むフォルダを指定してください（static-ffmpeg はそのマーカーをインストール完了の証明として扱い、マーカーがない場合はバイナリを上書き再ダウンロードします）。
synced_workflows_directory	string	"synced_workflows"	GTN_CONFIG_SYNCED_WORKFLOWS_DIRECTORY	同期されたワークフローディレクトリのパス。ワークスペースディレクトリからの相対パス。
enable_workspace_file_watching	boolean	true	GTN_CONFIG_ENABLE_WORKSPACE_FILE_WATCHING	同期されたワークフローディレクトリのファイル監視（ファイル変更検知）を有効にするかどうか。

アプリケーションイベント (Application Events)

アプリケーションのライフサイクルイベントに関する設定

設定名	型	デフォルト値	環境変数	説明
app_events.on_app_initialization_complete.libraries_to_download	array of (string または LibraryDownload)	[]	利用不可（設定ファイルを編集）	エンジン起動時に libraries_directory へ自動ダウンロードするライブラリの一覧。各エントリはプレーンな Git URL 文字列、または git_url と任意の PEP 440 version 指定およびマニフェスト name を持つオブジェクトです。Git URL は完全な URL または GitHub 短縮形（例: 'user/repo'）をサポートします。@ref 構文でブランチ、タグ、コミットを任意に指定できます（例: 'user/repo@stable'、'https://github.com/user/repo@v1.0.0'）。ref が指定されていない場合はリポジトリのデフォルトブランチが使用されます。エンジンは各エントリを固定バージョンに合わせてプロビジョニングし、誤ったインストールバージョンを上書きする場合があります（libraries_to_register にのみ記載されているライブラリが上書きされることはありません）。
app_events.on_app_initialization_complete.libraries_to_register	array of (string または LibraryRegistration)	[]	利用不可（設定ファイルを編集）	エンジン起動時に読み込むライブラリ。各エントリは単一の griptape_nodes_library.json ファイルへのパス、または 1 つ以上のライブラリを含むフォルダへのパスです。トグルを使用してライブラリを有効化またはスキップでき、ライブラリがサポートしている場合はエンジンと並行して実行するか、専用の分離プロセス内で実行するかを選択できます。
app_events.on_app_initialization_complete.workflows_to_register	array of string	[]	利用不可（設定ファイルを編集）	起動時に登録するワークフローファイルのリスト。
app_events.on_app_initialization_complete.secrets_to_register	(array of string) または object	{"HF_TOKEN": "", "GT_CLOUD_API_KEY": ""}	GTN_CONFIG_APP_EVENTS__ON_APP_INITIALIZATION_COMPLETE__SECRETS_TO_REGISTER__<KEY>	登録するコアシークレット。シークレット名のリスト（空文字がデフォルト値）または名前とデフォルト値のマッピング辞書を指定できます。ライブラリ固有のシークレットは、ライブラリ設定から自動的に登録されます。
app_events.on_app_initialization_complete.models_to_download	array of string	[]	利用不可（設定ファイルを編集）	起動時に自動ダウンロードするモデルのリスト。
app_events.events_to_echo_as_retained_mode	array of string	["CreateConnectionRequest", "DeleteConnectionRequest", "CreateFlowRequest", ...]（22 項目）	利用不可（設定ファイルを編集）	Retained Mode コマンドとしてエコー出力するイベントのリスト。

プロジェクト (Projects)

プロジェクトテンプレートの設定および登録

設定名	型	デフォルト値	環境変数	説明
app_events.on_app_initialization_complete.projects_to_register	array of (string または PerPlatformProjectPath)	[]	利用不可（設定ファイルを編集）	起動時に読み込むプロジェクトエントリのリスト。各エントリは次のいずれかです：(1) 単一のパス文字列（${ENV_VAR} および ~ 展開をサポート）、または (2) 同一プロジェクトが各 OS で異なるパスに解決されるクロスプラットフォーム展開用の、オプショナルな linux、darwin、windows、default キーを持つプラットフォーム別マッピング。パスエントリは単一の griptape-nodes-project.yml ファイル、またはすべての griptape-nodes-project.yml ファイルを再帰的にスキャンするディレクトリ（それぞれ登録テンプレートとして読み込まれます）を指すことができます。ディレクトリのエントリはそのまま保持され起動ごとに再スキャンされます。検出されたファイルが個別のエントリに展開されることはありません。アクティブなプラットフォームに一致するキーがなく default もないプラットフォーム別エントリは、警告ととも​​にスキップされます。
app_events.on_app_initialization_complete.requires_engine	string	null	GTN_CONFIG_APP_EVENTS__ON_APP_INITIALIZATION_COMPLETE__REQUIRES_ENGINE	実行中のエンジンが満たす必要のある PEP 440 バージョン指定子（例: '>=0.5,<0.6'）。不一致の場合はプロジェクトの有効化がブロックされます。通常はプロジェクト隣接の設定ファイルで設定され、プロジェクトが依存するエンジンバージョンの信頼できる唯一の情報源（SSOT）になります。
project_file	string	null	GTN_CONFIG_PROJECT_FILE	エンジン起動時に最初に読み込むプロジェクトファイル（griptape-nodes-project.yml）のパス。設定されている場合、デフォルトの <workspace_directory>/griptape-nodes-project.yml をオーバーライドします。指定されたパスが存在しない場合はワークスペースのデフォルトにフォールバックします。センチネル値 '<system-defaults>' は、エンジンが意図的にシステムデフォルトに留まり、ワークスペースデフォルトへのフォールバックを抑制すること（ワークスペース内の griptape-nodes-project.yml を自動検出しない）を意味します。これはエンジンが意図的にシステムデフォルトを使用している場合に永続化される値です。
project_workspaces	object	{}	GTN_CONFIG_PROJECT_WORKSPACES__<KEY>	プロジェクト識別子からワークスペースディレクトリのオーバーライドへのマッピング。キーはプロジェクト ID またはプロジェクトファイルパスのいずれかです：まず読み込まれたプロジェクト ID と照合され、一致するものがない場合はプロジェクトファイルパスとして扱われます。プロジェクトが読み込まれた際、ここに一致するキーがあれば、プロジェクト隣接設定や自動デフォルトの代わりにその対応する値がワークスペースディレクトリとして使用されます。

実行 (Execution)

ワークフローの実行および処理に関する設定

設定名	型	デフォルト値	環境変数	説明
log_level	CRITICAL, ERROR, WARNING, INFO, DEBUG のいずれか	"INFO"	GTN_CONFIG_LOG_LEVEL	エンジンのログ詳細度。CRITICAL、ERROR、WARNING、INFO、DEBUG のいずれか（左から右へ詳細度が高くなります）。
workflow_execution_mode	sequential, parallel のいずれか	"sequential"	GTN_CONFIG_WORKFLOW_EXECUTION_MODE	ノード処理のワークフロー実行モード。SEQUENTIAL モードは max_nodes_in_parallel=1 の ParallelResolutionMachine を使用してノードを 1 つずつ実行します。PARALLEL モードは設定された max_nodes_in_parallel の値を使用します。
max_nodes_in_parallel	integer	5	GTN_CONFIG_MAX_NODES_IN_PARALLEL	並列実行時に同時に実行できるノードの最大数。
worker.heartbeat_interval_s	number	5.0	GTN_CONFIG_WORKER__HEARTBEAT_INTERVAL_S	オーケストレーターから送信されるワーカーハートビート確認の間隔（秒単位）。
worker.heartbeat_timeout_s	number	15.0	GTN_CONFIG_WORKER__HEARTBEAT_TIMEOUT_S	ワーカーが退去（立ち退き）されるまでのハートビート応答なしの秒数。ワーカー側もオーケストレーターからの応答がこの秒数途絶過すると自動終了しますが、ビジー状態のオーケストレーターを終了と誤認しないよう、30 秒より早く終了することはありません。
worker.library_load_timeout_s	number	600.0	GTN_CONFIG_WORKER__LIBRARY_LOAD_TIMEOUT_S	オーケストレーターがライブラリを FAILURE（失敗）とマークするまでに、ワーカーがライブラリの読み込みに費やすことができる秒数。ノードの実行がそのライブラリのワーカーの読み込み完了を待機する時間や、プロジェクト切り替え時に各ワーカーがそれを適用するのを待機する時間の上限でもあります。巨大なライブラリ（torch、diffusers など）の初回インストールは 2 分を容易に超えることがあります。ハートビートには影響しません（ハートビートについては worker.heartbeat_timeout_s を参照）。

ロギング (Logging)

エンジンログの保存場所と履歴保持に関する設定

設定名	型	デフォルト値	環境変数	説明
logging.log_to_file	boolean	true	GTN_CONFIG_LOGGING__LOG_TO_FILE	コンソール出力に加えてファイルにもエンジンログを書き込みます。各エンジンプロセスは独自のファイルに書き込み、10 MB でローテーションし最大 5 世代保持するため、プロセスごとの総容量は制限されます。現在実行中のセッションのログのみが必要な場合は、これをオフにしてください。
logging.log_directory	string	""	GTN_CONFIG_LOGGING__LOG_DIRECTORY	エンジンログファイルを保持するディレクトリの絶対パス。ffmpeg_directory と同様に、ワークスペースからの相対パスとしては決して解釈されません：ログはワークスペースではなくマシンに属するため、すべてのワークスペースとプロジェクトで一箇所の場所を共有します。相対パスは警告ととも​​に無視されます。空（デフォルト）の場合は <XDG_STATE_HOME>/griptape_nodes/logs を意味します。
logging.log_retention_days	integer	7	GTN_CONFIG_LOGGING__LOG_RETENTION_DAYS	指定した日数の間書き込みが行われなかったエンジンログファイルを自動削除します。エンジン起動時、およびロギング設定が変更されるたびにチェックされます。エンジンが現在書き込みを行っているアクティブなログファイルは、どれだけ古くても削除されません。ログファイルを無期限に保持するには 0 を設定します。
logging.session_log_buffer_lines	integer	5000	GTN_CONFIG_LOGGING__SESSION_LOG_BUFFER_LINES	不具合の再現を行わなくても直前の動作を問題レポートに含められるように、エンジンが現在のセッション用にメモリ内に保持する最新のログ行数。これらの行には log_level で許可されたすべてのログが含まれるため、レポートにデバッグ詳細が必要な場合は不具合の再現前に log_level を DEBUG に引き上げてください。0 に設定すると無効になり、問題レポートにはログファイルに書き込まれた内容のみが含まれるようになります。

ストレージ (Storage)

データストレージおよび永続化に関する設定

設定名	型	デフォルト値	環境変数	説明
storage_backend	local, gtc のいずれか	"local"	GTN_CONFIG_STORAGE_BACKEND	ワークフローデータおよび生成アセットの永続化に使用されるバックエンド。'local' はワークスペース配下のローカルファイルシステムにファイルを保存し、'gtc' は Griptape Cloud ストレージを使用します。
auto_inject_workflow_metadata	boolean	true	GTN_CONFIG_AUTO_INJECT_WORKFLOW_METADATA	サポートされている形式で保存されたファイルにワークフローのメタデータを自動注入するかどうか。
thread_storage_backend	"local"（定数）	"local"	GTN_CONFIG_THREAD_STORAGE_BACKEND	カンバセーションスレッドのストレージバックエンド。'local'（ファイルシステム）のみがサポートされています（Griptape Cloud サポートは Pydantic AI への移行時に廃止されました）。

システム要件 (System Requirements)

システムリソースの要件および制限値

設定名	型	デフォルト値	環境変数	説明
minimum_disk_space_gb_libraries	number	10.0	GTN_CONFIG_MINIMUM_DISK_SPACE_GB_LIBRARIES	ライブラリのインストールおよび仮想環境の操作に必要な最小ディスク容量（GB 単位）。
minimum_disk_space_gb_workflows	number	1.0	GTN_CONFIG_MINIMUM_DISK_SPACE_GB_WORKFLOWS	ワークフローの保存に必要な最小ディスク容量（GB 単位）。
discovery_max_depth	integer	5	GTN_CONFIG_DISCOVERY_MAX_DEPTH	登録されたエントリがディレクトリを指している場合に、エンジンがファイルを再帰検出するために走査するディレクトリの最大階層深度（例: projects_to_register 配下のプロジェクトファイル）。異常に深いツリー構造やシンボリックリンクの循環から起動時スキャンを保護します。0 はトップレベルディレクトリのみをスキャンし、ネスト階層ごとに 1 ずつ加算されます。

MCP サーバー (MCP Servers)

Model Context Protocol サーバーの設定

設定名	型	デフォルト値	環境変数	説明
mcp_servers	array of MCPServerConfig	[]	利用不可（設定ファイルを編集）	Model Context Protocol サーバー設定のリスト。

静的ファイルサーバー (Static Server)

メディアアセット配信用の静的ファイルサーバー設定

設定名	型	デフォルト値	環境変数	説明
static_server_base_url	string	null	GTN_CONFIG_STATIC_SERVER_BASE_URL	静的サーバーのベース URL。設定しない場合、サーバーのホスト/ポート（設定ポートが使用できない場合の OS 割り当てポートを含む）から自動導出されます。トンネルツール（ngrok、Cloudflare Tunnel）やリバースプロキシを前段に配置する場合など、導出された URL をオーバーライドする場合にのみ設定してください。

アーティファクト (Artifacts)

アーティファクトプロバイダーおよびプレビュー生成に関する設定

設定名	型	デフォルト値	環境変数	説明
artifacts	object	{}	GTN_CONFIG_ARTIFACTS__<KEY>	画像やその他のメディアファイルのプレビュー生成方法を制御します。

エージェント (Agent)

エージェントの動作およびシステムプロンプト設定

設定名	型	デフォルト値	環境変数	説明
agent.system_prompt	string	""	GTN_CONFIG_AGENT__SYSTEM_PROMPT	エージェントの組み込みシステムプロンプトに追加されるテキスト。トーン、推奨パターン、ドメイン固有のコンテキストのカスタマイズに使用します。

ライブラリ (Libraries)

ライブラリ管理および依存関係のインストールに関する設定

設定名	型	デフォルト値	環境変数	説明
library.dependency_install_behavior	always, never のいずれか	"always"	GTN_CONFIG_LIBRARY__DEPENDENCY_INSTALL_BEHAVIOR	ライブラリマニフェストで宣言された依存関係の自動インストール動作を制御します。'always' は登録時にダウンロードしてインストールします。'never' はインストールをスキップし、必要な依存関係が不足している場合にライブラリを degraded（機能制限）状態としてマークします。
library.lazy_node_loading	boolean	true	GTN_CONFIG_LIBRARY__LAZY_NODE_LOADING	True（デフォルト）の場合、ノードの Python モジュールは起動時ではなく、その型のノードが初めて作成されたとき（またはイントロスペクション時など型が解決されたとき）に遅延インポート（Lazy Loading）されるため、ノード数の多いライブラリや重量級ノードを持つライブラリのエンジン起動時間が短縮されます。トレードオフとして、破損したノードのインポートエラーはその型が作成されるまで報告されません。False に設定すると、エンジンは起動時にすべてのノードの Python モジュールを一括インポートするため、ノードがキャンバスに配置される前にインポートエラーがライブラリの問題として即座に表面化します（ノード開発時にこのチェックを行いたい場合に設定してください）。なお、サンドボックスライブラリ内のノードはこの設定に関係なく常に先行読み込み（Eager Loading）されます。
library.minimum_release_age	number	0.0	GTN_CONFIG_LIBRARY__MINIMUM_RELEASE_AGE	ライブラリ更新を適用するまでの、対象リリースの最小経過時間（時間単位）。0（デフォルト）の場合、利用可能になるとすぐに更新が適用されます。0 より大きい場合、移行先のコミットが少なくともこの時間（時間単位）経過するまで更新が保留され、問題のあるリリースがプッシュされて取り下げ（ヤンク）されるまでの間に自動適用されてしまうリスクを防ぎます。対象コミットの経過時間が特定できない場合（リモートのタイムスタンプが読み取れない場合など）は更新が許可され（フェイルオープン）、警告がログ出力されるため、メタデータの不調によって更新が恒久的にブロックされることはありません。経過時間は対象コミットの Git コミッタータイムスタンプから計測されますが、これは必ずしもリリース公開日時と一致しない点に注意してください（リベース、チェリーピック、過去日付指定（GIT_COMMITTER_DATE）、強制移動されたタグでは、実際の公開日時と異なる経過時間が報告される場合があります）。

ベータ機能 (Beta Features)

オン/オフを切り替え可能な実験的機能の設定

設定名	型	デフォルト値	環境変数	説明
beta_features	object	{}	GTN_CONFIG_BETA_FEATURES__<KEY>	機能 ID をキーとしてオン/オフされる実験的機能。エディタの Beta 設定ページがこれらを書き込みます。このマップにない機能はデフォルト設定を使用します。任意のキーを受け付けるため、エディタ専用機能のためにエンジンの再リリースが必要になることはありません。
library_beta_features	object	{}	GTN_CONFIG_LIBRARY_BETA_FEATURES__<KEY>	ノードライブラリによって定義された実験的機能のオン/オフ。ライブラリ名を小文字にし、空白と記号をアンダースコアに置換した文字列をキーとし、その配下に機能 ID を指定します。このマップにない機能はデフォルト設定を使用します。

エントリ型 (Entry Types)

リスト型またはマッピング型の設定値の内部に出現するオブジェクトのフィールド構造です。これらは設定そのものではなく個別エントリに属するため、固有のドット区切りキーや環境変数は持ちません。エントリとともに設定ファイル内で編集してください。

LibraryDownload

エンジンが特定バージョンにプロビジョニングする libraries_to_download 内のライブラリ情報。

フィールド名	型	デフォルト値	説明
git_url	string	必須	エンジンの url@ref 形式の Git ソース：完全な URL または user/repo 短縮形。任意の @branch|tag|commit サフィックスを付与可能（例: 'griptape-ai/griptape-nodes-library-standard@v2.0'）。
version	string	null	インストールされたライブラリが満たす必要のある PEP 440 バージョン指定子（例: '>=1.2,<2'）。None の場合はソース指定のみで固定。
name	string	null	ライブラリ名。ライブラリマニフェストの name と一致させる必要があります。設定されている場合、再ダウンロードが必要かどうかを判断するためにインストール済みバージョンが名前で照合されます。

LibraryRegistration

任意のメタデータを含む libraries_to_register 内のライブラリ情報。

フィールド名	型	デフォルト値	説明
path	string	必須	griptape_nodes_library.json ファイルまたは再帰的にスキャンされるディレクトリへのパス。
enabled	boolean	true	False の場合、設定には残りますが起動時には読み込まれません。
worker_mode_override	ORCHESTRATOR, WORKER のいずれか	null	ライブラリマニフェストで宣言された起動モードのライブラリ別オーバーライド。ORCHESTRATOR または WORKER。マニフェストが WorkerModeCompatibility.COMPATIBLE を宣言している場合にのみ有効であり、INCOMPATIBLE なライブラリでは無視されます。None はマニフェストの SuggestedWorkerMode に戻します。

PerPlatformProjectPath

プロジェクト YAML パスのプラットフォーム別マッピング。

フィールド名	型	デフォルト値	説明
linux	string	null	Linux 上で使用される値
darwin	string	null	macOS 上で使用される値
windows	string	null	Windows 上で使用される値
default	string	null	アクティブなプラットフォームのキーが未設定の場合のフォールバック値

MCPServerConfig

単一の MCP サーバーの設定。

フィールド名	型	デフォルト値	説明
name	string	必須	MCP サーバーの一意な名前/識別子
enabled	boolean	true	この MCP サーバーを有効にするかどうか
transport	string	"stdio"	トランスポート種別: stdio, sse, streamable_http, または websocket
command	string	null	MCP サーバーを起動するコマンド（stdio では必須）
args	array of string	[]	MCP サーバーコマンドに渡す引数（stdio）
env	object	{}	MCP サーバー用の環境変数（stdio）
cwd	string	null	MCP サーバーの作業ディレクトリ（stdio）
encoding	string	"utf-8"	stdio 通信用テキストエンコーディング
encoding_error_handler	string	"strict"	stdio のエンコーディングエラーハンドラー
url	string	null	HTTP ベース接続（sse, streamable_http, websocket）用の URL
headers	object	null	HTTP ベース接続用の HTTP ヘッダー
timeout	number	null	HTTP タイムアウト（秒単位）
sse_read_timeout	number	null	SSE 読み取りタイムアウト（秒単位）
terminate_on_close	boolean	true	切断時にセッションを終了するかどうか（streamable_http）
description	string	null	この MCP サーバーが提供する機能の任意の説明
capabilities	array of string	[]	この MCP サーバーが提供するケーパビリティのリスト
rules	string	null	この MCP サーバー用の任意のルール文字列