Models

A model is named as provider and name, "anthropic/claude-sonnet-5". An agent, a job or a single step can each name its own, so a cheap step can ask a small model while the rest of the agent asks a large one.

Which model answers

The first of these that is set wins.

	Set with
One step	model on work.model() or work.agent()
A pick for one job	/model <name> for <job> in a chat
One job	model in defineJob, or in a markdown job's frontmatter
A pick for one chat	/model <name>, or /model auto, in that chat (chat turns only)
The agent	model in defineAgent, or the quick model when it has auto: true (see Auto, below)
Every agent	model.defaultModel in settings, which npx chloe setup writes

An agent with none of these is refused as it loads. A model given as an AI SDK model, like anthropic("claude-opus-5-5"), always goes to that provider's own API, on whatever key that package reads.

How a call reaches it, and who pays

There are six routes. Each call goes by the first route in model.preferredRoute that can carry the model's provider and is set up on this machine. A route with nothing set up is skipped.

Route	Goes through	Carries	Paid by	What to set up
claude	the claude command	Anthropic models	your Claude subscription	install Claude Code and sign in
codex	the codex command	the OpenAI models your plan allows	your ChatGPT plan	install Codex and sign in
antigravity	the agy command	Google models	your Google AI Pro plan	install Antigravity CLI and sign in with Google
opencode	the opencode command	whatever it is signed in to	that account	install opencode and sign in
direct	the provider's own API	Anthropic and OpenAI	your key, per call	model.keys.anthropic, model.keys.openai
gateway	an AI gateway	any provider it carries	its key, per call	model.key

The default order is the one above, so a subscription is used before a key that charges per call. To pay with a key instead, put direct first: model: { preferredRoute: ["direct", "claude", "codex", "antigravity", "opencode", "gateway"] }, which is what setup writes when you give it a key.

One model can go by another route than the order says by naming it at the end: "openai/gpt-5.5 via gateway". That works anywhere a model is named, in an agent, a job or a pick from a chat, and the route is used even when it is not set up, so the run fails saying what is missing rather than charging another account.

A key is a secret, so it goes in .env, and the config hands it over: model: { keys: { anthropic: process.env.ANTHROPIC_API_KEY } }, or model: { key: process.env.CHLOE_MODEL_KEY } for a gateway.

Setting	Default	What it controls
model.defaultModel	none	The model of an agent that names none.
model.preferredRoute	["claude", "codex", "antigravity", "opencode", "direct", "gateway"]	The order routes are tried in.
model.keys	none	Anthropic's and OpenAI's own keys, for direct.
model.key	none	The gateway's key.
model.gatewayUrl	the Vercel AI Gateway	Any gateway that speaks the OpenAI chat shape.
model.models	ask each route	The shortlist a person may pick from in a chat. Empty offers everything this machine can reach, often hundreds: each command route and the gateway are asked what they run when chloe starts and when the config changes.
model.program	claude, codex, agy, opencode	Where each command is, when it is not on the path under that name.
model.timeLimit	10	The most minutes one model call may take, on any route. A call still going is stopped, its program killed, and the run fails saying so, instead of holding its job. 0 is no limit. A whole step and one tool call have a limit of their own: see Step, model, agent.
model.judgeModel	"anthropic/claude-sonnet-5"	Who marks an eval.
model.quickModel	the route's own	What Auto hands an easy message, and who names a new conversation on the dashboard. Empty takes the quick model of the route the agent's own model goes by: the claude command's haiku, codex's gpt-6-luna while it lists it. The direct, gateway, antigravity and opencode routes have none, so name one here to use Auto on them. With none, the agent's own model names conversations.

A call that fails in a way a fresh try might fix, such as the provider cutting the stream or dropping the connection, is tried again twice, a few seconds apart, before the run fails. So is an answer on the claude or opencode route that writes tool calls out as text instead of making them. A refusal in words, a missing credential and a usage limit fail at once. The direct and gateway routes also retry a busy or failing provider four times within each call.

No model and no key yet

