OpenAI Codex - Automagik Suite Documentation

Overview

OpenAI’s GPT-4 and GPT-3.5 models are reliable, well-documented AI coding assistants. Known for consistency, strong general-purpose capabilities, and excellent documentation generation.

GPT-4 Turbo offers the best balance of performance and cost for most coding tasks.

Quick Start

Get API Key

Go to platform.openai.com
Sign up or log in
Navigate to API Keys
Click Create new secret key
Copy your API key (starts with sk-)

Add Credits

OpenAI requires prepaid credits:

Go to Billing → Add payment method
Add credit card
Purchase credits ($5+ recommended)

Configure Forge

Edit .forge/config.json:

{
  "llms": {
    "openai": {
      "apiKey": "sk-...",
      "model": "gpt-4-turbo"
    }
  }
}

Test Connection

forge task create \
  --title "Test GPT-4" \
  --description "Print 'Hello from OpenAI!'" \
  --llm openai

Available Models

GPT-4 Family

gpt-4-turbo

model

Best overall GPT-4 model

Context: 128K tokens
Speed: Fast
Cost: $10/MTok input,$ 30/MTok output
Best for: Complex coding tasks

{
  "llms": {
    "openai": {
      "model": "gpt-4-turbo"
    }
  }
}

gpt-4

model

Original GPT-4 (legacy)

Context: 8K tokens
Speed: Slower
Cost: $30/MTok input,$ 60/MTok output
Best for: Nothing (use Turbo instead)

Use gpt-4-turbo instead - faster and cheaper!

GPT-3.5 Family

gpt-3.5-turbo

model

Fast and affordable

Context: 16K tokens
Speed: Very fast
Cost: $0.50/MTok input,$ 1.50/MTok output
Best for: Simple tasks, quick fixes

{
  "llms": {
    "openai-cheap": {
      "apiKey": "sk-...",
      "model": "gpt-3.5-turbo"
    }
  }
}

Model Comparison

Model	Context	Speed	Cost	Quality
GPT-4 Turbo	128K	⭐⭐⭐⭐	$$$	⭐⭐⭐⭐
GPT-4	8K	⭐⭐	$$$$	⭐⭐⭐⭐
GPT-3.5 Turbo	16K	⭐⭐⭐⭐⭐	$	⭐⭐⭐

Recommendation: Use GPT-4 Turbo for most tasks, GPT-3.5 Turbo for simple fixes.

Configuration

Basic Setup

{
  "llms": {
    "openai": {
      "apiKey": "sk-...",
      "model": "gpt-4-turbo"
    }
  }
}

Advanced Configuration

{
  "llms": {
    "openai": {
      "apiKey": "sk-...",
      "model": "gpt-4-turbo",
      "organization": "org-...",  // Optional
      "maxTokens": 4096,
      "temperature": 0.7,
      "topP": 1,
      "frequencyPenalty": 0,
      "presencePenalty": 0,
      "timeout": 60000,
      "retries": 3
    }
  }
}

organization

string

Your OpenAI organization ID (for enterprise accounts)

maxTokens

number

default:"4096"

Maximum tokens in response (1-4096)

temperature

number

default:"1.0"

Randomness (0-2)

0 = Deterministic
1 = Balanced
2 = Creative

OpenAI’s Strengths

Consistency

GPT-4 produces reliable, consistent results:

# Same task multiple times = similar results
forge task create "Add validation" --llm openai

# More predictable than Claude/Gemini

General Purpose

Good at everything, great at nothing:

# Works well for:
- Backend APIs
- Frontend components
- Data processing
- Testing
- Documentation

Documentation

Excellent at writing clear documentation:

forge task create \
  --title "Document authentication flow" \
  --description "
  Create comprehensive documentation for:
  - How JWT tokens work
  - Login/signup flow
  - Password reset process
  - Include code examples
  " \
  --llm openai

Result: Clear, well-structured docs with examples.

Large Ecosystem

Most tools integrate with OpenAI:

Extensive docs
Large community
Many examples
Well-tested

OpenAI’s Weaknesses

Expensive

GPT-4 is one of the most expensive options:

