Skip to content

GrayGooAgent Providers and Troubleshooting

Setup Philosophy

For the first commercial release, the lowest-support-cost setup is:

  • one provider instance
  • one known-good model
  • one default provider
  • one fresh session
  • one read-only quickstart before any mutating workflow

Only add lightweight provider overrides, custom instruction paths, Python execution, or external bridge workflows after the basic path is stable.

Provider Paths

This is the best first-run path because the configuration is direct:

  • full API Endpoint
  • API Key
  • Model ID

Typical provider ids:

  • openai
  • openai-compatible

Use this path if you want the smallest onboarding surface and the clearest troubleshooting path.

ChatGPT Plus/Pro Path: OpenAI Codex

GrayGooAgent also includes a built-in OpenAI Codex (ChatGPT Plus/Pro) provider path.

Typical provider id:

  • openai-codex-chatgpt

Use this path if you want to authenticate through the in-settings login flow rather than entering a standard API key.

Notes:

  • auth mode is OAuth-based
  • the settings UI exposes a dedicated login section for this provider
  • the plugin can also read OPENAI_ACCESS_TOKEN from environment variables if present

Zhipu AI Coding Plan

GrayGooAgent includes a built-in provider path for Zhipu.

Typical provider id:

  • zhipu-ai-coding-plan

Typical API key environment variable fallback:

  • ZAI_API_KEY
  • ZHIPUAI_API_KEY

Other Provider Templates

The provider catalog also includes additional templates beyond the launch-default paths.

Treat those as advanced paths. For launch documentation and buyer support, the primary recommendation should remain:

  • get one OpenAI or OpenAI-compatible instance working first

Common Provider Fields

Instance Name

Human-readable name for the configured provider instance.

Use stable names such as:

  • Primary OpenAI
  • Primary Codex
  • Primary Zhipu

Provider ID

Selects the provider protocol and template behavior.

Examples:

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

Model ID

The model GrayGooAgent should request through that provider.

For first run, choose one model and keep it stable until the rest of the setup is proven.

API Endpoint

Use the full endpoint, not just the base domain.

If you are using an OpenAI-compatible service, point this field to the exact endpoint that serves the selected protocol.

Auth

GrayGooAgent resolves credentials from settings first and then falls back to environment variables when applicable.

Useful environment variable fallbacks:

  • OPENAI_API_KEY
  • OPENAI_ACCESS_TOKEN
  • ZAI_API_KEY
  • ZHIPUAI_API_KEY

Default Provider Instance

This is the main provider used by the active primary workflow.

For the first run, point this at the same provider instance you just verified.

Default Lightweight Provider Instance

This is the fallback path for lighter delegated work.

For the first run, set it to the same instance as the default provider to reduce moving parts.

Recipe A: Simple API Key Setup

Use this when you want the fewest steps:

  • create one provider instance
  • set Provider ID to openai or openai-compatible
  • fill Model ID
  • fill the full API Endpoint
  • enter an API Key
  • point both default provider fields at this same instance

Recipe B: ChatGPT Plus/Pro Login

Use this when you want the Codex login path:

  • create one provider instance
  • set Provider ID to openai-codex-chatgpt
  • keep a supported Codex model selected
  • use the inline login section in settings
  • point the default provider to this instance

Recipe C: Zhipu Key Setup

Use this when your primary path is Zhipu:

  • create one provider instance
  • set Provider ID to zhipu-ai-coding-plan
  • set a supported glm model
  • enter the API key or expose it through environment variables
  • point both default provider fields to this same instance for first run

Troubleshooting by Startup Guide Check

Provider

Symptoms:

  • the startup guide shows Provider as blocked
  • Run Quickstart is disabled
  • the session cannot submit a first turn

Things to verify:

  • Default Provider Instance points to a real configured instance
  • Model ID is not empty
  • API Endpoint is not empty
  • the selected auth path is actually usable
  • for OAuth-based Codex setup, the account is logged in

Fast fix:

  • switch to one simple provider instance
  • point both default provider fields to that same instance
  • restart the panel or the editor if auth state changed

Plugin Dependencies

Symptoms:

  • startup guide warns that dependencies are missing
  • Python-backed workflows fail immediately

Manual first-run prerequisites:

  • Interchange
  • PythonScriptPlugin

Additional capability-side dependencies declared by GrayGooAgent:

  • Niagara
  • PCG
  • Dataflow

How to interpret them:

  • if Interchange or PythonScriptPlugin is missing, fix that first because the narrow onboarding path depends on them
  • if Niagara, PCG, or Dataflow is missing, the related workflow surfaces may be unavailable or reduced, but that does not necessarily explain a basic provider or quickstart failure

Fast fix:

  • enable the missing plugins that match the workflow you are testing
  • restart the editor
  • reopen the GrayGooAgent panel

Instructions

Symptoms:

  • startup guide warns about instruction paths

Cause:

  • one or more configured Instruction Paths do not exist anymore

Fast fix:

  • remove stale paths from Project Settings > Plugins > GrayGooAgent
  • or correct the paths so they point to real files or directories

If you do not need custom instructions yet, an empty Instruction Paths list is fine.

External Bridge

Symptoms:

  • bridge check fails
  • listener does not start
  • startup guide says the bridge is enabled but unavailable

What to verify:

  • whether you actually need the bridge for this project
  • whether the selected port is free
  • whether the editor was restarted after changing bridge settings
  • whether the configured default bridge agent has a valid provider

Recommended integration path:

  • use the companion graygoo-unreal-bridge skill instead of hand-writing raw bridge HTTP calls
  • let that skill handle status, start, wait-ready, execute, wait, stop, and restart flow
  • keep the bridge disabled until the normal in-editor quickstart path is already stable

Fast fix:

  • disable Enable External Agent Bridge unless you actively need it
  • if you do need it, change the port and restart the editor
  • confirm the bridge default agent can resolve a provider

If the bridge itself is healthy but your outside agent flow is still awkward or unreliable, read:

Quickstart

Symptoms:

  • Run Quickstart is disabled
  • the guide says the current session is not ready

Common causes:

  • no active session
  • current session is closed
  • current session is busy
  • provider is not configured yet

Fast fix:

  • create a fresh session
  • wait for any running turn to finish
  • fix the provider issue first

Additional Troubleshooting

Python Execute Tool Does Not Appear

Cause:

  • Enable Python Execute Tool is off, or
  • PythonScriptPlugin is unavailable

Fast fix:

  • enable PythonScriptPlugin
  • enable Enable Python Execute Tool in plugin settings
  • restart the editor if needed

Screenshot Flow Returns Metadata But No Image Reasoning

Cause:

  • the screenshot was captured, but the active model does not support image input

What this means:

  • the workflow can still use screenshot metadata
  • image-grounded follow-up reasoning will not happen until you choose a provider/model path with image input support

External Tools Cannot Use Screenshot Workflows

Cause:

  • Expose Screenshot Tool To Remote Providers is off

Use this setting only when you intentionally want broader remote-tool access to the screenshot workflow.

Where To Look For Logs

Check:

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

When reporting an issue, include:

  • engine version
  • plugin version
  • provider type
  • model id
  • a screenshot of the startup guide state
  • the relevant log lines around the failure

If you still need help after checking this guide, continue with:

  • Docs/FAQ.md
  • Docs/Support.md