跳转至

GrayGooAgent 安装与快速开始

适用范围

本页聚焦于当前已验证环境下的首次安装与首次运行验证流程。

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

如果你使用的是其他引擎版本或平台，本页仍可作为参考，但不应视为兼容性保证。

前置条件

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

安装清单

1. 安装插件

可以使用以下任一方式：

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

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

2. 确认 Unreal 插件依赖

为减少初次接入中的环境问题，建议先确认以下两个编辑器插件已启用：

  • Interchange
  • PythonScriptPlugin

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

另外还有几项编辑器依赖，只有在对应功能里才会用到：

  • 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
  • 暂不启用可变更工作流，先从内置只读快速开始入手

提供方配置：优先采用最简方案

首次接入建议先配置一个最直接、变量最少的 provider 实例。

先把这些字段填好：

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

建议首次接入优先使用标准 OpenAI 或 OpenAI-compatible 端点，并先确认启动指南已将 provider 识别为可用，再扩展到其他配置方案。

一个最小可用示例：

Instance Name: Primary OpenAI
Provider ID: openai
Model ID: gpt-5.4-mini
API Endpoint: https://api.openai.com/v1/responses
Auth: OPENAI_API_KEY 或直接填写 API key
Default Provider Instance: Primary OpenAI
Default Lightweight Provider Instance: Primary OpenAI

首次运行验证

1. 启动一个新会话

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

启动指南会检查以下内容：

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

2. 清除所有阻塞项

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

如果仅剩 [WARN]，通常已具备继续验证的条件，但建议先确认警告项的具体含义，再继续后续步骤。

3. 运行内置快速开始

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

  • Insert Quickstart
  • Run Quickstart

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

内置快速开始默认是只读的。它会让 GrayGooAgent：

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

4. 验证通过的判据

满足以下条件时，可视为首次验证已经通过：

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

推荐的后续步骤

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

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

首次验证阶段不建议直接提交大范围写入请求。请先确认项目上下文和提供方路径均已稳定。

完成首次验证后再查看

只有在 quickstart 已经稳定后，再继续到下面这些内容：

  • 自定义指令路径
  • 基于 Python 的可变更工作流
  • 轻量 provider 专门配置
  • 外部代理桥接

这些功能均可用，但不属于首次验证的必需项。待基础流程稳定后，再继续查看：

如果出现错误

请查看：

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

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

如果你准备提交支持请求，请同时参考支持。