Models and agents

Raw separates two things in config.json:

• Models (models) describe how to reach an upstream model.
• Agents (agents) choose one model and define how a run behaves.

Several agents can share one model. Changing an agent never changes the model connection, and changing a model affects every agent that uses it.

Configure a model

Each entry under models is a connection. The key is a local alias that agents use.

Field	Required	Purpose
provider	Yes	The service or deployment, such as ollama, deepseek, openai or a custom gateway name.
method	Yes	The wire API. See the table below. Raw never infers it from the provider or model name.
model_id	Yes	The exact model ID sent to the service.
base_url	Sometimes	The endpoint. Required for a custom service, and for any pair other than the official provider and method.
api_key or api_key_env	No	A literal key, or the name of an environment variable that holds the key. You cannot set both.
context_window_tokens	No	The model’s context size, a positive integer. Used for context percentages and automatic compaction.
max_output_tokens	No	A positive integer. Must be smaller than context_window_tokens when both are set.
vision	No	true if the model accepts images. Defaults to false.

Wire methods

The method field selects the API that Raw calls.

Method	Typical service	Output cap field
openai-chat-completions	OpenAI, DeepSeek, OpenRouter, Ollama, compatible gateways	max_completion_tokens for OpenAI, max_tokens for other services
openai-responses	OpenAI	max_output_tokens
anthropic-messages	Anthropic or a compatible gateway	max_tokens
google-generate-content	Gemini or a compatible gateway	maxOutputTokens

Official endpoint defaults apply only when the provider and method form the matching pair. For anything else, set base_url explicitly, so Raw never sends a credential to the default endpoint of a different service.

Credentials

Raw reads credentials for the selected model only. These environment variables are used by default for known services:

• OPENAI_API_KEY
• ANTHROPIC_API_KEY
• GEMINI_API_KEY or GOOGLE_API_KEY
• OPENROUTER_API_KEY

A local Ollama endpoint needs no key. A custom service needs an explicit base_url, and a key source if the endpoint requires authentication. Prefer api_key_env over a literal api_key, so the key stays out of the file.

raw config list shows model and access settings without printing keys.

Example: a local model and a hosted model

{
  "default_agent": "raw",
  "models": {
    "local": {
      "provider": "ollama",
      "method": "openai-chat-completions",
      "model_id": "YOUR_INSTALLED_MODEL",
      "base_url": "http://127.0.0.1:11434/v1"
    },
    "flash": {
      "provider": "deepseek",
      "method": "openai-chat-completions",
      "model_id": "deepseek-flash",
      "base_url": "https://api.deepseek.com",
      "api_key_env": "DEEPSEEK_API_KEY",
      "context_window_tokens": 1048576
    }
  },
  "agents": {
    "raw": {
      "model": "local",
      "tools": { "use": ["builtin/read_file", "builtin/write_file", "builtin/bash"] }
    },
    "deepseek": {
      "model": "flash",
      "tools": { "use": ["builtin/read_file", "builtin/write_file", "builtin/bash"] },
      "request": { "thinking": "enabled", "reasoning_effort": "high", "max_output_tokens": 4096 },
      "compact": { "trigger_tokens": 800000, "keep_recent_turns": 2, "max_output_tokens": 512 }
    }
  }
}

Configure an agent

Each entry under agents names exactly one model alias in its model field.

Field	Default	Purpose
model	Required	The model alias from models.
tools.use	Required	Exact tool IDs, in the order the model sees them. An empty array gives the agent no tools.
tools.rules	None	Ordered allow, ask and deny rules. See Permissions.
skills.use	[]	Skills the agent may load. Requires builtin/list_skills and builtin/load_skill in tools.use.
hooks.use	[]	Hooks to run, in order.
vars	None	Exact names of root variables the agent may read.
system_prompt	Raw’s default	Literal prompt text. Cannot be combined with system_prompt_file.
system_prompt_file	None	Path to a UTF-8 Markdown file, relative to the config file or absolute.
request	None	Provider-specific request options. See Request options.
cache	None	Prompt-cache settings where the provider supports them. See Context and compaction.
compact	Manual	Compaction settings. See Context and compaction.
max_steps	10000	Maximum model requests in one run.
max_output_bytes	8192	Model-facing cap on each tool result, in bytes.
request_timeout_ms	120000	Deadline for one model request or MCP call.

Tool IDs use these forms: builtin/read_file, local/my_tool, agent/project_note and mcp/search/web_search. The Core concepts page describes each source.

Choose the agent that runs

Raw picks the agent in this order:

1. --agent NAME on the command line.
2. The RAW_AGENT environment variable.
3. default_agent in the config file.

Raw has no --provider, --model or --base-url flags. The agent selection fixes the model, endpoint and credentials for a session.

raw --agent deepseek "Fix the failing tests"

Limits and prompt precedence

Numeric limits resolve in this order, highest first: a command-line flag (--max-steps, --max-output-bytes, --request-timeout-ms), the matching RAW_* environment variable, the agent field, and then the built-in default.

The system prompt resolves in this order: --system-prompt, then RAW_SYSTEM_PROMPT, then the agent’s system_prompt or system_prompt_file, then Raw’s default prompt.

Use a different config file

--config PATH replaces the default config file for one command. An explicit path that does not exist is an error.

raw --config ./team/raw.json --agent project "Summarize the open issues"

Older settings are not accepted

Raw is pre-release and its config schema is strict. Unknown or duplicate fields fail validation. The old profiles, default_profile, --profile and RAW_PROFILE names are not supported. The environment variables RAW_PROVIDER, RAW_MODEL and RAW_BASE_URL cause an error when they are set, even when empty. Rewrite older configs to the models and agents shape shown on this page.

Request options

The request object passes provider-specific settings. It is validated strictly and cannot override the model ID, tools, endpoint or credentials. Each option is accepted only for the provider it names. Raw does not translate options between services, and a provider’s error for an unsupported combination is returned to you.

Method	Options
openai-chat-completions (provider openai)	service_tier, reasoning_effort
openai-chat-completions (provider deepseek)	thinking (enabled or disabled), reasoning_effort (low, high, max)
openai-responses (provider openai)	service_tier, reasoning_effort, reasoning_mode (standard or pro)
anthropic-messages (provider anthropic)	thinking, effort, service_tier
google-generate-content (provider google)	thinking_level or thinking_budget, not both

All methods accept max_output_tokens, a positive integer. For Anthropic, a manual thinking budget must be at least 1024 and smaller than the output cap. Raise compact.max_output_tokens above that budget as well if you enable manual thinking.

Note

GPT-6 Astra tool use requires the openai-responses method.

Add image support

To let an agent view images, mark the model as vision-capable and select the tool explicitly. Raw never adds the tool for you.

1. Set vision to true on the model entry.

   {
     "models": {
       "local": {
         "provider": "ollama",
         "method": "openai-chat-completions",
         "model_id": "YOUR_VISION_MODEL",
         "base_url": "http://127.0.0.1:11434/v1",
         "vision": true
       }
     }
   }

2. Add builtin/view_image to the agent’s tools.use.

3. Name the image path in your task, for example raw "Explain screenshot.png".

A text-only model can still work with images through an MCP tool that returns a text description.

Check your setup

raw config list

The output lists each agent with its model alias, upstream model ID, provider, method, sanitized endpoint, selected tools, tool rules and compaction trigger.