跳转至

GrayGooAgent 安装与快速开始

适用范围

本指南适用于当前已验证首发基线上的首次成功运行：

  • Unreal Engine 5.7
  • Windows / Win64 editor workflow
  • 作为仅编辑器插件的 GrayGooAgent

如果你正在测试不同的引擎版本或平台，请把这份指南当作参考，而不是兼容性承诺。

你需要准备什么

  • 一个运行在 UE 5.7 上的项目
  • 已通过 Fab 安装，或已复制到 <Project>/Plugins/GrayGooAgent 的 GrayGooAgent 插件
  • 你所选 LLM 提供方的网络访问
  • 一条可用的提供方凭据路径：
  • API key，或
  • ChatGPT Plus/Pro 登录，用于 Codex 提供方路径

安装清单

1. 安装插件

可以使用以下任一方式：

  • 通过 Fab 安装到你的引擎中，然后在目标项目里启用插件
  • 将打包好的 GrayGooAgent 插件文件夹复制到 <Project>/Plugins/ 中

安装完成后，打开项目并确认 GrayGooAgent 已启用。

2. 确认 Unreal 插件依赖

为了让首次成功运行的路径尽量短，手动确认以下编辑器插件已启用：

  • Interchange
  • PythonScriptPlugin

如果其中任意一个之前是禁用状态，请在启用后重启编辑器。

GrayGooAgent 还声明了更广的能力侧编辑器依赖，用于特定工作流表面：

  • Niagara
  • PCG
  • Dataflow

这些不是首次接入的重点。把它们理解为能力依赖即可，它们在你明确使用这些工作流表面时才真正重要。如果其中某个不可用，相关动作集合可能会减少，但基础接入路径仍然有可能成功。

3. 打开面板

从下面的位置打开面板：

  • Window > GrayGooAgent

插件设置页位于：

  • Project Settings > Plugins > GrayGooAgent

你也可以在面板里的启动指南卡片中点击 Open Settings。

推荐的首次运行配置

首发阶段请把第一次配置保持得尽量简单：

  • 先配置一个提供方实例
  • 将 Default Provider Instance 和 Default Lightweight Provider Instance 都指向同一个实例
  • 除非你已经有一套稳定可用的提示词库，否则先让 Instruction Paths 保持空白
  • 除非你明确需要外部工具驱动编辑器，否则先关闭 Enable External Agent Bridge
  • 先不要碰可变更工作流，先从内置只读快速开始入手

提供方配置：最简单路径

最稳妥的接入方式，是先配置一个带明确字段的提供方实例。

首次可用配置推荐字段：

  • Instance Name：任意清晰名称，例如 Primary OpenAI
  • Provider ID：与你的端点匹配的提供方模板，例如 openai 或 openai-compatible
  • Model ID：你选定的模型，例如 gpt-5.4-mini
  • API Endpoint：该提供方的完整端点
  • Auth：你的 API key，或基于登录的凭据流程

如果你希望把变动因素压到最少，建议先使用标准 OpenAI 或 OpenAI-compatible 端点，然后在尝试其他任何内容之前，先确认启动指南已经报告提供方准备就绪。

首次成功运行

1. 启动一个新会话

打开 GrayGooAgent 面板并创建一个新会话。

启动指南卡片会检查：

  • 提供方是否就绪
  • 必需的插件依赖
  • 自定义指令路径
  • 外部桥接状态
  • 快速开始是否可用

2. 清除所有阻塞项

如果指南显示 [BLOCK]，请先修复这些项。

如果它只显示 [WARN]，核心聊天可能已经可以使用，但你仍然应该先理解警告含义再继续。

3. 运行内置快速开始

从指南卡片中使用下面任一操作：

  • Insert Quickstart
  • Run Quickstart

当当前会话已准备好时，Run Quickstart 是最快路径。

内置快速开始是刻意设计成只读的。它会要求 GrayGooAgent：

  • 报告当前活动的代理、提供方和模型
  • 列出当前关卡中的前几个 Actor
  • 说明它现在可以使用哪些只读 Unreal 动作
  • 在不做修改的前提下，建议几个安全的下一步任务

4. 成功的表现是什么

当下面这些条件都满足时，你的首次运行就算健康：

  • 面板能够正常打开
  • 启动指南没有阻塞性的提供方错误
  • Run Quickstart 可用，或者 Insert Quickstart 生成了连贯的只读响应
  • 响应能够正确识别当前提供方和模型
  • 响应能够检查真实编辑器上下文，例如当前关卡或当前 Actor

推荐的第二步

当只读快速开始成功后，再尝试一个小而具体的任务：

  • 检查一个 Blueprint
  • 按名称搜索一个资源
  • 检查当前关卡或 Actor 列表
  • 截取一张截图用于视觉验证

不要一开始就提出大范围写入请求。先确认项目上下文和提供方路径都稳定。

可选的高级设置

首次运行不需要这些，但它们可用：

  • Instruction Paths 在默认路径已经可用之后，再添加自定义提示词或指令目录。
  • Enable Python Execute Tool 启用会修改 Unreal Editor 的 Python 执行。只有在你明确想进行基于 Python 的编辑器变更时才打开它。
  • Expose Screenshot Tool To Remote Providers 面向更广泛远程工具工作流的高级选项。
  • Enable External Agent Bridge 允许外部工具通过桥接服务驱动编辑器。这个设置需要重启才能生效。

外部代理工作流路径

如果你希望外部代理通过 GrayGooAgent 驱动 Unreal Editor，推荐的配套集成路径是：

  • graygoo-unreal-bridge
  • 打包位置：GrayGooAgent 插件内的 Docs/graygoo-unreal-bridge/

这个配套 skill 是给外部代理侧使用的，用来封装：

  • 编辑器状态检查
  • 桥接就绪检查
  • 任务执行
  • 等待 / 轮询流程
  • 安全停止或重启行为

只有在正常的编辑器内快速开始已经可用之后，才使用这条路径。对于第一次外部代理成功运行，请：

  • 保持只配置一个提供方实例
  • 启用 Enable External Agent Bridge
  • 重启编辑器
  • 确认启动指南显示桥接状态健康
  • 发送一个窄范围任务，并等待完成后再复用该会话

如果你正在准备更完整的外部代理工作流，请阅读：

如果出错了怎么办

请查看：

先从与启动指南状态相匹配的部分开始：

  • Provider
  • Plugin Dependencies
  • Instructions
  • External Bridge
  • Quickstart