Cost comparison (10K input + 2K output):
- GPT-4 Turbo:  $0.16
- Claude Sonnet: $0.06  (2.6x cheaper)
- Gemini Flash:  $0.00  (free!)

Not Exceptional

Jack of all trades, master of none:

Claude better at reasoning
Gemini faster and cheaper
Cursor better at UI

Requires Prepaid Credits

Can’t pay-as-you-go:

Must purchase credits upfront
Minimum $5
Credits expire (usually 1 year)

Pricing

Per-Token Costs

Model	Input	Output	Example
GPT-4 Turbo	$10/MTok	$30/MTok	10K in + 2K out = $0.16
GPT-4	$30/MTok	$60/MTok	10K in + 2K out = $0.48
GPT-3.5 Turbo	$0.50/MTok	$1.50/MTok	10K in + 2K out = $0.008

Prepaid Credits

Minimum purchase: $5
Recommended: $20-50 for hobby projects
Credits expire after 1 year

Best Use Cases

Documentation

forge task create \
  --title "Write API documentation" \
  --description "
  Document all endpoints in src/api/
  Include:
  - Request/response examples
  - Error codes
  - Authentication requirements
  " \
  --llm openai

General Coding

forge task create \
  --title "Implement user CRUD endpoints" \
  --llm openai

Testing

forge task create \
  --title "Add unit tests for auth service" \
  --description "Aim for 90%+ coverage" \
  --llm openai

Consistency-Critical Tasks

When you need predictable results:

forge task create \
  --title "Generate migration scripts" \
  --llm openai  # Consistent output important

Integration with Forge

Using in Tasks

# Basic usage
forge task create "Add feature" --llm openai

# Specify model
forge task create "Quick fix" --llm openai-cheap  # GPT-3.5

# With organization
forge task create "Enterprise task" --llm openai \
  --org org-your-org-id

Multiple OpenAI Configs

Configure both GPT-4 and GPT-3.5:

{
  "llms": {
    "openai": {
      "apiKey": "sk-...",
      "model": "gpt-4-turbo"
    },
    "openai-cheap": {
      "apiKey": "sk-...",
      "model": "gpt-3.5-turbo"
    }
  }
}

Use appropriately:

# Complex task → GPT-4
forge task create "Design system architecture" --llm openai

# Simple task → GPT-3.5
forge task create "Add console.log" --llm openai-cheap

Cost Optimization

Use GPT-3.5 for Simple Tasks

# Simple tasks (20x cheaper)
forge task create "Fix typo" --llm openai-cheap
forge task create "Add comment" --llm openai-cheap

# Complex tasks
forge task create "Refactor architecture" --llm openai

Reduce Context

# Send less context
forge task create "Fix bug in login.ts" \
  --files "src/auth/login.ts" \  # Only this file
  --llm openai

Lower Max Tokens

{
  "llms": {
    "openai": {
      "maxTokens": 2048  // Instead of 4096
    }
  }
}

Monitor Spending

# Check costs
forge cost summary --month january

# Set budget alerts
forge config set budget.monthly 50  # $50/month
forge config set budget.alert true

Troubleshooting

401 Invalid API Key

Error: “Incorrect API key provided”Solutions:

Verify API key from platform.openai.com
Check for extra spaces
Ensure key hasn’t been deleted
Generate new key

429 Rate Limit

Error: “Rate limit reached”Solutions:

Wait a few seconds
Reduce concurrent requests
Upgrade tier (Tier 1 → Tier 2)
Use exponential backoff

Insufficient Credits

Error: “You exceeded your current quota”Solutions:

Add more credits: platform.openai.com/billing
Check billing dashboard
Verify payment method

Slow responses

Issue: GPT-4 taking too longSolutions:

Use GPT-4 Turbo (not regular GPT-4)
Use GPT-3.5 for simple tasks
Reduce maxTokens
Check OpenAI status page

Context length error

Error: “This model’s maximum context length is…”Solutions:

Use GPT-4 Turbo (128K context)
Reduce input context
Split task into smaller pieces

Rate Limits

By Tier