OpenRouter has free models with no card: make a key at openrouter.ai/keys, set model.gatewayUrl to https://openrouter.ai/api/v1/chat/completions, and ask for openrouter/free, which picks a free model that can call tools. It is limited to a few dozen calls a day, a different model may answer each time, and the runs cost 0 in the record.

A job whose steps are all code needs no model at all, which is why setup runs one before it asks for one.

What the command routes do

Each one runs the command once per step, with the command's own tools switched off, so every tool call is chloe's and is written down.

• claude hands the tools over as real tools. It is never given ANTHROPIC_API_KEY, so a key in .env cannot quietly pay for a subscription run.
• antigravity describes the tools in the prompt too, like codex: the CLI refuses every tool of its own in headless mode, and real MCP tools are not used (the CLI reads its MCP servers from the account's own settings, which is the person's, not chloe's). The prompt goes in over stdin (agy -p hangs in a pipe), and a custom agent written into the run folder makes chloe's instructions the model's system prompt, which also keeps the CLI's own instructions out of the call (about 2k tokens a step, not 12k). The CLI still offers the model its own sixty tools and sometimes the model uses one, which headless refuses and which ends the turn, and its own call format is the same {"tool": ...} shape the prompt asks for: the route is not reliable yet.
• opencode hands the tools over as real tools too. For each step it starts an opencode server of its own, reachable from this machine only, and closes it after. It needs opencode 2 or later, and adds a second or two to each step. The conversation so far goes over as real past turns (opencode's session/import), so past calls are calls to the model and not text it might copy; only the newest turn is sent as the prompt. That endpoint is marked experimental, and an opencode without it gets the whole conversation as one block of text instead.
• codex describes the tools in the prompt and reads the calls back from the reply, which is a little less reliable and costs about 500 tokens a step. It adds about 7,000 tokens of its own instructions to every call.

A run on the claude route shows what it would have cost on the API, as a price, not a charge. opencode names the price its own list gives the model: a charge on an account that pays per call, only a price on a plan. codex and antigravity name no price, so what their runs cost is unknown, and a budget or a web chat's dollar limit cannot be kept on them.

Auto

An agent with auto: true in defineAgent, or a chat picked onto it with /model auto, asks the quick model about each message before it answers: does this need the agent's own model? The quick model sees the message and the last few in the conversation, never the agent's tools, and answers in a line. An easy message is then answered by the quick model, and anything else by the agent's own, in the same way as without Auto.

export default defineAgent({
  model: "anthropic/claude-opus-5-5",
  auto: true,
  identity: "Answers the shop's customers.",
});

• The quick model is found from the route the agent's own model goes by, so the same account pays for both: Opus through the claude command gets the command's Haiku. model.quickModel names one instead.
• A conversation that went to the agent's own model stays there for the hour, without asking again.
• When the quick model fails, or answers in words it cannot be read from, the agent's own model answers.
• The run's first line says which model it went to and why, and what asking cost is in the run's cost.
• Jobs are not on Auto: each keeps the model it names.

The owner can change an agent's model, and switch Auto on or off, from the model on the agent's page on the dashboard, or with POST /api/agents/<id>/own-model and { "model", "auto" }. Either writes its agent.ts, and leaves a model the file says as code, like anthropic("claude-opus-5-5"), for the file.

On a subscription, a quick model saves the plan's limits and time, not money.

Picking one from a chat

/models lists what may be picked, with a button each on Telegram. A model that more than one route here can run is listed once for each, the others as <name> via <route>, and so it is on the dashboard. /model <name> picks one for that chat, /model <name> for <job> for one job, /model auto puts that chat on Auto, and /model default takes a pick back, with the same for. A pick is a trial and is not how an agent's model is set: what it runs on is model in its own definition, and there is no pick for the whole agent. The run record still says which model made each run.

Over the API: GET /api/models, and POST /api/agents/<id>/model with { "scope", "model" }, where scope is job:<id> or chat:<thread>, "auto" puts a chat on Auto, and an empty model takes the pick back.