引擎配置项全量参考 (Configuration Reference)

本篇文档按功能分类汇编了 Griptape Nodes 引擎所支持的全部配置项。每个配置项均可声明在任意 griptape_nodes_config.json 配置文件中（有关层级加载顺序，请参阅 引擎配置指南）。嵌套设置按其完整的点分键路径（Dotted Key）展示，这也是 griptape-nodes config show 命令所接受并在下文环境变量中所使用的命名格式。在 JSON 配置文件中，点分键的每一级均作为嵌套对象呈现，例如 worker.heartbeat_timeout_s 在 JSON 中声明为 {"worker": {"heartbeat_timeout_s": 30}}；扁平的 "worker.heartbeat_timeout_s" 键名将被引擎忽略。带 GTN_CONFIG_* 环境变量名称的配置项（包括在点分键之间以 __ 分隔的 GTN_CONFIG_<PATH> 形式，以及映射类型配置项所使用的 GTN_CONFIG_<NAME>__<KEY> 形式）均可从操作系统环境变量进行覆写；列表类型的配置项则必须在配置文件中进行修改。映射的键名在匹配时区分大小写，但环境变量名全局统一转为小写，因此唯有全小写的键名可通过环境变量进行配置（详见配置指南）。

文件系统 (File System)

应用程序使用的核心目录与文件路径配置。

配置项	数据类型	默认值	环境变量	功能描述
workspace_directory	string	<当前工作目录>/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。如需使用系统自带二进制，请将其指向包含 bin/<platform>/ 结构的目录（内含 ffmpeg、ffprobe 以及一个空的 installed.crumb 标记文件——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 or LibraryDownload)	[]	无（请修改配置文件）	引擎启动时自动下载到 libraries_directory 的算子库清单。每个条目可以是纯 Git URL 字符串，也可以是包含 git_url、可选的 PEP 440 version 版本锁定以及清单 name 的对象。支持标准 Git URL 或 GitHub 简写（如 'user/repo'）。可通过 @ref 语法指定分支、标签或 Commit（例如 '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 or LibraryRegistration)	[]	无（请修改配置文件）	引擎在启动时直接装载的算子库。条目可以是单一 griptape_nodes_library.json 文件的路径，也可以是包含一个或多个库的文件夹。可开关启用状态，并在库架构支持时选择将其运行在主引擎内还是独立隔离子进程中。
app_events.on_app_initialization_complete.workflows_to_register	array of string	[]	无（请修改配置文件）	引擎启动初始化完成后需要自动注册的工作流文件列表。
app_events.on_app_initialization_complete.secrets_to_register	(array of string) or 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 项)	无（请修改配置文件）	需要以保留模式命令回显在终端中的底层事件请求类型列表。

项目配置 (Projects)

项目模板配置与注册项。

配置项	数据类型	默认值	环境变量	功能描述
app_events.on_app_initialization_complete.projects_to_register	array of (string or PerPlatformProjectPath)	[]	无（请修改配置文件）	启动时加载的项目条目列表。每个条目可以是：(1) 单一路径字符串（支持 ${ENV_VAR} 与 ~ 展开），或 (2) 包含可选 linux、darwin、windows 与 default 键的平台映射字典，用于跨平台部署时在各系统上解析到不同路径。条目可以指向具体的 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'）。不匹配时将阻止项目激活。通常在项目附属配置中指定，使项目成为其运行引擎版本的唯一事实源。
project_file	string	null	GTN_CONFIG_PROJECT_FILE	引擎启动时初始加载的项目文件路径 (griptape-nodes-project.yml)。设置后将覆写默认的 <workspace_directory>/griptape-nodes-project.yml 位置。若指定路径不存在，则回退到工作区默认位置。哨兵值 '<system-defaults>' 表示引擎显式停留在系统默认配置上并抑制自动回退探测。
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 逐个处理节点；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 子进程发送心跳探活请求的时间间隔（秒）。
worker.heartbeat_timeout_s	number	15.0	GTN_CONFIG_WORKER__HEARTBEAT_TIMEOUT_S	Worker 子进程无心跳响应被判定逐出并回收的超时时间（秒）。Worker 在主进程沉默达到此时长后也会主动自毁，但绝不会早于 30 秒，避免将主进程繁忙误判为已退出。
worker.library_load_timeout_s	number	600.0	GTN_CONFIG_WORKER__LIBRARY_LOAD_TIMEOUT_S	Worker 子进程加载其算子库的最大允许时长（秒），超时主进程将该库标记为 FAILURE。该值同时限制运行节点等待 Worker 加载完毕的最长等待时间，以及切换项目时等待 Worker 适配的时长。大型库（如 torch, diffusers）首次安装加载易超两分钟。本配置不影响心跳。

