跳转至

GrayGooAgent 提供方与故障排查

配置理念

对于首次商业发布，支持成本最低的配置是：

  • 一个提供方实例
  • 一个已知可用的模型
  • 一个默认提供方
  • 一个新会话
  • 在任何可变更工作流之前先跑一次只读快速开始

只有在基础路径稳定后，才继续增加轻量级提供方覆盖、自定义指令路径、Python 执行或外部桥接工作流。

提供方路径

推荐首发路径：OpenAI 或 OpenAI-Compatible

这是最适合首次运行的路径，因为配置最直接：

  • 完整的 API Endpoint
  • API Key
  • Model ID

典型的提供方 ID：

  • openai
  • openai-compatible

如果你希望把接入面和排障路径都压到最小，建议使用这条路径。

ChatGPT Plus/Pro 路径：OpenAI Codex

GrayGooAgent 还内置了一个 OpenAI Codex (ChatGPT Plus/Pro) 提供方路径。

典型的提供方 ID：

  • openai-codex-chatgpt

如果你希望通过设置页里的登录流程认证，而不是输入标准 API key，那么可以使用这条路径。

说明：

  • 认证模式基于 OAuth
  • 设置 UI 为这个提供方暴露了独立的登录区域
  • 如果环境变量中存在 OPENAI_ACCESS_TOKEN，插件也可以读取它

Zhipu AI Coding Plan

GrayGooAgent 内置了一个面向 Zhipu 的提供方路径。

典型的提供方 ID：

  • zhipu-ai-coding-plan

典型的 API key 环境变量回退：

  • ZAI_API_KEY
  • ZHIPUAI_API_KEY

其他提供方模板

提供方目录里也包含一些首发默认路径之外的模板。

这些应被视为高级路径。对于首发文档和买家支持，主要推荐仍然是：

  • 先把一个 OpenAI 或 OpenAI-compatible 实例跑通

常见提供方字段

Instance Name

已配置提供方实例的人类可读名称。

建议使用稳定的名称，例如：

  • Primary OpenAI
  • Primary Codex
  • Primary Zhipu

Provider ID

用于选择提供方协议和模板行为。

示例：

  • openai
  • openai-compatible
  • openai-codex-chatgpt
  • zhipu-ai-coding-plan

Model ID

GrayGooAgent 应该通过这个提供方请求的模型。

首次运行时，请先选定一个模型，并在其余配置验证完成前保持稳定。

API Endpoint

请使用完整端点，而不是只填基础域名。

如果你使用的是 OpenAI-compatible 服务，请把这个字段指向承载所选协议的准确端点。

Auth

GrayGooAgent 会先从设置中解析凭据，然后在适用时再回退到环境变量。

有用的环境变量回退包括：

  • OPENAI_API_KEY
  • OPENAI_ACCESS_TOKEN
  • ZAI_API_KEY
  • ZHIPUAI_API_KEY

Default Provider Instance

这是当前主工作流所使用的主提供方。

首次运行时，请把它指向你刚刚验证过的同一个提供方实例。

Default Lightweight Provider Instance

这是用于较轻委派工作的回退路径。

首次运行时，请把它设成和默认提供方相同的实例，以减少变量。

推荐的提供方配方

配方 A：简单 API Key 配置

当你想要最少步骤时，使用这个方案：

  • 创建一个提供方实例
  • 将 Provider ID 设为 openai 或 openai-compatible
  • 填写 Model ID
  • 填写完整的 API Endpoint
  • 输入 API Key
  • 将两个默认提供方字段都指向同一个实例

配方 B：ChatGPT Plus/Pro 登录

当你想使用 Codex 登录路径时，使用这个方案：

  • 创建一个提供方实例
  • 将 Provider ID 设为 openai-codex-chatgpt
  • 保持选择一个受支持的 Codex 模型
  • 在设置中使用内联登录区域
  • 将默认提供方指向这个实例

配方 C：Zhipu Key 配置

当你的主路径是 Zhipu 时，使用这个方案：

  • 创建一个提供方实例
  • 将 Provider ID 设为 zhipu-ai-coding-plan
  • 选择一个受支持的 glm 模型
  • 输入 API key，或通过环境变量暴露它
  • 首次运行时，把两个默认提供方字段都指向同一个实例