Tier	RPM	TPM	How to Reach
Free	3	40K	New account
Tier 1	500	30K	$5+ paid
Tier 2	5000	450K	$50+ paid + 7 days
Tier 3	10000	1M	$1000+ paid + 7 days

RPM = Requests per minute TPM = Tokens per minute Check your tier: platform.openai.com/account/limits

Best Practices

Use GPT-3.5 for Simple Tasks

# 20x cheaper!
forge task create "Quick fix" --llm openai-cheap

Reserve GPT-4 for complex work

Monitor Usage

# Check OpenAI dashboard
open https://platform.openai.com/usage

# Track in Forge
forge cost summary

Set Budget Alerts

On OpenAI dashboard:

Set hard limit ($50/month)
Email alerts at 75%, 90%

Use for Documentation

GPT-4 excels at docs:

forge task create "Document code" --llm openai

OpenAI vs Other Agents

Feature	OpenAI	Claude	Gemini	Cursor
Quality	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐
Cost	$$$$	$$$	$	Subscription
Speed	⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐
Context	128K	200K	2M	Variable
Consistency	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐

Choose OpenAI for: Documentation, consistency, general purpose Choose Claude for: Complex reasoning, architecture Choose Gemini for: Speed, cost, large context Choose Cursor for: UI/UX, frontend

Real-World Examples

Example 1: API Documentation

forge task create \
  --title "Document REST API" \
  --description "
  Create OpenAPI spec for all endpoints in src/api/
  Include examples and error codes
  " \
  --llm openai

# Time: ~5 minutes
# Cost: ~$0.25
# Quality: Excellent, comprehensive

Example 2: Test Generation

forge task create \
  --title "Add tests for user service" \
  --description "Unit tests with 90%+ coverage" \
  --llm openai

# Time: ~4 minutes
# Cost: ~$0.18
# Result: 95% coverage achieved

Next Steps

Get Started

Create your first GPT-4 task

Other Agents

Compare with other AI agents

Cost Optimization

Reduce OpenAI spending

OpenAI Platform

Manage your API keys and billing

Getting Started

Learn

Configuration

Reference

Troubleshooting

​Overview

​Quick Start

​Available Models

​GPT-4 Family

​GPT-3.5 Family

​Model Comparison

​Configuration

​Basic Setup

​Advanced Configuration

​OpenAI’s Strengths

​Consistency

​General Purpose

​Documentation

​Large Ecosystem

​OpenAI’s Weaknesses

​Expensive

​Not Exceptional

​Requires Prepaid Credits

​Pricing

​Per-Token Costs

​Prepaid Credits

​Best Use Cases

​Documentation

​General Coding

​Testing

​Consistency-Critical Tasks

​Integration with Forge

​Using in Tasks

​Multiple OpenAI Configs

​Cost Optimization

​Use GPT-3.5 for Simple Tasks

​Reduce Context

​Lower Max Tokens

​Monitor Spending

​Troubleshooting

​Rate Limits

​By Tier

​Best Practices

Use GPT-3.5 for Simple Tasks

Monitor Usage

Set Budget Alerts

Use for Documentation

​OpenAI vs Other Agents

​Real-World Examples

​Example 1: API Documentation

​Example 2: Test Generation

​Next Steps

Get Started

Other Agents

Cost Optimization

OpenAI Platform

Overview

Quick Start

Available Models

GPT-4 Family

GPT-3.5 Family

Model Comparison

Configuration

Basic Setup

Advanced Configuration

OpenAI’s Strengths

Consistency

General Purpose

Documentation

Large Ecosystem

OpenAI’s Weaknesses

Expensive

Not Exceptional

Requires Prepaid Credits

Pricing

Per-Token Costs

Prepaid Credits

Best Use Cases

Documentation

General Coding

Testing

Consistency-Critical Tasks

Integration with Forge

Using in Tasks

Multiple OpenAI Configs

Cost Optimization

Use GPT-3.5 for Simple Tasks

Reduce Context

Lower Max Tokens

Monitor Spending

Troubleshooting

Rate Limits

By Tier

Best Practices

OpenAI vs Other Agents

Real-World Examples

Example 1: API Documentation

Example 2: Test Generation

Next Steps