安装 Griptape Nodes (Installing Griptape Nodes)

部署并运行 Griptape Nodes 通常有两种方式：

Griptape Nodes Desktop 桌面客户端（强烈推荐）—— 官方开箱即用的全托管桌面应用程序，完整打包了执行引擎与前端可视化画布编辑器。自动完成账号登录、自动分配并注入 API 密钥，并提供全量无缝更新支持。完全无需打开终端敲命令行。
手动安装执行引擎 (Manual engine install) —— 面向高级开发人员的高级模式。你可以通过命令行独立安装和启动后端执行引擎，并通过 Web 浏览器访问在线编辑器。

如果你的企业组织直接向你颁发了许可证密钥 (License Key) 而非个人账号，请直接参阅下文的使用许可证激活。

Griptape Nodes Desktop 桌面客户端 (推荐)

Griptape Nodes Desktop 是一款高度集成的桌面应用程序，原生集成了前端编辑器与底层工作流引擎。它会自动安装和管理本地引擎环境、完成用户身份认证并为你自动预分配 Griptape API Key —— 完全无需任何复杂的手工配置。

1. 下载并安装

从官网 griptapenodes.com 下载适配你操作系统的安装包。目前全面支持 macOS、Windows 与 Linux 平台。

2. 账号登录

启动桌面客户端，点击 Login or Sign-Up（登录或注册）使用你的 Griptape 账号登入。

如果你此前已注册过 Griptape Cloud 账号，该凭据可以直接在此无缝登入！

如果你的企业管理员为你颁发了专属的许可证密钥而不是个人账号，请点击下方的 Activate with a License（使用许可证激活）—— 详细流程见使用许可证激活。

3. 选择工作区目录 (Workspace)

首次启动运行客户端时，系统会引导你指定一个工作区目录 (Workspace Directory)。工作区是 Griptape Nodes 保存所有项目工程文件与生成的多媒体资产的本地根目录。你可以直接点击继续采用默认路径，也可以自由选择任何适合的自定义文件夹（例如网络挂载共享盘）。

至此配置全部完成！桌面应用会自动在后台准备好引擎运行环境、生成 API Key 并自动打开可视化工作流编辑器。你已准备就绪，可以随时探索快速入门教程！

后续若需迁移工作区路径、管理许可证授权或调整客户端自动升级行为，可随时在应用设置 (App Settings) 中进行调整。

进阶玩法：命令行手动安装引擎 (Manual Engine Install)

如果你倾向于在纯代码环境中自由掌控后端引擎，可以采用该进阶方案：在命令行终端中自主安装运行后端引擎服务，并通过浏览器直接打开在线 Web 编辑器：https://nodes.griptape.ai。

前端编辑器与后端引擎完全解耦，二者通过底层事件总线服务进行双向异步通信。因此，引擎不必非得与运行浏览器的计算机处于同一台机器上。如果你希望将高性能计算任务交由局域网内拥有更强 GPU 算力的服务器或工作站执行，可以在远程服务器上运行引擎，本节步骤在远程机与本机上完全一致。

1. 注册或登录 Web 控制台

访问 https://griptapenodes.com 并点击右上角登录。

你的 Griptape Cloud 账号同样通用！

登录成功后，浏览器会自动打开在线编辑器。当未检测到任何正在运行的本地引擎连接时，系统会自动弹出引擎设置向导对话框。选择 Get Started 选项卡并展开 Install Engine Manually（手动安装引擎）折叠栏。

2. 安装引擎程序

确保机器上已安装现代 Python 依赖管理工具 uv；
在终端中运行以下命令以全局独立工具方式安装 Griptape Nodes：
```
uv tool install griptape-nodes
```

安装完成后，在终端中首次执行 griptape-nodes（或使用内置简写别名 gtn），控制台会进入交互式引导初始化问答。

3. 初始化交互配置

第一步：命令行提示输入 Griptape API Key。该 API 密钥用于授权本地引擎与 Web 编辑器建立受信的事件中继长连接。