按启动指南项排查

提供方

症状：

  • 启动指南把 Provider 标记为阻塞
  • Run Quickstart 变灰不可用
  • 会话无法提交第一轮

需要确认的事项：

  • Default Provider Instance 是否指向一个真实存在且已配置的实例
  • Model ID 是否为空
  • API Endpoint 是否为空
  • 选择的认证路径是否真的可用
  • 对于基于 OAuth 的 Codex 配置，账号是否已经登录

快速修复：

  • 切换到一个简单的提供方实例
  • 将两个默认提供方字段都指向同一个实例
  • 如果认证状态发生变化，请重启面板或编辑器

插件依赖

症状：

  • 启动指南提示缺少依赖
  • 基于 Python 的工作流立即失败

首次运行的手动前置条件：

  • Interchange
  • PythonScriptPlugin

GrayGooAgent 声明的附加能力侧依赖：

  • Niagara
  • PCG
  • Dataflow

它们的理解方式如下：

  • 如果缺少 Interchange 或 PythonScriptPlugin，请先修这个，因为最窄的接入路径依赖它们
  • 如果缺少 Niagara、PCG 或 Dataflow，相关工作流表面可能不可用或能力减少，但这不一定能解释一个基础提供方或快速开始失败

快速修复：

  • 启用与你正在测试的工作流相匹配的缺失插件
  • 重启编辑器
  • 重新打开 GrayGooAgent 面板

指令路径

症状：

  • 启动指南提示指令路径有问题

原因：

  • 一个或多个已配置的 Instruction Paths 已经不存在

快速修复：

  • 从 Project Settings > Plugins > GrayGooAgent 中移除失效路径
  • 或者修正这些路径，让它们指向真实存在的文件或目录

如果你暂时不需要自定义指令，空的 Instruction Paths 列表是可以接受的。

外部桥接

症状：

  • 桥接检查失败
  • 监听器没有启动
  • 启动指南显示桥接已启用但不可用

需要确认的事项：

  • 你是否真的需要这个项目使用桥接
  • 选择的端口是否空闲
  • 修改桥接设置后是否重启了编辑器
  • 已配置的默认桥接代理是否拥有有效提供方

推荐的集成路径：

  • 使用配套的 graygoo-unreal-bridge skill，而不是手写原始桥接 HTTP 调用
  • 让这个 skill 处理状态、启动、等待就绪、执行、等待、停止和重启流程
  • 在正常的编辑器内快速开始已经稳定之前，保持桥接关闭

快速修复：

  • 除非你正在主动使用它，否则关闭 Enable External Agent Bridge
  • 如果确实需要它，就更换端口并重启编辑器
  • 确认桥接默认代理能够解析到一个提供方

如果桥接本身是健康的，但你的外部代理流程仍然别扭或不稳定，请阅读：

快速开始

症状：

  • Run Quickstart 被禁用
  • 指南提示当前会话尚未准备就绪

常见原因：

  • 没有活动会话
  • 当前会话已关闭
  • 当前会话正在忙
  • 提供方尚未配置

快速修复：

  • 新建一个会话
  • 等待正在运行的 turn 完成
  • 先修复提供方问题

其他故障排查

Python 执行工具不显示

原因：

  • Enable Python Execute Tool 处于关闭状态，或者
  • PythonScriptPlugin 不可用

快速修复：

  • 启用 PythonScriptPlugin
  • 在插件设置里启用 Enable Python Execute Tool
  • 必要时重启编辑器

截图流程返回了元数据，但没有图像推理

原因：

  • 截图已经采集，但当前活动模型不支持图像输入

这意味着：

  • 工作流仍然可以使用截图元数据
  • 只有在你选择了支持图像输入的提供方 / 模型路径后，基于图像的后续推理才会发生

外部工具无法使用截图工作流

原因：

  • Expose Screenshot Tool To Remote Providers 处于关闭状态

只有在你明确希望更广泛的远程工具访问截图工作流时，才启用这个设置。

日志在哪里看

请检查：

  • <Project>/Saved/Logs/UnrealEditor.log