Skip to content

openai.md

Latest commit

 

History

History
197 lines (147 loc) · 6.18 KB

openai.md

File metadata and controls

197 lines (147 loc) · 6.18 KB

OpenAI

Connect GoClaw to OpenAI's GPT-4o and o-series reasoning models using the standard OpenAI API.

Overview

GoClaw uses a generic OpenAI-compatible provider (OpenAIProvider) for all OpenAI API requests. It supports both regular chat models (GPT-4o, GPT-4o-mini) and o-series reasoning models (o1, o3, o4-mini) that use reasoning_effort instead of temperature. Streaming uses SSE and includes usage stats in the final chunk via stream_options.include_usage.

Prerequisites

config.json Setup

{
  "providers": {
    "openai": {
      "api_key": "sk-..."
    }
  }
}

The default base URL is https://api.openai.com/v1. To use a custom endpoint (e.g. a local proxy):

{
  "providers": {
    "openai": {
      "api_key": "sk-...",
      "api_base": "https://your-proxy.example.com/v1"
    }
  }
}

Dashboard Setup

Go to Settings → Providers → OpenAI in the dashboard and enter your API key. Keys are encrypted with AES-256-GCM at rest.

Supported Models

Model Context Window Notes
gpt-4o 128k tokens Best multimodal model, supports vision
gpt-4o-mini 128k tokens Faster and cheaper than gpt-4o
o4-mini 200k tokens Fast reasoning model
o3 200k tokens Advanced reasoning
o1 200k tokens Original reasoning model
o1-mini 128k tokens Smaller reasoning model

Reasoning API

GoClaw supports a two-level reasoning configuration: provider-level defaults that apply to all agents, and per-agent overrides. This applies to o-series and GPT-5/Codex models.

Provider-Level Defaults

Set reusable reasoning defaults on the provider itself using settings.reasoning_defaults. Every agent that uses this provider inherits these defaults automatically:

{
  "name": "openai",
  "provider_type": "openai",
  "settings": {
    "reasoning_defaults": {
      "effort": "high",
      "fallback": "downgrade"
    }
  }
}

If no reasoning_defaults is configured on the provider, inherit resolves to reasoning off.

Agent-Level Overrides

Agents can override or inherit the provider default using reasoning.override_mode in other_config:

{
  "provider": "openai",
  "other_config": {
    "reasoning": {
      "override_mode": "inherit"
    }
  }
}
{
  "provider": "openai",
  "other_config": {
    "reasoning": {
      "override_mode": "custom",
      "effort": "medium",
      "fallback": "off"
    }
  }
}
override_mode Behavior
inherit Uses the provider's reasoning_defaults
custom Uses the agent's own reasoning policy

Agents without override_mode behave as custom (backward compatible).

Effort Levels and Fallback Policy

Valid effort levels: off, auto, none, minimal, low, medium, high, xhigh.

Valid fallback values when the requested effort is not supported by the model:

fallback Behavior
downgrade (default) Uses the highest supported level below the requested level
off Disables reasoning entirely
provider_default Falls back to the model's default effort

GPT-5 and Codex Effort Normalization

For known GPT-5 and Codex models, GoClaw validates and normalizes effort before sending the request. This avoids API errors when the requested level is not supported by that model variant:

Model Supported Levels Default
gpt-5 minimal, low, medium, high medium
gpt-5.1 none, low, medium, high none
gpt-5.1-codex low, medium, high medium
gpt-5.2 none, low, medium, high, xhigh none
gpt-5.2-codex low, medium, high, xhigh medium
gpt-5.3-codex low, medium, high, xhigh medium
gpt-5.4 none, low, medium, high, xhigh none
gpt-5-mini / gpt-5.4-mini none, low, medium, high, xhigh none

For unknown models (e.g. new releases), the requested effort is passed through as-is. Trace metadata exposes the resolved source and effective_effort so you can see what was actually sent.

Legacy thinking_level (Backward Compat)

The earlier options.thinking_level key still works as a shorthand for the reasoning API:

{
  "options": {
    "thinking_level": "high"
  }
}

This is a shim — GoClaw maps it to reasoning_effort internally. New configurations should use reasoning.override_mode with effort instead. Reasoning token usage is tracked in Usage.ThinkingTokens from completion_tokens_details.reasoning_tokens.

Vision

GPT-4o supports image input. Send images as base64 in the images field of a message. GoClaw converts them to the OpenAI image_url content block format automatically:

{
  "role": "user",
  "content": "What's in this image?",
  "images": [
    {
      "mime_type": "image/jpeg",
      "data": "<base64-encoded-bytes>"
    }
  ]
}

Tool Use

OpenAI function calling works out of the box. GoClaw converts internal tool definitions to the OpenAI wire format (with type: "function" wrapper and arguments serialized as a JSON string) before sending.

Common Issues

Issue Cause Fix
HTTP 401 Invalid API key Verify key at platform.openai.com
HTTP 429 Rate limit GoClaw retries automatically; check your tier limits
HTTP 400 on o-series Unsupported parameter Avoid setting temperature with o-series models
Vision not working Model doesn't support images Use gpt-4o or gpt-4o-mini

Developer Role (GPT-4o+)

For native OpenAI endpoints (api.openai.com), GoClaw automatically maps the system role to developer when sending requests. The developer role has higher instruction priority than system for GPT-4o and newer models.

This mapping only applies to native OpenAI infrastructure. Other OpenAI-compatible backends (Azure OpenAI, proxies, Qwen, DeepSeek, etc.) continue to use the standard system role.

What's Next

  • OpenRouter — access 100+ models through one API key
  • Anthropic — native Claude integration
  • Overview — provider architecture and retry logic