切回浏览器中的编辑器标签页。在引擎设置弹窗的 Get Started → Install Engine Manually 区域中，展开 Generate an API Key（生成 API Key）步骤；
点击 Generate API Key 按钮，系统会即时生成一段长 Token 凭据；
复制该 Token 并粘贴至终端控制台提示符处（该 Token 在浏览器端仅展示一次，请务必在关闭前复制并妥善保管）。

╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Griptape API Key                                                                                                        │
│         A Griptape API Key is needed to proceed.                                                                        │
│         This key allows the Griptape Nodes Engine to communicate with the Griptape Nodes Editor.                        │
│         In order to get your key, return to the https://nodes.griptape.ai tab in your browser and click the button      │
│         "Generate API Key".                                                                                             │
│         Once the key is generated, copy and paste its value here to proceed.                                            │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Griptape API Key (YOUR-KEY-HERE):

复用已存在的凭据

如果你此前曾执行过 gtn init，控制台可能会自动检测并高亮已存在的 Key，直接敲回车（Enter）即可确认沿用。

第二步：配置工作区目录（Workspace Directory）。工作区是引擎在本地保存工作流工程文件与生成的多媒体资产的根路径，同时还包含存放各类第三方模型服务商密钥的 .env 文件。

╭───────────────────────────────────────────────────────────────────╮
│ Workspace Directory                                               │
│     Select the workspace directory. This is the location where    │
│     Griptape Nodes will store your saved workflows.               │
│     You may enter a custom directory or press Return to accept    │
│     the default workspace directory                               │
╰───────────────────────────────────────────────────────────────────╯
Workspace Directory (/Users/user/Documents/GriptapeNodes)

直接敲回车将采用默认路径：<当前运行目录>/GriptapeNodes。当然，你也可以在此手动输入任何自定义的绝对路径。

最后一步：可选的高阶配置项（均可直接按回车跳过并采用安全默认值，后续随时可调）：

Storage backend (存储后端) —— 静态生成文件的落盘方式：本地磁盘（local，默认推荐）或 Griptape Cloud 云端存储桶（gtc）；
Griptape Cloud bucket (云存储桶) —— 用于在多台开发机之间漫游同步工作流与资产；
Hugging Face token —— 仅当你需要自动拉取 Hugging Face 上受门禁保护 (Gated) 的模型权重时需要配置；
Additional libraries (扩展算子库) —— 可选一键安装官方的 Diffusers 扩散模型库与 Griptape Cloud 云能力算子库。

后续如果需要重新唤起此初始化流程修改配置，随时在终端中运行 gtn init 即可。

4. 启动引擎并开始创作

配置收尾后，在终端中敲入 griptape-nodes（或 gtn）回车启动引擎守护进程。此时切回浏览器中的 https://nodes.griptape.ai 页面，界面会自动感应并刷新，呈现 Create from scratch（从空白画布新建）按钮以及若干官方预置示例工作流，点击即可开启图计算编排！

使用企业许可证激活 (Activating with a License)

企业组织通常采用企业级许可证（License Keys）机制统一管控席位，而非要求员工各自注册个人账号。如果你收到了企业 IT 管理员分发的许可证密钥，完全无需在公网注册任何账号：

如上所述下载并安装 Griptape Nodes Desktop 桌面客户端；
在登录欢迎界面上，点击底部的 Activate with a License，不要点击登录按钮；
粘贴管理员分发的 License Key 字符串，点击 Activate 完成受信激活。

如果企业在内网部署了专属的 Admin Server 管理服务器，你还需要在激活弹窗中将端点地址替换为企业内网服务地址。详尽的图文分步流程请参阅使用企业管理服务器激活指南。

企业 IT 管理员若需了解许可证密钥的批量颁发、并发会话审计与 Cedar 策略控制，请参阅企业管理看板指南。关于各类部署模式下的系统底层通信拓扑，请参阅系统架构总览。

下一步 (Next Steps)

现在，开始探索在 Griptape Nodes 中构建与运行第一个 AI 图像与文本生成工作流：快速入门教程！

如需彻底移除清理软件，请参阅卸载 Griptape Nodes 指南。