日志记录 (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	引擎在内存中为当前会话保留的最新日志行数，以便生成问题诊断包时无需复现即可包含刚才发生的事件。设为 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' 本地文件系统。

系统资源要求 (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	引擎递归扫描发现文件（如项目配置）时允许下潜的最大目录层级深度。防止在异常深层目录树或软链接环路中陷入死循环。0 表示仅扫描顶层目录。

MCP 服务器 (MCP Servers)

Model Context Protocol (MCP) 服务器配置项。

配置项	数据类型	默认值	环境变量	功能描述
mcp_servers	array of MCPServerConfig	[]	无（请修改配置文件）	已配置的 Model Context Protocol 服务器连接规范列表。

静态资源服务器 (Static Server)

用于承载媒体资产浏览与分发的静态文件服务器配置。

配置项	数据类型	默认值	环境变量	功能描述
static_server_base_url	string	null	GTN_CONFIG_STATIC_SERVER_BASE_URL	静态服务器的外部基准 URL。未设置时自动根据主机的 host/port 派生。仅在配合反向代理或隧道穿透（ngrok、Cloudflare Tunnel 等）时显式指定以进行外部映射覆写。

资产预览 (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	算子库清单中声明的 pip 依赖自动安装策略。'always' 在注册时全自动下载并构建安装；'never' 跳过安装，若缺少依赖则将库标记为降级状态 (degraded)。
library.lazy_node_loading	boolean	true	GTN_CONFIG_LIBRARY__LAZY_NODE_LOADING	算子延迟按需加载开关。设为 True（默认）时，算子的 Python 模块仅在首次创建其实例或反射内省时才被动态 import 引入，可大幅提升庞大算子库的引擎启动速度；代价是语法错误的算子只有在拖入画布时才报错。设为 False 时，引擎在启动阶段即全量预加载所有算子类，能及早暴露导入缺陷。沙盒开发库不受此限制，始终采用即时加载。
library.minimum_release_age	number	0.0	GTN_CONFIG_LIBRARY__MINIMUM_RELEASE_AGE	应用算子库更新前目标 Release 版本的最小“冷却等待时长”（小时）。默认 0 表示一旦上游发布立刻生效。大于 0 时，引擎将推迟更新，直到目标提交已发布满该时长，防御因误发恶意版本或存在重大缺陷而被未审撤回。

Beta 实验性功能 (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 子进程）。仅在该库声明了兼容 COMPATIBLE 时生效；对明确不兼容的库自动忽略。设为 None 则恢复库清单的预设推荐。

PerPlatformProjectPath

项目 YAML 文件的跨平台专属路径映射规范。

字段名	数据类型	默认值	字段说明
linux	string	null	Linux 操作系统下所使用的路径表达式。
darwin	string	null	macOS (Darwin) 系统下所使用的路径表达式。
windows	string	null	Windows 操作系统下所使用的路径表达式。
default	string	null	当当前平台未明确匹配到指定键时的兜底路径。

MCPServerConfig

单个 Model Context Protocol (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	[]	传递给执行命令的位置参数列表（针对 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 请求头字典。
timeout	number	null	HTTP 网络请求超时阈值（秒）。
sse_read_timeout	number	null	SSE 事件流读取超时阈值（秒）。
terminate_on_close	boolean	true	连接关闭时是否终止后台会话。
description	string	null	描述该 MCP 服务器所提供能力的自然语言说明文档。
capabilities	array of string	[]	该服务器所对外开放的能力特性列表。
rules	string	null	约束该 MCP 服务器行为的专属规则文本。