# How to Configure AI Engines (Copilot, Claude, Codex, Custom) in GitHub Agentic Workflows > Learn to configure AI engines like Copilot, Claude, and Codex in GitHub Agentic Workflows. Set the engine field in your YAML for seamless integration and enhanced automation. - Repository: [GitHub/gh-aw](https://github.com/github/gh-aw) - Tags: how-to-guide - Published: 2026-02-16 --- **Configure AI engines in GitHub Agentic Workflows by setting the `engine` field in your workflow's YAML front-matter, using either a simple scalar (`engine: copilot`) or an expanded map with engine-specific options like `model`, `args`, and `agent`.** GitHub Agentic Workflows (`gh-aw`) is an open-source framework that lets you orchestrate coding tasks using natural language prompts. When you configure AI engines in GitHub Agentic Workflows, you select which large language model or agent interprets these prompts—whether that is GitHub Copilot, Anthropic Claude, OpenAI Codex, or a custom binary. ## Supported AI Engines in gh-aw The `gh-aw` CLI supports four primary engine identifiers, each mapped to a specific coding agent: - **`copilot`** — The default GitHub Copilot CLI agent, hosted by GitHub and optimized for general coding tasks. - **`claude`** — Anthropic's Claude models, selected for complex reasoning and higher token limits. - **`codex`** — OpenAI's Codex models, useful for legacy codebases or specific OpenAI-compatible integrations. - **`custom`** — Any external agent binary or custom Copilot agent file located in `.github/agents/`. According to the source code in [`pkg/workflow/engine_validation.go`](https://github.com/github/gh-aw/blob/main/pkg/workflow/engine_validation.go), the validation layer checks the `engine` field against this allowed set and rejects invalid values with a descriptive error message. ## Configuring the Engine in Workflow Front-Matter Workflow files in `gh-aw` are Markdown files with YAML front-matter. You declare the AI engine at the top of the file using either a simple scalar or an expanded configuration map. ### Simple Scalar Form For most use cases, specify the engine as a single string value: ```yaml --- engine: copilot --- ``` This format is documented in [`docs/src/content/docs/reference/engines.md`](https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/engines.md) at lines 24-26. When you use the scalar form, `gh-aw` applies default settings for the selected engine, including the latest stable model version and standard CLI arguments. ### Expanded Map Form For advanced configuration—such as pinning a specific model version, passing custom CLI arguments, or referencing a custom agent file—use the expanded map syntax: ```yaml --- engine: id: claude version: latest model: claude-sonnet-3.5 args: ["--add-dir", "/workspace"] agent: my-custom-agent --- ``` As shown in the reference documentation at lines 84-91, the `id` field is required and must match one of the supported engine identifiers. The `args` array allows you to pass arbitrary flags to the underlying agent binary, while the `agent` field specifies a custom agent file located in `.github/agents/`. ## Engine-Specific Configuration and Secrets Each AI engine requires specific authentication tokens and environment variables. The `gh-aw` CLI reads these from your environment or GitHub Secrets at runtime. ### Copilot CLI Configuration To use the Copilot engine, you must authenticate with GitHub and possess a Personal Access Token (PAT) with the `copilot-requests` scope. Export this token as `COPILOT_GITHUB_TOKEN`: ```bash export COPILOT_GITHUB_TOKEN=ghp_xxxxxxxxxxxx ``` The Copilot-specific documentation in [`docs/src/content/docs/reference/engines.md`](https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/engines.md) (lines 22-26) notes that this engine is the default and requires no additional configuration if the token is present in the environment. ### Claude (Anthropic) Setup For the Claude engine, provide your Anthropic API key via the `ANTHROPIC_API_KEY` environment variable: ```bash export ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxx ``` As documented at lines 54-60, you can optionally specify the model version in the expanded engine map (e.g., `model: claude-opus-4`) to override the default `claude-sonnet-3.5`. ### OpenAI Codex Setup The Codex engine requires an OpenAI API key exported as `OPENAI_API_KEY`: ```bash export OPENAI_API_KEY=sk-xxxxxxxxxxxx ``` According to the reference at lines 72-78, the Codex engine supports legacy OpenAI models. You may need to specify an older model identifier in the `model` field if your workflow targets specific legacy behavior. ### Custom Agent Configuration Custom engines allow you to integrate third-party agents or specialized Copilot agents. To configure a custom engine, place your agent definition file in `.github/agents/` and reference it in the `agent` field: ```yaml --- engine: id: custom agent: technical-doc-writer --- ``` The `technical-doc-writer` file must exist at `.github/agents/technical-doc-writer.copilot`. As noted at lines 95-100, the `id` field can be `custom` or any string that maps to your external binary, provided the binary is available in the system PATH. ## Validation and Error Handling The `gh-aw` CLI validates engine configuration before executing workflows. The validation logic resides in [`pkg/workflow/engine_validation.go`](https://github.com/github/gh-aw/blob/main/pkg/workflow/engine_validation.go), which checks that the `engine` identifier matches one of the allowed values: `copilot`, `claude`, `codex`, or `custom`. If you provide an invalid engine identifier, the CLI returns a structured error message: ``` invalid engine: . Valid engines are: copilot, claude, codex, custom. Example: engine: copilot ``` This error generation occurs at lines 82-89 of [`pkg/workflow/engine_validation.go`](https://github.com/github/gh-aw/blob/main/pkg/workflow/engine_validation.go). Additionally, the JSON schema definition in [`pkg/workflow/schema_validation.go`](https://github.com/github/gh-aw/blob/main/pkg/workflow/schema_validation.go) (line 162) enumerates the valid engine strings, ensuring that validation occurs both at the schema level and in the Go validation logic. ## Complete Configuration Examples ### Example 1: Basic Copilot Workflow ```markdown --- engine: copilot --- # Refactor Python Functions Please refactor the following Python code to use list comprehensions instead of for-loops. ``` ### Example 2: Claude with Specific Model and Arguments ```markdown --- engine: id: claude model: claude-opus-4 args: ["--thinking", "enabled"] --- # Complex Architecture Review Analyze the microservice architecture described below and identify potential failure points. ``` ### Example 3: Custom Agent for Documentation ```markdown --- engine: id: custom agent: technical-doc-writer --- # Generate API Documentation Create comprehensive API documentation for the following endpoints. ``` ## Summary - **Engine selection** in `gh-aw` is controlled by the `engine` field in workflow front-matter, supporting `copilot`, `claude`, `codex`, and `custom`. - **Simple configuration** uses scalar values (`engine: claude`), while **advanced configuration** uses expanded maps with `id`, `model`, `args`, and `agent` fields. - **Authentication** requires environment-specific API keys: `COPILOT_GITHUB_TOKEN` for Copilot, `ANTHROPIC_API_KEY` for Claude, and `OPENAI_API_KEY` for Codex. - **Custom agents** reside in `.github/agents/` and are referenced via the `agent` field in the engine configuration. - **Validation** occurs in [`pkg/workflow/engine_validation.go`](https://github.com/github/gh-aw/blob/main/pkg/workflow/engine_validation.go), which enforces allowed engine identifiers and provides helpful error messages for invalid configurations. ## Frequently Asked Questions ### How do I switch between Copilot and Claude in different workflows? You specify the engine individually in each workflow file's front-matter. One workflow can use `engine: copilot` while another uses `engine: claude` or the expanded form with `id: claude`. The `gh-aw` CLI reads the configuration per-file during compilation, allowing you to mix engines across your workflow suite. ### What is the difference between the `custom` engine and the `agent` field? The `custom` engine identifier tells `gh-aw` to use an external agent binary not natively integrated into the CLI. The `agent` field, used with either `copilot` or `custom` engines, points to a specific agent definition file located in `.github/agents/`. For Copilot, this loads a custom Copilot agent; for custom engines, it may specify configuration for your external binary. ### Why does my workflow fail with "invalid engine" error? This error originates from [`pkg/workflow/engine_validation.go`](https://github.com/github/gh-aw/blob/main/pkg/workflow/engine_validation.go) when the `engine` field contains a value not in the allowed set: `copilot`, `claude`, `codex`, or `custom`. Check your front-matter for typos, ensure the value is lowercase, and verify you are using the expanded map syntax correctly if specifying additional fields like `model` or `args`. ### Can I pass custom CLI arguments to the AI engine? Yes. Use the expanded map form of the engine configuration and include the `args` array. For example, `args: ["--add-dir", "/workspace"]` passes those flags to the underlying agent binary when the workflow executes. This works for all supported engines including custom external agents.