# Example configuration for zagent.

# Copy this file to one of the following locations:

# $XDG_CONFIG_HOME/zagent

# ~/.config/zagent

#

# Environment variables override values from this file.

# Optional. Select a built-in provider preset: openai, deepseek, anthropic,

# openai-compatible, anthropic-compatible or codex.

# The preset supplies AI_URL, AI_MODEL, the wire protocol, and the name of the

# environment variable holding the API key (DEEPSEEK_API_KEY for deepseek,

# ANTHROPIC_API_KEY for anthropic). Anything set below, or via AI_* environment

# variables, still takes precedence.

#

# When this is unset, the preset is autodetected from whichever API key the

# environment exports: OPENAI_API_KEY selects openai, DEEPSEEK_API_KEY selects

# deepseek, ANTHROPIC_API_KEY selects anthropic, and openai wins if more than

# one is exported.

#

# openai-compatible is for any other vendor that implements the Responses API

# — Alibaba Cloud Model Studio (百炼), Moonshot, Zhipu, a local vLLM server.

# It supplies no defaults: AI_URL and AI_MODEL below are required, the key is

# read from AI_KEY, and startup names the setting that is still missing.

# The names openai_compatible and compatible are accepted as well.

# AI_PROVIDER=openai-compatible

# AI_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

# AI_MODEL=qwen-plus

#

# anthropic-compatible is the same for any vendor speaking the Anthropic

# Messages API; the client posts to <AI_URL>/messages instead of /responses.

# Anthropic's own API needs neither setting: AI_PROVIDER=anthropic and

# ANTHROPIC_API_KEY are enough.

# AI_PROVIDER=anthropic-compatible

# AI_URL=https://api.moonshot.cn/anthropic

# AI_MODEL=kimi-k2-turbo-preview

#

# Left commented out because the AI_URL and AI_MODEL below configure OpenAI.

# AI_PROVIDER=deepseek

# Required for remote endpoints, on either protocol.

# Under AI_PROVIDER=deepseek, set DEEPSEEK_API_KEY in the environment instead.

#

# Note that a key set here also turns the autodetection described above off:

# the key stays paired with the AI_URL below rather than following an

# unrelated exported variable.

AI_KEY=sk-your-api-key-here

# Optional. API base URL; zagent appends /responses or /messages, following the

# protocol of the selected preset (no Chat Completions fallback).

# Defaults to https://api.openai.com/v1; DeepSeek uses https://api.deepseek.com,

# Anthropic https://api.anthropic.com/v1.

# Alibaba Cloud Model Studio: https://dashscope.aliyuncs.com/compatible-mode/v1

AI_URL=https://api.openai.com/v1

# Optional. Defaults to gpt-4o-mini

# DeepSeek example: deepseek-flash or deepseek-v4-pro. Model names are sent unchanged.

AI_MODEL=gpt-4o-mini

# Optional. Initial output budget; defaults to 8192, the most DeepSeek's chat

# models accept. Sent as max_output_tokens on the Responses API and as

# max_tokens on the Messages API.

# On token truncation, retry up to 3 times with doubled budgets (growth cap 8192).

# A reply still cut off is continued from where it stopped, up to 8 times.

AI_MAX_TOKENS=8192

# Optional standard Responses reasoning effort, sent as the outer-level

# reasoning.effort to any Responses provider. Not sent to a Messages endpoint,

# which has no such field; asked for by name above it is AI_THINKING that turns

# thinking on there, with a budget of AI_MAX_TOKENS / 2.

# Omitted when unset or empty; whether a value is accepted is up to the model

# and the backend.

# AI_REASONING_EFFORT=high

# Optional thinking switch, sent as the outer-level thinking object.

# enabled/disabled ask for the mode explicitly, omit drops the field. Left unset,

# deepseek and openai-compatible ask for thinking (DeepSeek keeps it on when the

# field is missing) while openai and codex send nothing they do not define.

# AI_THINKING=enabled

# Optional explicit prompt cache retention; omitted by default. Responses only.

# Confirm that your endpoint supports this field. Accepts only in_memory or 24h.

# Automatic caching may work even without it.

# AI_PROMPT_CACHE_RETENTION=in_memory

# Optional. Record every step of a run — each request, its raw response stream,

# every tool call and result — and write an HTML report of it when the run

# ends. `--debug` does the same for one run; see docs/debug.md.

# AI_DEBUG=1

# Optional. Where the web tools ask instead of their built-in behaviour.

# web_search sends the query to this endpoint with {query} filled in (and

# {limit} when the URL names it), or adds q= to its query string when it does

# not. Unset, the query goes to DuckDuckGo's own results page, which takes no

# key. See docs/web.md.

# WEB_SEARCH_URL=https://searx.example.com/search?q={query}&format=json

# WEB_SEARCH_KEY=your-search-service-key

#

# web_fetch asks this service for a page and returns its answer unchanged; the

# page's address fills {url}, or is appended to the URL when it names no {url}.

# Unset, the page is fetched here and read as markdown.

# WEB_FETCH_URL=https://r.jina.ai/

# WEB_FETCH_KEY=your-reader-service-key

# MCP servers are described in a separate file, mcp.json, in the same

# directory as this one — there is no equivalent setting here, and no

# environment variable. See mcp.example.json for its members, and note that

# only this user-level file is read: zagent never starts a server named by a

# file in the directory it happens to be running in.

# These options are environment variables (not config file keys):

# AI_MEMORY_FILE=/path/to/notes.md # store memory somewhere else

# Tools and local MCP servers run directly with host environment, permissions

# and network access; start in the project directory and only run trusted tasks.

# Zig compiler version: 0.17.0.

# ChatGPT subscription: run `zagent login`, then select this provider.

# Uses the official Codex backend; no API key or custom AI_URL.

# AI_PROVIDER=codex

# AI_MODEL=gpt-5.4

# Optional, Codex only: its fast mode. Omitted from requests when unset or empty;

# the value is passed through unchanged.

# AI_SERVICE_TIER=fast