[{"data":1,"prerenderedAt":5429},["ShallowReactive",2],{"blog-post-agents-md-multi-agent-best-practices":3,"related-posts-agents-md-multi-agent-best-practices":475},{"id":4,"title":5,"author":6,"body":10,"category":449,"date":450,"description":451,"extension":452,"featured":453,"hideToc":453,"image":454,"imageHeight":455,"imageWidth":456,"meta":457,"navigation":458,"path":459,"readingTime":460,"redirected":453,"seo":461,"seoTitle":462,"stem":463,"tags":464,"updatedDate":473,"__hash__":474},"blog/blog/agents-md-multi-agent-best-practices.md","AGENTS.md for Multi-Agent Systems: Stop Writing One File for Five Agents",{"name":7,"role":8,"avatar":9},"Shabnam Katoch","Growth Head","/img/avatars/shabnam-profile.jpeg",{"type":11,"value":12,"toc":437},"minimark",[13,20,28,31,34,39,42,45,53,59,66,77,84,88,95,101,123,137,142,145,151,155,158,165,168,171,178,185,188,192,199,202,218,227,230,240,243,249,253,256,282,289,304,308,311,317,326,332,335,339,342,348,365,372,376,379,386,400,404,410,419,425,431],[14,15,16],"p",{},[17,18,19],"strong",{},"One instruction file was built for one agent. The moment you add a second, every rule in it gets obeyed twice, billed twice, and misread once. Here's the three-layer layout that fixes it.",[14,21,22,23,27],{},"Picture the setup. A root AGENTS.md with one sensible line: ",[24,25,26],"em",{},"\"Run the full test suite before you consider any change done.\""," One agent, that's fine. Then you add a planner, a coder, a tester, and a reviewer, and hand them all the same file.",[14,29,30],{},"The planner runs the test suite before it plans. The coder runs it after every edit. The tester runs it, which is at least its job. The reviewer runs it before reviewing. Four agents, one line, and the suite runs a dozen times per task, each one billed as tool output flowing back into a context window.",[14,32,33],{},"Nobody wrote a bug. Everybody followed the instructions. That is the whole problem with AGENTS.md in a multi-agent system, and it's worth getting right before you scale from one agent to five.",[35,36,38],"h2",{"id":37},"the-file-you-wrote-for-one-agent-doesnt-scale-by-copying-it","The file you wrote for one agent doesn't scale by copying it",[14,40,41],{},"Here's the part most guides skip. AGENTS.md was designed as a single file at the root of a repo, read by a single coding agent, and it's very good at that. It's now in 60,000-plus public repositories and is stewarded under the Linux Foundation's Agentic AI Foundation. Around thirty tools read it.",[14,43,44],{},"But the spec is deliberately thin. The FAQ says two things about conflicts: the AGENTS.md nearest to the file being edited wins, and anything typed directly into chat overrides all of it. That's it. What happens when three agents with three different jobs read the same file is left to the tools, and the tools disagree.",[14,46,47,48,52],{},"Codex concatenates every AGENTS.md from the root down to the working directory and caps the combined text at 32 KiB by default. Factory's Droid walks nearest-first. Claude Code doesn't read AGENTS.md at all; it reads CLAUDE.md, and the common workaround is a one-line ",[49,50,51],"code",{},"@AGENTS.md"," import at the top. Three tools, three loading orders, one file.",[54,55,56],"blockquote",{},[14,57,58],{},"\"Nearest file wins\" is a rule about directories. It says nothing about roles. A tester and a deployer in the same directory get the same instructions, and only one of them should be allowed to touch production.",[14,60,61,62,65],{},"Then there's the cost. An ETH Zurich study published in February 2026 tested context files across four coding agents on SWE-bench and a new benchmark built from repos with developer-written files. Every context file, human or LLM-written, increased inference cost and step count, by more than 20 percent. LLM-generated files nudged success rates ",[24,63,64],{},"down",". Human-written files nudged them up by roughly 4 percent, and neither shift was statistically significant.",[14,67,68,69,72,73,76],{},"The behavioural finding matters more than the headline. Agents follow context files too faithfully. Mention ",[49,70,71],{},"uv"," instead of ",[49,74,75],{},"pip"," and agents invoke it 1.6 times per task versus almost never without the mention. That's great when the instruction is right and expensive when it's stale. Now multiply the 20 percent overhead and the obedience by every agent that loads the file.",[14,78,79],{},[80,81],"img",{"alt":82,"src":83},"One AGENTS.md file adding 20 percent cost, multiplied across five agents, based on the ETH Zurich February 2026 study, hand-drawn pastel style","/img/blog/agents-md-multi-agent-best-practices-instruction-overhead.jpg",[35,85,87],{"id":86},"three-layers-not-one-file","Three layers, not one file",[14,89,90,91,94],{},"The fix that has held up in every multi-agent setup I've seen work is to stop thinking of AGENTS.md as ",[24,92,93],{},"the"," instructions and start thinking of it as one of three layers.",[14,96,97,100],{},[17,98,99],{},"Layer one: root invariants."," The root AGENTS.md holds only what is true for every agent in every directory. Toolchain choices, the test command, the branch naming rule, the \"never commit secrets\" line. If a rule doesn't apply to every agent, it doesn't go here. Aim for under 60 lines. The ETH data says a bloated root is worse than no root.",[14,102,103,106,107,110,111,114,115,118,119,122],{},[17,104,105],{},"Layer two: scope files."," Nested AGENTS.md files in the directories that have their own conventions. ",[49,108,109],{},"packages/api/AGENTS.md"," knows about migrations. ",[49,112,113],{},"packages/web/AGENTS.md"," knows about component rules. This is what the nearest-file-wins rule was built for, and OpenAI's own monorepo reportedly runs about 88 of them. Scope files describe ",[24,116,117],{},"places",", never ",[24,120,121],{},"roles",".",[14,124,125,128,129,132,133,136],{},[17,126,127],{},"Layer three: role files."," This is the layer the spec doesn't cover, so you build it with whatever your tooling gives you. In Claude Code it's a markdown file in ",[49,130,131],{},".claude/agents/"," whose body becomes that subagent's system prompt. On OpenClaw it's a per-agent SOUL.md alongside a per-agent AGENTS.md in each agent's workspace. On a hosted platform it's the per-agent instruction field. The role file says what ",[24,134,135],{},"this"," agent is for, what it may touch, and what it must hand back.",[54,138,139],{},[14,140,141],{},"Root answers \"what is always true here.\" Scope answers \"what is true in this folder.\" Role answers \"what is true for you.\" A rule in the wrong layer is a rule that will be obeyed by the wrong agent.",[14,143,144],{},"The tester's role file says \"run the suite and report failures as a list.\" The coder's says \"do not run the full suite; run the tests for the files you touched.\" The reviewer's says \"read only; never execute.\" Same root, same scope files, four different behaviours. The dozen redundant test runs from the opening go away without deleting the rule that caused them.",[14,146,147],{},[80,148],{"alt":149,"src":150},"Three layers of agent instructions: root AGENTS.md invariants, scope AGENTS.md per directory, and role files per agent, hand-drawn pastel style","/img/blog/agents-md-multi-agent-best-practices-three-layers.jpg",[35,152,154],{"id":153},"what-a-subagent-actually-sees-and-what-it-doesnt","What a subagent actually sees, and what it doesn't",[14,156,157],{},"This is where multi-agent AGENTS.md goes wrong quietly, because the failure looks like a model problem rather than a config problem.",[14,159,160,161,164],{},"Take Claude Code's documented behaviour, since it's the most explicit. A standard subagent starts with its own system prompt from the role file, the delegation message from the parent, the CLAUDE.md hierarchy, and basic environment details like the working directory. It does ",[24,162,163],{},"not"," get the parent's conversation history, the files the parent already read, or the parent's earlier tool calls. Only the subagent's final message comes back. The built-in Plan subagent skips CLAUDE.md entirely.",[14,166,167],{},"So if your root file says \"we decided in the kickoff to use the v2 schema,\" the subagent that reads it has no idea what kickoff that was. And if the parent decided something at message 30 that never made it into a file, the subagent will happily contradict it at message 31.",[14,169,170],{},"Two rules fall out of this.",[14,172,173,174,177],{},"First, ",[17,175,176],{},"never put state in an instruction file."," Decisions, current task, who's doing what: those change per run and belong in the delegation message or a scratch file the parent writes. AGENTS.md is for what's still true next week.",[14,179,180,181,184],{},"Second, ",[17,182,183],{},"the parent's delegation message is the real interface",", and it deserves the same care as the file. Claude Code even warns you at startup if your combined subagent descriptions cross 15,000 tokens, because every description loads into the parent's context so it can decide whom to delegate to. Keep descriptions to a sentence. Put the detail in the role body, which only loads when that agent runs.",[14,186,187],{},"Anthropic's engineering team put a number on the stakes when they built their multi-agent research system: agents use roughly four times the tokens of a chat, and multi-agent systems roughly fifteen times. Every stray paragraph in a shared file is paid at that multiplier.",[35,189,191],{"id":190},"the-handoff-contract-is-the-part-everyone-forgets-to-write","The handoff contract is the part everyone forgets to write",[14,193,194,195,198],{},"Single-agent AGENTS.md tells the agent how to work. Multi-agent AGENTS.md also has to tell each agent how to ",[24,196,197],{},"stop",", and what to leave behind for the next one.",[14,200,201],{},"I've started calling this the handoff contract, and it's the most valuable forty lines in the whole setup. Each role file should answer four questions in plain language:",[203,204,205,209,212,215],"ul",{},[206,207,208],"li",{},"What does \"done\" mean for you, specifically? A passing test list, a diff, a review with severity tags, a deployment log.",[206,210,211],{},"What format do you return it in? Fixed headings, a JSON block, a file path. The parent and the next agent should never have to parse prose.",[206,213,214],{},"What must you never touch? The coder doesn't edit tests. The reviewer doesn't edit anything. The deployer doesn't read source.",[206,216,217],{},"When do you stop and escalate instead of continuing? A failing migration, a missing credential, a scope that has grown past what you were asked.",[14,219,220,221,226],{},"That last one is the safety line. An agent with a clear \"stop here\" instruction fails loudly. An agent without one keeps going, and keeps billing, and occasionally keeps deleting. If you've read our piece on ",[222,223,225],"a",{"href":224},"/blog/agent-rules-drift-fix","why agents drift from their rules",", the pattern is the same: the rule that matters most is the one that says when to stop.",[14,228,229],{},"A minimal tester role file, for reference:",[231,232,237],"pre",{"className":233,"code":235,"language":236},[234],"language-text","You are the tester for this repository.\nDone means: the test suite for the files listed in your task ran, and you returned results.\nReturn format: a heading \"RESULTS\", then one line per failing test: file, test name, first line of the error.\nNever edit source or test files. Never run the full suite unless the task says \"full\".\nStop and report if: more than 10 tests fail, a test takes over 5 minutes, or a required service is unreachable.\n","text",[49,238,235],{"__ignoreMap":239},"",[14,241,242],{},"Eight lines. No architecture overview, no \"the codebase is organised as follows.\" The ETH paper found that codebase-overview prose had essentially no effect on how fast agents found files, because agents read the codebase anyway. What moved behaviour was specific, non-obvious instruction. Write that and nothing else.",[14,244,245],{},[80,246],{"alt":247,"src":248},"The handoff contract: a relay baton passing from coder to tester above the four questions every role file must answer, hand-drawn pastel style","/img/blog/agents-md-multi-agent-best-practices-handoff-contract.jpg",[35,250,252],{"id":251},"conflict-rules-you-have-to-write-down-yourself","Conflict rules you have to write down yourself",[14,254,255],{},"The spec's precedence is directory-based and tool-dependent. Your system has role-based conflicts the spec can't see. So say them out loud, in the root file, in one short block:",[203,257,258,261,268,275],{},[206,259,260],{},"A direct instruction in the current task beats every file. (This is also what Codex's own guidance says, and most tools follow it.)",[206,262,263,264,267],{},"A role file beats a scope file on ",[24,265,266],{},"behaviour",". The tester's \"never edit\" wins over a scope file's \"always fix lint on save.\"",[206,269,270,271,274],{},"A scope file beats the root on ",[24,272,273],{},"conventions",". The api package's migration rule wins over the root's generic database line.",[206,276,277,278,281],{},"The root wins on ",[24,279,280],{},"safety and secrets",", always, and no lower file may loosen it.",[14,283,284,285,288],{},"Four lines. Every agent reads them, and when two files disagree, the agent has a tiebreaker instead of a coin flip. If you use Codex, keep temporary experiments in ",[49,286,287],{},"AGENTS.override.md"," rather than editing the root, so the override is obviously temporary and easy to delete.",[14,290,291,292,295,296,299,300,303],{},"One more thing to make explicit: personal instruction files. Codex reads ",[49,293,294],{},"~/.codex/AGENTS.md",", Factory reads ",[49,297,298],{},"~/.factory/AGENTS.md",", Claude Code has ",[49,301,302],{},"CLAUDE.local.md",". In a multi-agent setup with several humans, a personal file that says \"always use tabs\" will fight the repo file that says spaces, on every agent, silently. Personal files should hold preferences, never requirements. Repo files and task instructions should always be able to override them.",[35,305,307],{"id":306},"what-to-delete-before-you-add-anything","What to delete before you add anything",[14,309,310],{},"If your root AGENTS.md is over a hundred lines, you almost certainly have one of these three things in it, and each one gets worse with every agent you add.",[14,312,313,316],{},[17,314,315],{},"Redundant documentation."," The ETH team ran a clever control: strip all READMEs and docs from the repos, then test the LLM-generated context files again. The same files that hurt performance in documented repos improved it by 2.7 percent in bare ones. The content wasn't useless. It was duplicated. If your AGENTS.md restates the README, delete the restatement and link the README.",[14,318,319,325],{},[17,320,321,322,122],{},"Explanations of ",[24,323,324],{},"why"," Agents don't need the history of a decision to follow it. \"Use uv\" works. \"We migrated to uv in March because pip was slow in CI\" is thirty tokens of context per agent per run that changes nothing.",[14,327,328,331],{},[17,329,330],{},"Anything about a single agent's job."," If a line only matters to the reviewer, it's a role-file line living in the root, and every other agent is now paying to read and, per the obedience finding, probably trying to follow it.",[14,333,334],{},"We built BetterClaw's per-agent instruction model after watching exactly this happen on our own agents, where one shared file kept teaching the briefing agent things only the scraper needed to know. Each agent gets its own instructions, its own trust level, and its own cost cap, so a bloated rule can't quietly multiply across the fleet. Free plan, bring your own keys.",[35,336,338],{"id":337},"a-layout-you-can-copy","A layout you can copy",[14,340,341],{},"Here is the shape that has worked, tool-agnostic:",[231,343,346],{"className":344,"code":345,"language":236},[234],"repo/\n  AGENTS.md                  # root: invariants + the four conflict rules, under 60 lines\n  CLAUDE.md                  # one line: @AGENTS.md (only if Claude Code is in the mix)\n  packages/\n    api/AGENTS.md            # scope: migrations, db, api conventions\n    web/AGENTS.md            # scope: components, build, a11y rules\n  .claude/agents/            # role files (Claude Code), one per agent, body = system prompt\n    planner.md\n    coder.md\n    tester.md\n    reviewer.md\n",[49,347,345],{"__ignoreMap":239},[14,349,350,351,355,356,360,361,122],{},"On OpenClaw the role layer moves into each agent's workspace as its own AGENTS.md plus SOUL.md, and the ",[222,352,354],{"href":353},"/blog/soul-md-agents-md-configuration-guide","SOUL.md and AGENTS.md configuration guide"," covers what goes in which. If you're running three or more agents on OpenClaw specifically, the ",[222,357,359],{"href":358},"/blog/openclaw-multi-agent-setup","multi-agent setup guide"," handles the memory isolation and session binding that this post deliberately leaves alone. For the single-agent version of this file, start with ",[222,362,364],{"href":363},"/blog/agents-md-best-practices","AGENTS.md best practices",[14,366,367,368,371],{},"Whatever the tooling, the test is the same. Pick any line in any file and ask: ",[24,369,370],{},"which agents will read this, and should all of them obey it?"," If the answer is \"not all of them,\" it's in the wrong layer.",[35,373,375],{"id":374},"where-this-lands","Where this lands",[14,377,378],{},"Two years ago the question was whether an agent would read the file at all. Now the file gets read, obeyed, and billed by every agent you point at it, and the research says the honest default is to write less than feels comfortable.",[14,380,381,382,385],{},"The multi-agent version of that lesson is sharper. A single agent with a bloated AGENTS.md wastes tokens. A fleet with a bloated shared AGENTS.md wastes tokens ",[24,383,384],{},"in unison",", and occasionally does something four times that should have happened once. The layout above isn't clever. It's just the discipline of asking, for every rule, who it's actually for.",[14,387,388,389,395,396,122],{},"If any of this resonated, give BetterClaw a try. The free plan gives you one agent and 100 credits a month, bring your own API keys, no inference markup, and it never asks for a card. Pro is $49 a month for five agents, or $39 a month billed annually. Per-agent instructions and trust levels are on by default, so the three-layer model is how the product already thinks. ",[222,390,394],{"href":391,"rel":392},"https://app.betterclaw.io/sign-in",[393],"nofollow","Start free"," or ",[222,397,399],{"href":398},"/pricing","see full pricing",[35,401,403],{"id":402},"frequently-asked-questions","Frequently Asked Questions",[14,405,406,409],{},[17,407,408],{},"What is AGENTS.md in a multi-agent system?","\nAGENTS.md is a plain Markdown instruction file that AI coding agents read before working, now used in 60,000-plus repositories and stewarded by the Linux Foundation's Agentic AI Foundation. In a multi-agent system it works best as one of three layers: a short root file with rules true for every agent, nested scope files for directory-specific conventions, and separate per-agent role files that hold each agent's job, boundaries, and handoff format.",[14,411,412,415,416,418],{},[17,413,414],{},"How does AGENTS.md compare to CLAUDE.md and per-agent role files?","\nAGENTS.md is cross-tool and directory-scoped, with the nearest file winning on conflict. CLAUDE.md is Claude Code's own file, supports @imports, and is commonly pointed at AGENTS.md with a single import line. Role files (for example, the markdown files in Claude Code's ",[49,417,131],{}," folder, or a per-agent SOUL.md on OpenClaw) describe one agent's behaviour rather than one directory's conventions, which is the gap the AGENTS.md spec doesn't cover.",[14,420,421,424],{},[17,422,423],{},"How do I stop multiple agents from running the same instruction redundantly?","\nMove any instruction that only one agent should act on out of the root AGENTS.md and into that agent's role file, then give each role file an explicit \"never do X\" line for the behaviours it should skip. For example, the tester runs the suite and the coder runs only the tests for touched files. Add a four-line precedence block to the root so agents have a tiebreaker when files conflict.",[14,426,427,430],{},[17,428,429],{},"Is a detailed AGENTS.md worth the cost for a team of agents?","\nOnly if it's short and specific. An ETH Zurich study from February 2026 found every context file raised inference cost by over 20 percent per run, LLM-generated files slightly lowered success rates, and hand-written files gained roughly 4 percent, not statistically significant. In a multi-agent system that overhead is paid per agent, so a lean root plus targeted role files beats one comprehensive file on both cost and reliability.",[14,432,433,436],{},[17,434,435],{},"Is it safe to let subagents read the same AGENTS.md as the main agent?","\nYes, as long as the shared file contains no state and no role-specific behaviour, and the root's safety rules are marked as non-overridable. Subagents in Claude Code receive the CLAUDE.md hierarchy but not the parent's conversation, so anything decided mid-session must travel in the delegation message. Put \"stop and escalate\" conditions in every role file and use per-agent trust levels or approval gates for anything that writes to production.",{"title":239,"searchDepth":438,"depth":438,"links":439},2,[440,441,442,443,444,445,446,447,448],{"id":37,"depth":438,"text":38},{"id":86,"depth":438,"text":87},{"id":153,"depth":438,"text":154},{"id":190,"depth":438,"text":191},{"id":251,"depth":438,"text":252},{"id":306,"depth":438,"text":307},{"id":337,"depth":438,"text":338},{"id":374,"depth":438,"text":375},{"id":402,"depth":438,"text":403},"Best Practices","2026-09-08","AGENTS.md best practices for multi-agent setups: root, scope, and role layers, subagent context rules, handoff contracts, and what to delete before adding.","md",false,"/img/blog/agents-md-multi-agent-best-practices.jpg",512,1024,{},true,"/blog/agents-md-multi-agent-best-practices","13 min read",{"title":5,"description":451},"AGENTS.md for Multi-Agent Systems: Best Practices (2026)","blog/agents-md-multi-agent-best-practices",[465,466,467,468,469,470,471,472],"agents.md multi-agent","agents.md best practices","agents.md nested files","agents.md subagents","agents.md precedence","agents.md vs claude.md","multi-agent instruction files","agent handoff contract",null,"-uzkTT00BLGP9NPJCCDFSLOKXx_olu8i9Qi10lm9W5o",[476,1925,2267,3023,3525,4045,4486,4910],{"id":477,"title":478,"author":479,"body":480,"category":449,"date":1905,"description":1906,"extension":452,"featured":453,"hideToc":458,"image":1907,"imageHeight":473,"imageWidth":473,"meta":1908,"navigation":458,"path":363,"readingTime":1909,"redirected":453,"seo":1910,"seoTitle":1911,"stem":1912,"tags":1913,"updatedDate":1923,"__hash__":1924},"blog/blog/agents-md-best-practices.md","AGENTS.md Best Practices: Write the File That Makes Your Agent Actually Follow Instructions",{"name":7,"role":8,"avatar":9},{"type":11,"value":481,"toc":1878},[482,485,488,491,494,497,500,507,510,513,516,520,523,533,536,539,545,550,553,556,559,564,567,585,588,593,596,601,604,609,612,617,633,637,640,649,652,655,659,665,670,678,681,684,688,691,697,700,819,822,826,829,832,836,839,842,845,848,852,855,861,867,877,883,886,889,893,896,899,919,925,928,937,941,944,953,959,973,976,980,983,986,996,1000,1003,1012,1015,1029,1033,1036,1039,1045,1083,1086,1089,1093,1096,1382,1385,1389,1392,1397,1483,1490,1495,1636,1639,1644,1784,1787,1790,1793,1799,1802,1805,1808,1810,1814,1817,1821,1827,1831,1834,1838,1841,1845,1854,1858,1867,1871,1874],[14,483,484],{},"AGENTS.md is a Markdown file at the root of a code repository that tells AI coding agents how to work in that project. It covers the stack, build and test commands, code style, architecture constraints, and boundaries. It is read natively by 30+ AI tools including Claude Code, GitHub Copilot, Cursor, OpenAI Codex, and Gemini CLI.",[14,486,487],{},"60,000+ repos have one. 30+ AI tools read it. But most AGENTS.md files are either too long, too vague, or generated by an LLM (which makes your agent worse). Here's how to write one that works.",[14,489,490],{},"Our coding agent kept generating class components. The entire codebase was functional React with hooks. The README said \"React 19, functional components.\" The contributing guide explained it in detail.",[14,492,493],{},"The agent didn't read the README. It doesn't know to.",[14,495,496],{},"Then we added an AGENTS.md file with one line in the style section: Always use functional components with hooks. Never use class components. Plus one code example showing the pattern.",[14,498,499],{},"The problem disappeared instantly.",[14,501,502,503,506],{},"Running more than one agent? See how to ",[222,504,505],{"href":459},"organise agents.md across multiple agents"," without conflicts or drift.",[14,508,509],{},"That's what AGENTS.md does. It's a Markdown file at the root of your repository that gives AI agents the project-specific context they need to work correctly. Not documentation for humans. Instructions for machines. And as of 2026, it's read natively by 30+ AI tools including Claude Code, GitHub Copilot, Cursor, OpenAI Codex, Gemini CLI, Windsurf, Devin, Aider, and Amazon Q.",[14,511,512],{},"The convention has been adopted by over 60,000 repositories and is now stewarded by the Agentic AI Foundation under the Linux Foundation. If you build with AI agents and don't have an AGENTS.md, your agents are guessing at conventions they should know.",[14,514,515],{},"Here's how to write one that actually improves agent behavior instead of wasting context tokens.",[35,517,519],{"id":518},"what-goes-in-an-agentsmd-and-what-doesnt","What goes in an AGENTS.md (and what doesn't)",[14,521,522],{},"The common mistake is treating AGENTS.md like documentation. Long explanations. Architecture philosophy. Design rationale. History of the project.",[14,524,525,526,529,530,122],{},"Your agent doesn't need to know why you chose Next.js over Remix. It needs to know that you use Next.js 15 with App Router, and the test command is ",[49,527,528],{},"pnpm test",", not ",[49,531,532],{},"npm test",[14,534,535],{},"Research across 2,500+ repositories found that AGENTS.md files over 150 lines deliver diminishing returns and can increase inference costs 20-23% without improving agent performance. The technical maximum is 32 KiB, but aim for under 150 lines.",[14,537,538],{},"Here are the sections that matter, in the order they should appear:",[14,540,541],{},[80,542],{"alt":543,"src":544},"The AGENTS.md nutrition label: serving size under 150 lines, with project stack, build and test commands, code style with examples, architecture constraints, boundaries, and a short git workflow section.","/img/blog/agents-md-best-practices-nutrition-label.jpg",[14,546,547],{},[17,548,549],{},"Project stack (5-10 lines)",[14,551,552],{},"Language, framework, major dependencies, runtime. Be specific.",[14,554,555],{},"Good: Next.js 15 App Router, React 19, TypeScript 5.4, Tailwind CSS, Drizzle ORM, Bun",[14,557,558],{},"Bad: This is a modern web application built with React and various supporting libraries.",[14,560,561],{},[17,562,563],{},"Build and test commands (5-10 lines)",[14,565,566],{},"Exact commands with exact flags. Package manager matters. Build targets matter.",[14,568,569,570,573,574,577,578,581,582],{},"Good: Build: ",[49,571,572],{},"bun run build",". Test: ",[49,575,576],{},"bun test",". Lint: ",[49,579,580],{},"bun run lint --fix",". Deploy: ",[49,583,584],{},"bun run deploy:staging",[14,586,587],{},"Bad: Run the standard build and test commands as described in package.json.",[14,589,590],{},[17,591,592],{},"Code style conventions (10-20 lines, with examples)",[14,594,595],{},"One code example per convention beats three paragraphs describing it. This is the single most important insight from studying effective AGENTS.md files. Show, don't tell.",[14,597,598],{},[17,599,600],{},"Architecture constraints (5-15 lines)",[14,602,603],{},"Directory structure rules. Module boundaries. Import restrictions. Data flow patterns.",[14,605,606],{},[17,607,608],{},"Boundaries (5-10 lines)",[14,610,611],{},"What the agent should never touch. \"Never commit secrets\" was the most common helpful constraint across the 2,500-repository analysis. Add: generated files, legacy modules, configuration files that shouldn't change, directories managed by other tools.",[14,613,614],{},[17,615,616],{},"Git workflow (5 lines)",[14,618,619,620,623,624,623,627,623,630,122],{},"Branch naming, commit message format, PR conventions. Squash merge only. Conventional commits: ",[49,621,622],{},"feat:",", ",[49,625,626],{},"fix:",[49,628,629],{},"chore:",[49,631,632],{},"docs:",[35,634,636],{"id":635},"agentsmd-size-what-the-research-says","AGENTS.md size: what the research says",[14,638,639],{},"Keep it under 150 lines. That is the single number worth remembering, and it is the one most teams get wrong in the same direction: too long.",[14,641,642,643,648],{},"Two independent data points support it. The 2,500-repository analysis found diminishing returns past 150 lines, with inference costs rising 20-23% and no measurable improvement in agent behaviour. Separately, Coldtea's ",[222,644,647],{"href":645,"rel":646},"https://www.coldtea.ai/blog/agents-md-field-study",[393],"field study of the 100 biggest GitHub repos"," found the median AGENTS.md runs 1,198 words across roughly 14 headings, with a barbell distribution: 37% are sprawling constitutions past 1,500 words, while one file in ten comes in under 150 words.",[14,650,651],{},"Note the units. The 150-line guidance and the 1,198-word median measure different things, and a 150-line file with code blocks can easily exceed 1,198 words. Treat both as a ceiling signal rather than a target: the technical maximum is 32 KiB, but nothing in the data suggests longer files perform better.",[14,653,654],{},"The pattern across both studies is the same. Shorter, accurate, project-specific files beat comprehensive generic ones. Start at 30-50 lines covering stack, build commands, code style with examples, and boundaries. Add a section only when an agent consistently makes a specific mistake.",[35,656,658],{"id":657},"the-three-mistakes-that-make-agentsmd-useless","The three mistakes that make AGENTS.md useless",[14,660,661],{},[80,662],{"alt":663,"src":664},"The AGENTS.md hall of shame: the three mistakes that make a file useless — letting an LLM generate it, describing conventions instead of showing them with code, and not updating it.","/img/blog/agents-md-best-practices-hall-of-shame.jpg",[666,667,669],"h3",{"id":668},"mistake-1-letting-an-llm-generate-it","Mistake 1: Letting an LLM generate it",[14,671,672,673,677],{},"This is the most common mistake and the most damaging. Research found that LLM-generated AGENTS.md files reduce task success in 5 out of 8 tested settings and add 2.45-3.92 extra steps per task. The file-based approach is only one way to do this; on a ",[222,674,676],{"href":675},"/","no-code AI agent builder"," the same instructions live in the agent's role and are versioned for you.",[14,679,680],{},"Why? LLMs generate generic, verbose instructions that state the obvious. \"Follow best practices for error handling.\" \"Write clean, maintainable code.\" \"Use descriptive variable names.\" Your agent already knows this. You're burning context tokens on advice the model was trained to follow by default.",[14,682,683],{},"Write your AGENTS.md by hand. Include only the conventions that are specific to YOUR project and that an agent wouldn't know without being told.",[666,685,687],{"id":686},"mistake-2-describing-conventions-instead-of-showing-them","Mistake 2: Describing conventions instead of showing them",[14,689,690],{},"Bad:",[231,692,695],{"className":693,"code":694,"language":236},[234],"Use our custom error handling approach where errors bubble up through\nthe service layer and are caught by the global error handler rather\nthan being caught at individual function level.\n",[49,696,694],{"__ignoreMap":239},[14,698,699],{},"Good:",[231,701,705],{"className":702,"code":703,"language":704,"meta":239,"style":239},"language-js shiki shiki-themes github-light","// Error handling: Let errors propagate. Do not wrap individual calls\n// in try/catch. The global handler catches everything.\n\n// CORRECT\nasync function getUser(id) {\n  const user = await db.users.findById(id);\n  return user;\n}\n\n// WRONG\nasync function getUser(id) {\n  try {\n    const user = await db.users.findById(id);\n    return user;\n  } catch (e) {\n    logger.error(e);\n    throw e;\n  }\n}\n","js",[49,706,707,715,720,726,732,738,744,750,756,761,767,772,778,784,790,796,802,808,814],{"__ignoreMap":239},[708,709,712],"span",{"class":710,"line":711},"line",1,[708,713,714],{},"// Error handling: Let errors propagate. Do not wrap individual calls\n",[708,716,717],{"class":710,"line":438},[708,718,719],{},"// in try/catch. The global handler catches everything.\n",[708,721,723],{"class":710,"line":722},3,[708,724,725],{"emptyLinePlaceholder":458},"\n",[708,727,729],{"class":710,"line":728},4,[708,730,731],{},"// CORRECT\n",[708,733,735],{"class":710,"line":734},5,[708,736,737],{},"async function getUser(id) {\n",[708,739,741],{"class":710,"line":740},6,[708,742,743],{},"  const user = await db.users.findById(id);\n",[708,745,747],{"class":710,"line":746},7,[708,748,749],{},"  return user;\n",[708,751,753],{"class":710,"line":752},8,[708,754,755],{},"}\n",[708,757,759],{"class":710,"line":758},9,[708,760,725],{"emptyLinePlaceholder":458},[708,762,764],{"class":710,"line":763},10,[708,765,766],{},"// WRONG\n",[708,768,770],{"class":710,"line":769},11,[708,771,737],{},[708,773,775],{"class":710,"line":774},12,[708,776,777],{},"  try {\n",[708,779,781],{"class":710,"line":780},13,[708,782,783],{},"    const user = await db.users.findById(id);\n",[708,785,787],{"class":710,"line":786},14,[708,788,789],{},"    return user;\n",[708,791,793],{"class":710,"line":792},15,[708,794,795],{},"  } catch (e) {\n",[708,797,799],{"class":710,"line":798},16,[708,800,801],{},"    logger.error(e);\n",[708,803,805],{"class":710,"line":804},17,[708,806,807],{},"    throw e;\n",[708,809,811],{"class":710,"line":810},18,[708,812,813],{},"  }\n",[708,815,817],{"class":710,"line":816},19,[708,818,755],{},[14,820,821],{},"The code example communicates instantly what three paragraphs of description fail to convey.",[666,823,825],{"id":824},"mistake-3-not-updating-it","Mistake 3: Not updating it",[14,827,828],{},"An AGENTS.md with stale table names, deprecated commands, or outdated architecture constraints is worse than no AGENTS.md. It actively misleads the agent.",[14,830,831],{},"Update your AGENTS.md in the same PR where conventions change. Set a quarterly review to remove stale guidance. A useful signal: when an agent repeatedly produces incorrect output, that's a gap in your AGENTS.md.",[35,833,835],{"id":834},"does-agentsmd-actually-work","Does AGENTS.md actually work?",[14,837,838],{},"This gets asked often enough to deserve a direct answer, and the honest one is: yes, but only the hand-written kind.",[14,840,841],{},"The skepticism is earned. Generic, LLM-generated AGENTS.md files reduce task success in 5 out of 8 tested settings and add 2.45-3.92 extra steps per task. If you asked an agent to write your AGENTS.md, ran it, and saw no improvement, that result is exactly what the research predicts. The file wasn't neutral. It made things worse.",[14,843,844],{},"What works is narrow: instructions that tell the agent something it could not have inferred from the codebase. Your package manager. Your test command with its exact flags. The one directory it must never touch. The convention your codebase follows that looks unusual to a model trained on everyone else's code.",[14,846,847],{},"The test for any line in your AGENTS.md: would a competent developer who had never seen this repo get this wrong? If no, delete the line. It is costing you context tokens to restate the model's defaults back to itself.",[35,849,851],{"id":850},"agentsmd-vs-claudemd-vs-cursorrules-which-do-you-need","AGENTS.md vs CLAUDE.md vs .cursorrules (which do you need?)",[14,853,854],{},"Here's the honest answer: start with AGENTS.md, add tool-specific files only if you need their unique features.",[14,856,857],{},[80,858],{"alt":859,"src":860},"The universal file and its specialist cousins: AGENTS.md is the universal core read by 30+ tools, while CLAUDE.md adds @imports for Claude Code and .cursorrules adds glob-based rules for Cursor.","/img/blog/agents-md-best-practices-file-comparison.jpg",[14,862,863,866],{},[17,864,865],{},"AGENTS.md"," has the broadest compatibility. 30+ tools read it natively. It's the universal format.",[14,868,869,872,873,876],{},[17,870,871],{},"CLAUDE.md"," is Claude Code-specific. Its unique feature is ",[49,874,875],{},"@imports"," that compose instructions from multiple files. If your team uses Claude Code exclusively and needs modular instruction files, add CLAUDE.md alongside AGENTS.md.",[14,878,879,882],{},[17,880,881],{},".cursorrules"," is Cursor-specific. Its unique feature is MDC frontmatter with glob patterns that activate different instructions for different file types. If your team uses Cursor and needs per-filetype rules, add .cursorrules.",[14,884,885],{},"90% of the content across all three files is identical. Build commands, architecture rules, testing conventions, and boundaries don't change per tool. A converter tool called rule-porter can translate between formats if needed.",[14,887,888],{},"Write AGENTS.md first. It's the single source of truth that every tool reads. Add CLAUDE.md or .cursorrules only for features that AGENTS.md can't express.",[35,890,892],{"id":891},"does-agentsmd-work-with-openai-codex","Does AGENTS.md work with OpenAI Codex?",[14,894,895],{},"Yes. Codex reads AGENTS.md natively, and the same file works across Codex, Claude Code, Cursor, and Gemini CLI without changes. That is the whole point of the convention.",[14,897,898],{},"Codex is worth calling out separately because its resolution rules are more layered than most tools. It builds an instruction chain by walking from the top down and concatenating at most one file per directory:",[900,901,902,907,913,916],"ol",{},[206,903,904,906],{},[49,905,294],{}," (your personal global file, applied across every project)",[206,908,909,912],{},[49,910,911],{},"\u003Cgit-root>/AGENTS.md"," (the repository file, committed and shared with your team)",[206,914,915],{},"Any AGENTS.md in intermediate directories on the path",[206,917,918],{},"The AGENTS.md in your current working directory",[14,920,921,922,924],{},"Files closer to where you are working take precedence over the ones above them. If you need a subdirectory to replace inherited instructions rather than add to them, use ",[49,923,287],{}," at that level. Codex rebuilds this chain on every run, so there is no cache to clear when you edit a file.",[14,926,927],{},"One practical warning. Codex executes the build and test commands from your AGENTS.md in its sandbox. A stale or wrong command doesn't produce a helpful error; the agent runs it, watches it fail, and works around it. Before you rely on any command in your AGENTS.md, run it verbatim in a fresh terminal. Copy the command that worked, not the one you remember writing.",[14,929,930,931,936],{},"Behaviour can differ between Codex CLI and Codex in ChatGPT, so check ",[222,932,935],{"href":933,"rel":934},"https://developers.openai.com/codex/guides/agents-md",[393],"OpenAI's AGENTS.md documentation"," if you depend on a specific precedence detail.",[35,938,940],{"id":939},"global-vs-directory-level-agentsmd","Global vs directory-level AGENTS.md",[14,942,943],{},"There are three scopes, and mixing them up is a common source of \"why is the agent ignoring my instructions.\"",[14,945,946,949,950,952],{},[17,947,948],{},"Global (personal)."," A file in your tool's config directory, such as ",[49,951,294],{},". It applies to every project you open. Use it for preferences that are about you rather than the project: how verbose you want explanations, whether you want the agent to ask before running destructive commands. It is not committed anywhere, so your teammates never see it.",[14,954,955,958],{},[17,956,957],{},"Repository root."," The file most people mean by \"AGENTS.md.\" Committed to the repo, shared by the whole team. Use it for build commands, code style, architecture constraints, testing conventions, and boundaries that apply everywhere in the project.",[14,960,961,964,965,968,969,972],{},[17,962,963],{},"Subdirectory."," Overrides or extends the root file for one directory. Use it when a directory genuinely has different rules: a package with its own build command, a ",[49,966,967],{},"/mobile"," directory on a different framework than ",[49,970,971],{},"/web",", a test suite that runs on a different runner.",[14,974,975],{},"Most projects need only the root file. Add subdirectory files when a directory has genuinely different rules, not to organise a root file that has grown too long. If your root AGENTS.md is too long, the fix is deleting lines, not distributing them.",[35,977,979],{"id":978},"should-agentsmd-be-committed-to-git","Should AGENTS.md be committed to git?",[14,981,982],{},"Yes. AGENTS.md belongs in version control alongside the code it describes. It is project documentation, not a personal preference file.",[14,984,985],{},"Commit it at the root of the repo. Every contributor and every AI tool reads it from there, and it gets reviewed in the same PR as the convention change that prompted it. If team members keep their own local AGENTS.md instead, the agent gets different instructions depending on who triggered it, which is a genuinely difficult class of bug to notice.",[14,987,988,989,991,992,995],{},"Two exceptions. Personal preferences that are about you rather than the project belong in your global file (",[49,990,294],{},"), not the repo. And if your instructions need to reference secrets or internal URLs, keep those in ",[49,993,994],{},".env"," or a gitignored file and reference them from AGENTS.md rather than inlining them.",[35,997,999],{"id":998},"security-agentsmd-is-a-prompt-injection-surface","Security: AGENTS.md is a prompt-injection surface",[14,1001,1002],{},"This is the part of the convention that gets least attention and deserves more.",[14,1004,1005,1006,1011],{},"NVIDIA's AI Red Team demonstrated an indirect AGENTS.md injection against OpenAI Codex, in which a ",[222,1007,1010],{"href":1008,"rel":1009},"https://developer.nvidia.com/blog/mitigating-indirect-agents-md-injection-attacks-in-agentic-environments/",[393],"malicious dependency hijacks the agent's behaviour"," by abusing instruction precedence. The attack requires an already-compromised dependency, so it is not a reason to panic about every repo you clone. But it illustrates something structural: agent instruction files are executable context, and they widen the supply-chain attack surface in a way that traditional prompt injection does not.",[14,1013,1014],{},"The practical mitigations are unglamorous:",[203,1016,1017,1020,1023,1026],{},[206,1018,1019],{},"Read the AGENTS.md in any repo you clone before you point an agent at it. It takes fifteen seconds and it is the entire defence for the common case.",[206,1021,1022],{},"Treat AGENTS.md the way you treat a Makefile or a postinstall script. It influences commands that run on your machine.",[206,1024,1025],{},"Review changes to AGENTS.md in code review with the same attention as changes to CI config. A one-line edit can redirect what an agent does across the whole repo.",[206,1027,1028],{},"Run agents in a sandbox where you can, so an instruction you missed has a smaller blast radius.",[35,1030,1032],{"id":1031},"beyond-coding-agentsmd-for-business-agents","Beyond coding: AGENTS.md for business agents",[14,1034,1035],{},"Here's where things get interesting. The AGENTS.md convention was born in coding repositories. But the same principle applies to any AI agent: give the agent structured, project-specific context at session start, and it performs better.",[14,1037,1038],{},"For business agents (support, sales, operations), the equivalent configuration includes:",[14,1040,1041],{},[80,1042],{"alt":1043,"src":1044},"Same passport, two different languages: a coding agent's AGENTS.md (stack, commands, code style, boundaries) maps to a business agent's config (identity, capabilities, constraints, trust level, escalation, output format).","/img/blog/agents-md-best-practices-business-agents.jpg",[203,1046,1047,1053,1059,1065,1071,1077],{},[206,1048,1049,1052],{},[17,1050,1051],{},"Identity:"," Who the agent is. Name, role, company, tone of voice.",[206,1054,1055,1058],{},[17,1056,1057],{},"Capabilities:"," What the agent can do. Which tools it has access to. Which integrations it can call.",[206,1060,1061,1064],{},[17,1062,1063],{},"Constraints:"," What the agent cannot do. Actions that require human approval. Topics it should escalate. Data it should never share.",[206,1066,1067,1070],{},[17,1068,1069],{},"Trust level:"," How much autonomy the agent has. Draft-only? Execute with approval? Fully autonomous within boundaries?",[206,1072,1073,1076],{},[17,1074,1075],{},"Escalation rules:"," When to hand off to a human. Sentiment triggers, confidence thresholds, sensitive categories.",[206,1078,1079,1082],{},[17,1080,1081],{},"Output format:"," How the agent should respond. Structured JSON? Natural language? Specific templates?",[14,1084,1085],{},"For coding agents, AGENTS.md is a file you write and maintain manually. For business agents, this configuration should be visual and managed through a platform.",[14,1087,1088],{},"This is exactly how BetterClaw's agent builder works. Every field that would go into a business AGENTS.md is a visual input in the builder. Identity, capabilities, constraints, trust levels (Intern, Specialist, Lead), escalation rules, output format. Version-controlled by the platform. No file management. No forgetting to update. Free plan with 1 agent and 100 credits a month, Basic at $19/month, and Pro at $49/month for 5 agents. BYOK with zero markup.",[35,1090,1092],{"id":1091},"the-annotated-template-copy-and-adapt","The annotated template (copy and adapt)",[14,1094,1095],{},"Here's a minimal, effective AGENTS.md template. Delete sections that don't apply. A shorter, accurate file outperforms a comprehensive, generic one.",[231,1097,1100],{"className":1098,"code":1099,"language":452,"meta":239,"style":239},"language-md shiki shiki-themes github-light","# Project Name\n\nNext.js 15 App Router, React 19, TypeScript 5.4, Tailwind CSS, Drizzle ORM, Bun.\n\n## Commands\n\nBuild: `bun run build`\nTest: `bun test`\nLint: `bun run lint --fix`\nSingle test: `bun test path/to/file.test.ts`\n\n## Code Style\n\nFunctional components only. Never class components.\nUse `const` exclusively. Never `var`, never `let` unless reassignment is needed.\nNamed exports only. Never default exports.\n\n// Component pattern:\nexport const UserCard = ({ name, email }: UserCardProps) => {\n  return \u003Cdiv className=\"p-4\">{name}\u003C/div>;\n};\n\n## Error Handling\n\nLet errors propagate. Do not wrap individual calls in try/catch.\nThe global error handler in middleware.ts catches everything.\n\n## Architecture\n\n/app         -> Routes and page components\n/components  -> Shared UI components\n/lib         -> Business logic and utilities\n/db          -> Database schema and migrations\n\nNever import from /app into /lib. Data flows one direction.\n\n## Boundaries\n\nNever modify files in /generated/.\nNever commit .env or any file containing secrets.\nThe /legacy/ module uses sync patterns. Do not convert to async.\n\n## Git\n\nSquash merge only.\nConventional commits: feat:, fix:, chore:, docs:.\nBranch format: type/short-description (e.g., feat/user-auth).\n",[49,1101,1102,1108,1112,1118,1122,1127,1131,1140,1148,1156,1164,1168,1173,1177,1182,1204,1209,1213,1218,1223,1229,1235,1240,1246,1251,1257,1263,1268,1274,1279,1285,1291,1297,1303,1308,1314,1319,1325,1330,1336,1342,1348,1353,1359,1364,1370,1376],{"__ignoreMap":239},[708,1103,1104],{"class":710,"line":711},[708,1105,1107],{"class":1106},"surfw","# Project Name\n",[708,1109,1110],{"class":710,"line":438},[708,1111,725],{"emptyLinePlaceholder":458},[708,1113,1114],{"class":710,"line":722},[708,1115,1117],{"class":1116},"sgsFI","Next.js 15 App Router, React 19, TypeScript 5.4, Tailwind CSS, Drizzle ORM, Bun.\n",[708,1119,1120],{"class":710,"line":728},[708,1121,725],{"emptyLinePlaceholder":458},[708,1123,1124],{"class":710,"line":734},[708,1125,1126],{"class":1106},"## Commands\n",[708,1128,1129],{"class":710,"line":740},[708,1130,725],{"emptyLinePlaceholder":458},[708,1132,1133,1136],{"class":710,"line":746},[708,1134,1135],{"class":1116},"Build: ",[708,1137,1139],{"class":1138},"sYu0t","`bun run build`\n",[708,1141,1142,1145],{"class":710,"line":752},[708,1143,1144],{"class":1116},"Test: ",[708,1146,1147],{"class":1138},"`bun test`\n",[708,1149,1150,1153],{"class":710,"line":758},[708,1151,1152],{"class":1116},"Lint: ",[708,1154,1155],{"class":1138},"`bun run lint --fix`\n",[708,1157,1158,1161],{"class":710,"line":763},[708,1159,1160],{"class":1116},"Single test: ",[708,1162,1163],{"class":1138},"`bun test path/to/file.test.ts`\n",[708,1165,1166],{"class":710,"line":769},[708,1167,725],{"emptyLinePlaceholder":458},[708,1169,1170],{"class":710,"line":774},[708,1171,1172],{"class":1106},"## Code Style\n",[708,1174,1175],{"class":710,"line":780},[708,1176,725],{"emptyLinePlaceholder":458},[708,1178,1179],{"class":710,"line":786},[708,1180,1181],{"class":1116},"Functional components only. Never class components.\n",[708,1183,1184,1187,1190,1193,1196,1198,1201],{"class":710,"line":792},[708,1185,1186],{"class":1116},"Use ",[708,1188,1189],{"class":1138},"`const`",[708,1191,1192],{"class":1116}," exclusively. Never ",[708,1194,1195],{"class":1138},"`var`",[708,1197,118],{"class":1116},[708,1199,1200],{"class":1138},"`let`",[708,1202,1203],{"class":1116}," unless reassignment is needed.\n",[708,1205,1206],{"class":710,"line":798},[708,1207,1208],{"class":1116},"Named exports only. Never default exports.\n",[708,1210,1211],{"class":710,"line":804},[708,1212,725],{"emptyLinePlaceholder":458},[708,1214,1215],{"class":710,"line":810},[708,1216,1217],{"class":1116},"// Component pattern:\n",[708,1219,1220],{"class":710,"line":816},[708,1221,1222],{"class":1116},"export const UserCard = ({ name, email }: UserCardProps) => {\n",[708,1224,1226],{"class":710,"line":1225},20,[708,1227,1228],{"class":1116},"  return \u003Cdiv className=\"p-4\">{name}\u003C/div>;\n",[708,1230,1232],{"class":710,"line":1231},21,[708,1233,1234],{"class":1116},"};\n",[708,1236,1238],{"class":710,"line":1237},22,[708,1239,725],{"emptyLinePlaceholder":458},[708,1241,1243],{"class":710,"line":1242},23,[708,1244,1245],{"class":1106},"## Error Handling\n",[708,1247,1249],{"class":710,"line":1248},24,[708,1250,725],{"emptyLinePlaceholder":458},[708,1252,1254],{"class":710,"line":1253},25,[708,1255,1256],{"class":1116},"Let errors propagate. Do not wrap individual calls in try/catch.\n",[708,1258,1260],{"class":710,"line":1259},26,[708,1261,1262],{"class":1116},"The global error handler in middleware.ts catches everything.\n",[708,1264,1266],{"class":710,"line":1265},27,[708,1267,725],{"emptyLinePlaceholder":458},[708,1269,1271],{"class":710,"line":1270},28,[708,1272,1273],{"class":1106},"## Architecture\n",[708,1275,1277],{"class":710,"line":1276},29,[708,1278,725],{"emptyLinePlaceholder":458},[708,1280,1282],{"class":710,"line":1281},30,[708,1283,1284],{"class":1116},"/app         -> Routes and page components\n",[708,1286,1288],{"class":710,"line":1287},31,[708,1289,1290],{"class":1116},"/components  -> Shared UI components\n",[708,1292,1294],{"class":710,"line":1293},32,[708,1295,1296],{"class":1116},"/lib         -> Business logic and utilities\n",[708,1298,1300],{"class":710,"line":1299},33,[708,1301,1302],{"class":1116},"/db          -> Database schema and migrations\n",[708,1304,1306],{"class":710,"line":1305},34,[708,1307,725],{"emptyLinePlaceholder":458},[708,1309,1311],{"class":710,"line":1310},35,[708,1312,1313],{"class":1116},"Never import from /app into /lib. Data flows one direction.\n",[708,1315,1317],{"class":710,"line":1316},36,[708,1318,725],{"emptyLinePlaceholder":458},[708,1320,1322],{"class":710,"line":1321},37,[708,1323,1324],{"class":1106},"## Boundaries\n",[708,1326,1328],{"class":710,"line":1327},38,[708,1329,725],{"emptyLinePlaceholder":458},[708,1331,1333],{"class":710,"line":1332},39,[708,1334,1335],{"class":1116},"Never modify files in /generated/.\n",[708,1337,1339],{"class":710,"line":1338},40,[708,1340,1341],{"class":1116},"Never commit .env or any file containing secrets.\n",[708,1343,1345],{"class":710,"line":1344},41,[708,1346,1347],{"class":1116},"The /legacy/ module uses sync patterns. Do not convert to async.\n",[708,1349,1351],{"class":710,"line":1350},42,[708,1352,725],{"emptyLinePlaceholder":458},[708,1354,1356],{"class":710,"line":1355},43,[708,1357,1358],{"class":1106},"## Git\n",[708,1360,1362],{"class":710,"line":1361},44,[708,1363,725],{"emptyLinePlaceholder":458},[708,1365,1367],{"class":710,"line":1366},45,[708,1368,1369],{"class":1116},"Squash merge only.\n",[708,1371,1373],{"class":710,"line":1372},46,[708,1374,1375],{"class":1116},"Conventional commits: feat:, fix:, chore:, docs:.\n",[708,1377,1379],{"class":710,"line":1378},47,[708,1380,1381],{"class":1116},"Branch format: type/short-description (e.g., feat/user-auth).\n",[14,1383,1384],{},"That's under 50 lines. It communicates everything an agent needs to work correctly in this codebase. Every line is specific. Every section has a reason to exist.",[35,1386,1388],{"id":1387},"agentsmd-examples-three-files-for-three-project-types","AGENTS.md examples: three files for three project types",[14,1390,1391],{},"The template above is deliberately generic. Real files are shorter and stranger than templates, because they only contain the things that specific project's agents kept getting wrong. These three are representative examples written to show that range, not copies of any named repository's file.",[14,1393,1394],{},[17,1395,1396],{},"Example 1: a Next.js web app (12 lines)",[231,1398,1400],{"className":1098,"code":1399,"language":452,"meta":239,"style":239},"# Storefront\n\nNext.js 15 App Router, TypeScript, Tailwind, Bun.\n\nBuild: `bun run build` | Test: `bun test` | Lint: `bun run lint --fix`\n\nServer Components by default. Add `'use client'` only for event handlers or hooks.\nNever fetch in a Client Component. Fetch in the page, pass data down as props.\nNamed exports only.\n\nNever edit `/app/generated/`. It is regenerated on every build.\nNever add a dependency without asking. This bundle is size-budgeted.\n",[49,1401,1402,1407,1411,1416,1420,1438,1442,1453,1458,1463,1467,1478],{"__ignoreMap":239},[708,1403,1404],{"class":710,"line":711},[708,1405,1406],{"class":1106},"# Storefront\n",[708,1408,1409],{"class":710,"line":438},[708,1410,725],{"emptyLinePlaceholder":458},[708,1412,1413],{"class":710,"line":722},[708,1414,1415],{"class":1116},"Next.js 15 App Router, TypeScript, Tailwind, Bun.\n",[708,1417,1418],{"class":710,"line":728},[708,1419,725],{"emptyLinePlaceholder":458},[708,1421,1422,1424,1427,1430,1433,1436],{"class":710,"line":734},[708,1423,1135],{"class":1116},[708,1425,1426],{"class":1138},"`bun run build`",[708,1428,1429],{"class":1116}," | Test: ",[708,1431,1432],{"class":1138},"`bun test`",[708,1434,1435],{"class":1116}," | Lint: ",[708,1437,1155],{"class":1138},[708,1439,1440],{"class":710,"line":740},[708,1441,725],{"emptyLinePlaceholder":458},[708,1443,1444,1447,1450],{"class":710,"line":746},[708,1445,1446],{"class":1116},"Server Components by default. Add ",[708,1448,1449],{"class":1138},"`'use client'`",[708,1451,1452],{"class":1116}," only for event handlers or hooks.\n",[708,1454,1455],{"class":710,"line":752},[708,1456,1457],{"class":1116},"Never fetch in a Client Component. Fetch in the page, pass data down as props.\n",[708,1459,1460],{"class":710,"line":758},[708,1461,1462],{"class":1116},"Named exports only.\n",[708,1464,1465],{"class":710,"line":763},[708,1466,725],{"emptyLinePlaceholder":458},[708,1468,1469,1472,1475],{"class":710,"line":769},[708,1470,1471],{"class":1116},"Never edit ",[708,1473,1474],{"class":1138},"`/app/generated/`",[708,1476,1477],{"class":1116},". It is regenerated on every build.\n",[708,1479,1480],{"class":710,"line":774},[708,1481,1482],{"class":1116},"Never add a dependency without asking. This bundle is size-budgeted.\n",[14,1484,1485,1486,1489],{},"What it gets right: the ",[49,1487,1488],{},"'use client'"," rule is the one thing an agent reliably gets wrong in App Router projects, and it is stated as a rule with its exception, in one line.",[14,1491,1492],{},[17,1493,1494],{},"Example 2: a Python FastAPI backend (16 lines)",[231,1496,1498],{"className":1098,"code":1497,"language":452,"meta":239,"style":239},"# Billing API\n\nPython 3.12, FastAPI, SQLAlchemy 2.0 (async), Alembic, uv.\n\nInstall: `uv sync` | Run: `uv run uvicorn app.main:app --reload`\nTest: `uv run pytest -x` | Single test: `uv run pytest tests/test_invoices.py::test_name`\n\nAll DB access is async. Never use the sync Session. Never call `.commit()` in a\nroute handler; the dependency in `app/deps.py` handles the transaction boundary.\n\nPydantic models live in `app/schemas/`. SQLAlchemy models live in `app/models/`.\nNever import a SQLAlchemy model into a route signature.\n\nSchema changes require a migration: `uv run alembic revision --autogenerate -m \"...\"`.\nNever edit an existing migration that has been merged.\n\nMoney is `Decimal`, never `float`. Amounts are stored in minor units (cents).\n",[49,1499,1500,1505,1509,1514,1518,1532,1545,1549,1560,1571,1575,1592,1597,1601,1611,1616,1620],{"__ignoreMap":239},[708,1501,1502],{"class":710,"line":711},[708,1503,1504],{"class":1106},"# Billing API\n",[708,1506,1507],{"class":710,"line":438},[708,1508,725],{"emptyLinePlaceholder":458},[708,1510,1511],{"class":710,"line":722},[708,1512,1513],{"class":1116},"Python 3.12, FastAPI, SQLAlchemy 2.0 (async), Alembic, uv.\n",[708,1515,1516],{"class":710,"line":728},[708,1517,725],{"emptyLinePlaceholder":458},[708,1519,1520,1523,1526,1529],{"class":710,"line":734},[708,1521,1522],{"class":1116},"Install: ",[708,1524,1525],{"class":1138},"`uv sync`",[708,1527,1528],{"class":1116}," | Run: ",[708,1530,1531],{"class":1138},"`uv run uvicorn app.main:app --reload`\n",[708,1533,1534,1536,1539,1542],{"class":710,"line":740},[708,1535,1144],{"class":1116},[708,1537,1538],{"class":1138},"`uv run pytest -x`",[708,1540,1541],{"class":1116}," | Single test: ",[708,1543,1544],{"class":1138},"`uv run pytest tests/test_invoices.py::test_name`\n",[708,1546,1547],{"class":710,"line":746},[708,1548,725],{"emptyLinePlaceholder":458},[708,1550,1551,1554,1557],{"class":710,"line":752},[708,1552,1553],{"class":1116},"All DB access is async. Never use the sync Session. Never call ",[708,1555,1556],{"class":1138},"`.commit()`",[708,1558,1559],{"class":1116}," in a\n",[708,1561,1562,1565,1568],{"class":710,"line":758},[708,1563,1564],{"class":1116},"route handler; the dependency in ",[708,1566,1567],{"class":1138},"`app/deps.py`",[708,1569,1570],{"class":1116}," handles the transaction boundary.\n",[708,1572,1573],{"class":710,"line":763},[708,1574,725],{"emptyLinePlaceholder":458},[708,1576,1577,1580,1583,1586,1589],{"class":710,"line":769},[708,1578,1579],{"class":1116},"Pydantic models live in ",[708,1581,1582],{"class":1138},"`app/schemas/`",[708,1584,1585],{"class":1116},". SQLAlchemy models live in ",[708,1587,1588],{"class":1138},"`app/models/`",[708,1590,1591],{"class":1116},".\n",[708,1593,1594],{"class":710,"line":774},[708,1595,1596],{"class":1116},"Never import a SQLAlchemy model into a route signature.\n",[708,1598,1599],{"class":710,"line":780},[708,1600,725],{"emptyLinePlaceholder":458},[708,1602,1603,1606,1609],{"class":710,"line":786},[708,1604,1605],{"class":1116},"Schema changes require a migration: ",[708,1607,1608],{"class":1138},"`uv run alembic revision --autogenerate -m \"...\"`",[708,1610,1591],{"class":1116},[708,1612,1613],{"class":710,"line":792},[708,1614,1615],{"class":1116},"Never edit an existing migration that has been merged.\n",[708,1617,1618],{"class":710,"line":798},[708,1619,725],{"emptyLinePlaceholder":458},[708,1621,1622,1625,1628,1630,1633],{"class":710,"line":804},[708,1623,1624],{"class":1116},"Money is ",[708,1626,1627],{"class":1138},"`Decimal`",[708,1629,118],{"class":1116},[708,1631,1632],{"class":1138},"`float`",[708,1634,1635],{"class":1116},". Amounts are stored in minor units (cents).\n",[14,1637,1638],{},"What it gets right: the money rule. It is one line, it is unambiguous, and it prevents a class of bug that is expensive to find later.",[14,1640,1641],{},[17,1642,1643],{},"Example 3: a monorepo (22 lines)",[231,1645,1647],{"className":1098,"code":1646,"language":452,"meta":239,"style":239},"# Platform monorepo\n\npnpm workspaces + Turborepo. Node 22.\n\napps/web    -> Next.js 15 storefront\napps/admin  -> Vite + React admin panel\npackages/ui -> Shared component library\npackages/db -> Drizzle schema and client\n\nAlways run commands from the repo root: `pnpm turbo build --filter=web`.\nNever `cd` into a package and run `pnpm install` there.\n\nTest: `pnpm turbo test` | Single app: `pnpm turbo test --filter=admin`\n\napps/* may import from packages/*. packages/* must never import from apps/*.\npackages/ui must never import from packages/db. UI takes data as props.\n\nAdding a dependency to a package: `pnpm add \u003Cpkg> --filter=\u003Cpackage-name>`.\n\nEach app has its own AGENTS.md with framework-specific rules. This file covers\nthe workspace-level rules only.\n",[49,1648,1649,1654,1658,1663,1667,1672,1677,1682,1687,1691,1701,1718,1722,1735,1739,1751,1756,1760,1770,1774,1779],{"__ignoreMap":239},[708,1650,1651],{"class":710,"line":711},[708,1652,1653],{"class":1106},"# Platform monorepo\n",[708,1655,1656],{"class":710,"line":438},[708,1657,725],{"emptyLinePlaceholder":458},[708,1659,1660],{"class":710,"line":722},[708,1661,1662],{"class":1116},"pnpm workspaces + Turborepo. Node 22.\n",[708,1664,1665],{"class":710,"line":728},[708,1666,725],{"emptyLinePlaceholder":458},[708,1668,1669],{"class":710,"line":734},[708,1670,1671],{"class":1116},"apps/web    -> Next.js 15 storefront\n",[708,1673,1674],{"class":710,"line":740},[708,1675,1676],{"class":1116},"apps/admin  -> Vite + React admin panel\n",[708,1678,1679],{"class":710,"line":746},[708,1680,1681],{"class":1116},"packages/ui -> Shared component library\n",[708,1683,1684],{"class":710,"line":752},[708,1685,1686],{"class":1116},"packages/db -> Drizzle schema and client\n",[708,1688,1689],{"class":710,"line":758},[708,1690,725],{"emptyLinePlaceholder":458},[708,1692,1693,1696,1699],{"class":710,"line":763},[708,1694,1695],{"class":1116},"Always run commands from the repo root: ",[708,1697,1698],{"class":1138},"`pnpm turbo build --filter=web`",[708,1700,1591],{"class":1116},[708,1702,1703,1706,1709,1712,1715],{"class":710,"line":769},[708,1704,1705],{"class":1116},"Never ",[708,1707,1708],{"class":1138},"`cd`",[708,1710,1711],{"class":1116}," into a package and run ",[708,1713,1714],{"class":1138},"`pnpm install`",[708,1716,1717],{"class":1116}," there.\n",[708,1719,1720],{"class":710,"line":774},[708,1721,725],{"emptyLinePlaceholder":458},[708,1723,1724,1726,1729,1732],{"class":710,"line":780},[708,1725,1144],{"class":1116},[708,1727,1728],{"class":1138},"`pnpm turbo test`",[708,1730,1731],{"class":1116}," | Single app: ",[708,1733,1734],{"class":1138},"`pnpm turbo test --filter=admin`\n",[708,1736,1737],{"class":710,"line":786},[708,1738,725],{"emptyLinePlaceholder":458},[708,1740,1741,1744,1748],{"class":710,"line":792},[708,1742,1743],{"class":1116},"apps/* may import from packages/",[708,1745,1747],{"class":1746},"sLX6V","*. packages/*",[708,1749,1750],{"class":1116}," must never import from apps/*.\n",[708,1752,1753],{"class":710,"line":798},[708,1754,1755],{"class":1116},"packages/ui must never import from packages/db. UI takes data as props.\n",[708,1757,1758],{"class":710,"line":804},[708,1759,725],{"emptyLinePlaceholder":458},[708,1761,1762,1765,1768],{"class":710,"line":810},[708,1763,1764],{"class":1116},"Adding a dependency to a package: ",[708,1766,1767],{"class":1138},"`pnpm add \u003Cpkg> --filter=\u003Cpackage-name>`",[708,1769,1591],{"class":1116},[708,1771,1772],{"class":710,"line":816},[708,1773,725],{"emptyLinePlaceholder":458},[708,1775,1776],{"class":710,"line":1225},[708,1777,1778],{"class":1116},"Each app has its own AGENTS.md with framework-specific rules. This file covers\n",[708,1780,1781],{"class":710,"line":1231},[708,1782,1783],{"class":1116},"the workspace-level rules only.\n",[14,1785,1786],{},"What it gets right: the import direction rules, and the last line, which tells the agent that more specific instructions exist further down the tree.",[14,1788,1789],{},"The common thread across all three: every line is a rule an agent would break without being told, written as a constraint rather than an explanation. None of them describe what the project is for.",[14,1791,1792],{},"Gartner projects 40% of enterprise applications will embed AI agents by end of 2026. The teams that invest 30 minutes in a good AGENTS.md today will save hours of agent correction every week. The teams that skip it will keep wondering why their agent \"doesn't follow instructions.\"",[14,1794,1795],{},[80,1796],{"alt":1797,"src":1798},"Treat it like a bonsai, not an encyclopedia: start small, prune stale guidance, and add a section only when an agent consistently gets something wrong. A shorter, accurate file beats a comprehensive, generic one.","/img/blog/agents-md-best-practices-bonsai.jpg",[14,1800,1801],{},"The best AGENTS.md file is the one your team actually maintains. Not the one that comprehensively documents every edge case and is outdated by next sprint.",[14,1803,1804],{},"Start with 30 lines. Add a section when an agent consistently gets something wrong. Remove a section when the convention changes. Treat it like code, not documentation.",[14,1806,1807],{},"And if your agents are business agents, not coding agents, this entire configuration belongs in a visual builder, not a markdown file. Give BetterClaw a look. Free plan with 1 agent and 100 credits a month, Basic at $19/month, and Pro at $49/month for 5 agents. Agent configuration through the UI. No files to forget to update.",[35,1809,403],{"id":402},[666,1811,1813],{"id":1812},"what-is-an-agentsmd-file","What is an AGENTS.md file?",[14,1815,1816],{},"AGENTS.md is a Markdown file placed at the root of a code repository that provides AI coding agents with project-specific instructions: build commands, code style conventions, architecture constraints, testing procedures, and boundaries. It's read natively by 30+ AI tools including Claude Code, GitHub Copilot, Cursor, OpenAI Codex, and Gemini CLI. Over 60,000 repositories have adopted it, and it's now stewarded by the Agentic AI Foundation under the Linux Foundation.",[666,1818,1820],{"id":1819},"how-does-agentsmd-compare-to-claudemd-and-cursorrules","How does AGENTS.md compare to CLAUDE.md and .cursorrules?",[14,1822,1823,1824,1826],{},"AGENTS.md has the broadest compatibility (30+ tools read it). CLAUDE.md adds Claude-specific features like ",[49,1825,875],{}," for modular instruction files. .cursorrules adds Cursor-specific features like glob-based auto-attach rules. 90% of the content is identical across all three. Start with AGENTS.md as your universal source of truth, and add tool-specific files only for features AGENTS.md can't express. A converter tool (rule-porter) can translate between formats.",[666,1828,1830],{"id":1829},"how-long-should-an-agentsmd-file-be","How long should an AGENTS.md file be?",[14,1832,1833],{},"Under 150 lines. Research across 2,500+ repositories found that files beyond 150 lines deliver diminishing returns and can increase inference costs 20-23% without improving agent performance. The technical maximum is 32 KiB. Shorter, accurate files consistently outperform comprehensive, generic ones. Start with 30-50 lines covering stack, build commands, code style (with examples), and boundaries. Add sections only when an agent consistently makes a specific mistake.",[666,1835,1837],{"id":1836},"should-i-use-an-llm-to-generate-my-agentsmd","Should I use an LLM to generate my AGENTS.md?",[14,1839,1840],{},"No. Research found that LLM-generated AGENTS.md files reduce task success in 5 out of 8 tested settings and add 2.45-3.92 extra steps per task. LLMs generate generic, verbose instructions that state things agents already know (\"write clean code,\" \"follow best practices\"). Write your AGENTS.md by hand with only the conventions specific to your project that an agent wouldn't know without being told. One real code snippet is worth more than three paragraphs of description.",[666,1842,1844],{"id":1843},"can-i-use-the-same-agentsmd-for-codex-and-claude-code","Can I use the same AGENTS.md for Codex and Claude Code?",[14,1846,1847,1848,1850,1851,1853],{},"Yes. One AGENTS.md serves both, plus Cursor, Gemini CLI, and 30+ other tools, with no per-tool changes. Codex reads it natively. Codex builds an instruction chain from your global ",[49,1849,294],{},", then the repository root file, then any AGENTS.md in intermediate directories, then the one in your current working directory, with closer files taking precedence. Use ",[49,1852,287],{}," in a subdirectory to replace inherited instructions instead of adding to them. Codex also executes the build and test commands in your AGENTS.md, so verify each one runs in a fresh terminal before relying on it. Behaviour can differ between Codex CLI and Codex in ChatGPT.",[666,1855,1857],{"id":1856},"do-i-commit-agentsmd-or-add-it-to-gitignore","Do I commit AGENTS.md or add it to .gitignore?",[14,1859,1860,1861,1863,1864,1866],{},"Commit it. AGENTS.md is project documentation and belongs in version control at the repo root, so every contributor and every AI tool reads the same instructions. If team members keep local-only copies, the agent gets different instructions depending on who triggered it. Keep personal preferences in your tool's global file (such as ",[49,1862,294],{},") instead, and never inline secrets or internal URLs; reference them from ",[49,1865,994],{}," or a gitignored file.",[666,1868,1870],{"id":1869},"can-agentsmd-principles-apply-to-business-agents-not-just-coding-agents","Can AGENTS.md principles apply to business agents, not just coding agents?",[14,1872,1873],{},"Yes. The core principle (give the agent structured, specific context about identity, capabilities, constraints, and boundaries) applies to any AI agent. For business agents, the equivalent sections are identity, capabilities, constraints, trust levels, escalation rules, and output format. The difference is that business agent configuration belongs in a visual builder (like BetterClaw) rather than a markdown file, since business agents don't operate from a code repository.",[1875,1876,1877],"style",{},"html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html pre.shiki code .surfw, html code.shiki .surfw{--shiki-default:#005CC5;--shiki-default-font-weight:bold}html pre.shiki code .sgsFI, html code.shiki .sgsFI{--shiki-default:#24292E}html pre.shiki code .sYu0t, html code.shiki .sYu0t{--shiki-default:#005CC5}html pre.shiki code .sLX6V, html code.shiki .sLX6V{--shiki-default:#24292E;--shiki-default-font-style:italic}",{"title":239,"searchDepth":438,"depth":438,"links":1879},[1880,1881,1882,1887,1888,1889,1890,1891,1892,1893,1894,1895,1896],{"id":518,"depth":438,"text":519},{"id":635,"depth":438,"text":636},{"id":657,"depth":438,"text":658,"children":1883},[1884,1885,1886],{"id":668,"depth":722,"text":669},{"id":686,"depth":722,"text":687},{"id":824,"depth":722,"text":825},{"id":834,"depth":438,"text":835},{"id":850,"depth":438,"text":851},{"id":891,"depth":438,"text":892},{"id":939,"depth":438,"text":940},{"id":978,"depth":438,"text":979},{"id":998,"depth":438,"text":999},{"id":1031,"depth":438,"text":1032},{"id":1091,"depth":438,"text":1092},{"id":1387,"depth":438,"text":1388},{"id":402,"depth":438,"text":403,"children":1897},[1898,1899,1900,1901,1902,1903,1904],{"id":1812,"depth":722,"text":1813},{"id":1819,"depth":722,"text":1820},{"id":1829,"depth":722,"text":1830},{"id":1836,"depth":722,"text":1837},{"id":1843,"depth":722,"text":1844},{"id":1856,"depth":722,"text":1857},{"id":1869,"depth":722,"text":1870},"2026-06-11","How to write an AGENTS.md file that AI coding agents actually follow. Template, real examples, size limits, Codex setup, and the mistakes to avoid.","/img/blog/agents-md-best-practices.jpg",{},"15 min read",{"title":478,"description":1906},"AGENTS.md Best Practices: Template, Examples, Guide","blog/agents-md-best-practices",[466,1914,1915,1916,1917,1918,1919,1920,1921,1922],"agents md file","agents md template","agent configuration file","agents md format","agents md guide","agents md example","agents md size","codex agents md","global agents md","2026-09-09","xV34gNnJLcYQMI4bs9m-5J-PulE7Ge3zvgxIZYwi53Y",{"id":1926,"title":1927,"author":1928,"body":1929,"category":449,"date":1905,"description":2251,"extension":452,"featured":453,"hideToc":453,"image":2252,"imageHeight":473,"imageWidth":473,"meta":2253,"navigation":458,"path":2254,"readingTime":2255,"redirected":453,"seo":2256,"seoTitle":2257,"stem":2258,"tags":2259,"updatedDate":1905,"__hash__":2266},"blog/blog/ai-agent-human-approval-guardrails.md","AI Agent Guardrails: How to Add Human Approval Without Killing Speed",{"name":7,"role":8,"avatar":9},{"type":11,"value":1930,"toc":2231},[1931,1934,1937,1940,1943,1946,1949,1952,1956,1962,1968,1971,1976,1982,1986,1989,1992,1995,1998,2002,2005,2008,2011,2015,2018,2024,2030,2036,2042,2045,2049,2052,2055,2058,2062,2065,2068,2074,2080,2086,2089,2093,2096,2102,2108,2114,2120,2123,2126,2130,2133,2139,2145,2151,2157,2160,2163,2167,2173,2176,2179,2182,2185,2188,2191,2194,2196,2200,2203,2207,2210,2214,2217,2221,2224,2228],[14,1932,1933],{},"Fully autonomous agents are fast and terrifying. Fully supervised agents are safe and useless. Here's the architecture that gives you both.",[14,1935,1936],{},"Our support agent sent a refund email to a customer. Without asking anyone. $487. Gone.",[14,1938,1939],{},"The agent was correct. The customer qualified for the refund. The policy was clear. The response was well-written.",[14,1941,1942],{},"But nobody on the team knew it happened until the customer replied with a thank-you email. Our finance lead walked into Monday morning with a transaction she didn't authorize, processed by a system she didn't know could authorize transactions.",[14,1944,1945],{},"That's the moment we added human approval gates.",[14,1947,1948],{},"Not because the agent was wrong. Because the right action, taken without oversight, eroded trust more than the wrong action would have. AI agent human approval isn't about catching mistakes. It's about maintaining the trust that keeps your team willing to let agents do more over time.",[14,1950,1951],{},"Here's how to add approval gates without turning your agent into a chatbot that asks permission to breathe.",[35,1953,1955],{"id":1954},"the-speed-vs-safety-tradeoff-and-why-both-extremes-fail","The speed vs safety tradeoff (and why both extremes fail)",[14,1957,1958,1961],{},[17,1959,1960],{},"Fully autonomous:"," The agent acts on everything without asking. Fast. Efficient. Also terrifying. One hallucinated tool call, one misinterpreted instruction, one edge case nobody anticipated, and the agent takes an action you can't undo. Meta's Summer Yue watched her agent mass-delete emails while ignoring stop commands. That's the fully autonomous failure mode.",[14,1963,1964,1967],{},[17,1965,1966],{},"Fully supervised:"," The agent drafts everything and waits for human approval before every action. Safe. Predictable. Also useless. If a human has to review and approve every single agent action, you haven't automated anything. You've added a middleman between the human and the task.",[14,1969,1970],{},"The answer is neither extreme. It's tiered autonomy: the agent acts autonomously on routine, low-risk tasks and pauses for human approval on high-risk actions. The boundary between \"auto-approve\" and \"wait for human\" is the entire engineering problem.",[54,1972,1973],{},[14,1974,1975],{},"The goal isn't \"should this agent need approval?\" The goal is \"which specific actions need approval, and which can the agent handle alone?\" Draw the line at the action level, not the agent level.",[14,1977,1978],{},[80,1979],{"alt":1980,"src":1981},"The three-tier approval highway: Tier 1 auto-approves routine read-only actions, Tier 2 queues medium-risk actions for human review, and Tier 3 blocks irreversible high-impact actions until a human approves.","/img/blog/ai-agent-human-approval-guardrails-three-tiers.jpg",[35,1983,1985],{"id":1984},"tier-1-auto-approve-the-80-that-should-just-happen","Tier 1: Auto-approve (the 80% that should just happen)",[14,1987,1988],{},"Most of what your agent does is read-only or low-impact. Reading emails. Classifying tickets. Looking up customer data. Drafting responses. Summarizing documents. Querying databases.",[14,1990,1991],{},"These actions should execute immediately with zero approval gate. If you make your agent ask permission to read an email, you've killed the value proposition.",[14,1993,1994],{},"The rule: if the action is reversible, read-only, or internal-only, auto-approve it. Nobody needs to approve a CRM lookup. Nobody needs to approve a draft that hasn't been sent yet.",[14,1996,1997],{},"Most teams start by requiring approval on everything and gradually moving actions to auto-approve as trust builds. This is backwards. Start by auto-approving everything that's obviously safe and add approval gates only to the specific actions that need them.",[35,1999,2001],{"id":2000},"tier-2-queue-for-review-the-15-that-needs-a-quick-check","Tier 2: Queue for review (the 15% that needs a quick check)",[14,2003,2004],{},"These are actions with moderate impact that the agent handles correctly 95% of the time but where the 5% failure case matters.",[14,2006,2007],{},"Sending an email to a customer. Updating a CRM record. Applying a discount code. Posting to a public channel. Scheduling a meeting on someone's calendar.",[14,2009,2010],{},"The agent drafts the action and queues it for human review. The human gets a notification (Slack, email, or dashboard), reviews the draft, and approves or rejects. If approved, the agent executes. If rejected, the agent logs the feedback.",[666,2012,2014],{"id":2013},"designing-the-approval-channel","Designing the approval channel",[14,2016,2017],{},"Where the approval notification goes matters more than most people think.",[14,2019,2020],{},[80,2021],{"alt":2022,"src":2023},"Three ways to deliver approval requests: Slack/Teams notifications for real-time teams (2-15 min), email digests for batch review (30-60 min), and a dashboard queue for high-volume teams (1-4 hours).","/img/blog/ai-agent-human-approval-guardrails-approval-channels.jpg",[14,2025,2026,2029],{},[17,2027,2028],{},"Slack/Teams notification:"," Best for real-time teams. The agent posts a message with the proposed action, a summary of why, and approve/reject buttons. Approval latency: 2-15 minutes during business hours.",[14,2031,2032,2035],{},[17,2033,2034],{},"Email digest:"," Best for batch review. The agent collects queued actions and sends a summary every 30 minutes or every hour. The reviewer approves or rejects in bulk. Approval latency: 30-60 minutes.",[14,2037,2038,2041],{},[17,2039,2040],{},"Dashboard queue:"," Best for high-volume teams. A dedicated approval dashboard shows all pending actions, sorted by priority. Reviewers work through the queue during scheduled review windows. Approval latency: 1-4 hours.",[14,2043,2044],{},"Pick based on your team's workflow. A 5-person startup that lives in Slack should use Slack notifications. A 50-person operations team should use a dashboard queue.",[35,2046,2048],{"id":2047},"tier-3-block-until-approved-the-5-you-cant-undo","Tier 3: Block until approved (the 5% you can't undo)",[14,2050,2051],{},"These are actions with irreversible or high-financial-impact consequences. Processing refunds. Deleting records. Sending external communications with legal implications. Making API calls that trigger financial transactions.",[14,2053,2054],{},"For Tier 3, the agent stops completely and waits for explicit human approval. No timeout. No auto-approve after 30 minutes. The action does not happen until a human says yes.",[14,2056,2057],{},"This sounds restrictive. In practice, Tier 3 actions are rare. If your agent handles 200 tasks per day and 5% are Tier 3, that's 10 approval requests. Your team reviews 10 items per day. That's manageable. The other 190 tasks happen instantly.",[666,2059,2061],{"id":2060},"the-timeout-problem","The timeout problem",[14,2063,2064],{},"Tier 2 needs a timeout. What happens if the reviewer is in a meeting, on vacation, or simply doesn't see the notification?",[14,2066,2067],{},"Three options:",[14,2069,2070,2073],{},[17,2071,2072],{},"Auto-approve after timeout."," The action executes if nobody rejects it within 30 minutes. This is the fastest but riskiest. Only appropriate for Tier 2 actions where the failure case is mild.",[14,2075,2076,2079],{},[17,2077,2078],{},"Escalate after timeout."," If the primary reviewer doesn't respond within 30 minutes, the approval request escalates to the next person in the chain (team lead, then manager). This is the most common pattern for business-critical agents.",[14,2081,2082,2085],{},[17,2083,2084],{},"Auto-reject after timeout."," The action is cancelled if nobody approves it. The customer or process waits. This is the safest but creates the most friction. Use for actions where doing nothing is better than doing the wrong thing.",[14,2087,2088],{},"On most teams, escalation is the right default. Auto-approve timeouts sound efficient until the one time it auto-approves a $5,000 refund because the reviewer was at lunch.",[35,2090,2092],{"id":2091},"the-escalation-chain-who-approves-what-and-when","The escalation chain (who approves what, and when)",[14,2094,2095],{},"A well-designed escalation chain has three levels:",[14,2097,2098],{},[80,2099],{"alt":2100,"src":2101},"The approval escalation plan — know this before 2 AM: Level 1 is the agent's assigned reviewer, Level 2 is the team lead after a timeout, and Level 3 is a catch-all admin or on-call rotation.","/img/blog/ai-agent-human-approval-guardrails-escalation.jpg",[14,2103,2104,2107],{},[17,2105,2106],{},"Level 1: The agent's assigned reviewer."," This is the person or team responsible for the agent's domain. A support agent's reviewer is the support lead. A sales agent's reviewer is the sales manager.",[14,2109,2110,2113],{},[17,2111,2112],{},"Level 2: The team lead or department head."," If Level 1 doesn't respond within the timeout window (15-30 minutes), the request escalates.",[14,2115,2116,2119],{},[17,2117,2118],{},"Level 3: A catch-all admin or on-call."," If Level 2 doesn't respond, the request goes to someone who is always monitoring. For critical systems, this should be a PagerDuty-style rotation.",[14,2121,2122],{},"Map each agent to an escalation chain when you deploy it. Don't assume \"someone will see it.\" Assumption is the enemy of reliable agent operations.",[14,2124,2125],{},"This is exactly the kind of guardrail architecture that should be built into your platform, not bolted on after the fact. On BetterClaw, trust levels (Intern, Specialist, Lead) implement tiered autonomy natively. An \"Intern\" agent drafts but never executes. A \"Specialist\" executes within defined boundaries. A \"Lead\" acts autonomously with the one-click kill switch as the emergency brake. 200+ verified skills with built-in action approval. Free plan with 1 agent and 500 credits a month. $49/month on Pro. BYOK with zero markup.",[35,2127,2129],{"id":2128},"the-metrics-that-tell-you-if-your-guardrails-are-working","The metrics that tell you if your guardrails are working",[14,2131,2132],{},"Deploy approval gates and then measure whether they're calibrated correctly. Three metrics matter:",[14,2134,2135],{},[80,2136],{"alt":2137,"src":2138},"The guardrail calibration dashboard: three dials to watch — approval latency (target under 30 min), override rate (move under 2% to auto-approve, fix over 20%), and false-positive rate (tighten if over 15% are rubber-stamped).","/img/blog/ai-agent-human-approval-guardrails-metrics.jpg",[14,2140,2141,2144],{},[17,2142,2143],{},"Approval latency."," How long does it take from the agent queuing an action to a human approving it? If average latency exceeds 30 minutes for Tier 2 actions, your agent is spending more time waiting than working. Either the notification channel is wrong, the escalation chain is too slow, or you have too many actions in Tier 2 that should be in Tier 1.",[14,2146,2147,2150],{},[17,2148,2149],{},"Override rate."," What percentage of queued actions does the human reject or modify? If the override rate is below 2%, the actions in that tier are likely safe to auto-approve. Move them to Tier 1. If the override rate is above 20%, the agent is making too many errors and needs prompt or model improvements before being trusted with those actions.",[14,2152,2153,2156],{},[17,2154,2155],{},"False-positive rate."," How often does the guardrail fire on an action that didn't need review? If 90% of your Tier 2 approvals are rubber-stamped without changes, you've created busywork. Tighten the criteria for what triggers review.",[14,2158,2159],{},"The ideal approval system has high Tier 1 volume (the agent works fast on routine tasks), low Tier 2 volume (only genuinely ambiguous actions need review), and near-zero Tier 3 volume (high-risk actions are rare by design).",[14,2161,2162],{},"Gartner projects 40% of enterprise applications will embed AI agents by end of 2026. The organizations that get adoption right will be the ones whose teams trust their agents. And trust is built by demonstrating that the agent asks before acting on the things that matter.",[35,2164,2166],{"id":2165},"the-kill-switch-for-when-everything-else-fails","The kill switch (for when everything else fails)",[14,2168,2169],{},[80,2170],{"alt":2171,"src":2172},"The kill switch: build it first, hope to never use it. One button immediately halts all agent activity — no pending actions execute, no queued tasks complete, everything stops.","/img/blog/ai-agent-human-approval-guardrails-kill-switch.jpg",[14,2174,2175],{},"Every agent needs an emergency stop. Not a \"politely wind down\" mechanism. A button that immediately halts all agent activity. No pending actions execute. No queued tasks complete. Everything stops.",[14,2177,2178],{},"This isn't for routine operations. It's for the scenario where the agent is doing something unexpected at scale and you need it to stop now. The Meta email deletion incident is the canonical example. The agent was acting autonomously, the user couldn't stop it, and the damage compounded with every second.",[14,2180,2181],{},"Build the kill switch before you deploy the agent. Not after. Test it regularly. Know where it is at 2 AM when your phone buzzes.",[14,2183,2184],{},"The hardest part of AI agent guardrails isn't the technology. It's the organizational discipline. Defining which actions are Tier 1, 2, and 3. Assigning reviewers. Setting timeouts. Reviewing the metrics. Updating the tiers as the agent proves itself.",[14,2186,2187],{},"The teams that do this well gradually move actions from Tier 2 to Tier 1 as the agent demonstrates reliability. The boundary between \"needs approval\" and \"auto-approve\" shifts over time. That's the whole point. You're not building a permanent approval wall. You're building a trust gradient that widens as the agent earns it.",[14,2189,2190],{},"Start with more oversight than you think you need. Remove it as the data tells you to. Never the other way around.",[14,2192,2193],{},"Give BetterClaw a look if you want trust levels built in from day one. Intern, Specialist, Lead. Action approval on every skill. One-click kill switch. Free plan with 1 agent and 500 credits a month. $49/month for Pro. We handle the guardrail infrastructure. You decide where the lines go.",[35,2195,403],{"id":402},[666,2197,2199],{"id":2198},"what-are-ai-agent-guardrails","What are AI agent guardrails?",[14,2201,2202],{},"AI agent guardrails are safety controls that define what an autonomous agent can do without supervision and what requires human approval before execution. The most effective approach is tiered autonomy: routine, low-risk actions (reading data, drafting responses) are auto-approved, medium-risk actions (sending emails, updating records) are queued for human review, and high-risk actions (processing payments, deleting data) are blocked until a human explicitly approves.",[666,2204,2206],{"id":2205},"how-does-human-approval-compare-to-fully-autonomous-agents","How does human approval compare to fully autonomous agents?",[14,2208,2209],{},"Fully autonomous agents are faster but riskier. A single hallucinated action can cause real damage (unauthorized refunds, deleted data, incorrect external communications). Fully supervised agents are safe but negate the value of automation. Tiered autonomy gives you 80-90% of the speed (routine actions execute instantly) with 95%+ of the safety (risky actions wait for human review). The overhead is typically 10-15 approval reviews per day for a well-calibrated system.",[666,2211,2213],{"id":2212},"how-do-i-set-up-approval-workflows-for-my-ai-agent","How do I set up approval workflows for my AI agent?",[14,2215,2216],{},"Define three tiers: Tier 1 (auto-approve: read-only, reversible, internal actions), Tier 2 (queue for review: customer-facing, data-modifying actions), Tier 3 (block until approved: financial, irreversible, legal-impact actions). Choose an approval channel (Slack for real-time, email for batch, dashboard for high-volume). Set timeout rules for Tier 2 (escalate after 30 minutes). Assign an escalation chain per agent. On BetterClaw, this maps directly to trust levels: Intern (Tier 2/3), Specialist (Tier 1/2), Lead (mostly Tier 1).",[666,2218,2220],{"id":2219},"does-adding-approval-steps-slow-down-my-ai-agent","Does adding approval steps slow down my AI agent?",[14,2222,2223],{},"Only for the 15-20% of actions that genuinely need review. Tier 1 actions (80%+ of typical workloads) execute with zero delay. Tier 2 actions add 2-60 minutes depending on your approval channel and reviewer availability. Tier 3 actions wait for explicit approval with no timeout. If your approval latency exceeds 30 minutes on average, either your channel is wrong, your escalation chain is too slow, or too many actions are in Tier 2 that should be in Tier 1.",[666,2225,2227],{"id":2226},"how-do-i-know-if-my-agent-guardrails-are-calibrated-correctly","How do I know if my agent guardrails are calibrated correctly?",[14,2229,2230],{},"Track three metrics: approval latency (target: under 30 minutes average for Tier 2), override rate (if under 2%, move those actions to auto-approve; if over 20%, improve the agent before trusting it), and false-positive rate (if over 15% of approvals are rubber-stamped, tighten the review criteria). Review these metrics monthly and adjust tier assignments. The goal is to gradually move actions from Tier 2 to Tier 1 as the agent demonstrates reliability over time.",{"title":239,"searchDepth":438,"depth":438,"links":2232},[2233,2234,2235,2238,2241,2242,2243,2244],{"id":1954,"depth":438,"text":1955},{"id":1984,"depth":438,"text":1985},{"id":2000,"depth":438,"text":2001,"children":2236},[2237],{"id":2013,"depth":722,"text":2014},{"id":2047,"depth":438,"text":2048,"children":2239},[2240],{"id":2060,"depth":722,"text":2061},{"id":2091,"depth":438,"text":2092},{"id":2128,"depth":438,"text":2129},{"id":2165,"depth":438,"text":2166},{"id":402,"depth":438,"text":403,"children":2245},[2246,2247,2248,2249,2250],{"id":2198,"depth":722,"text":2199},{"id":2205,"depth":722,"text":2206},{"id":2212,"depth":722,"text":2213},{"id":2219,"depth":722,"text":2220},{"id":2226,"depth":722,"text":2227},"Your agent shouldn't approve refunds alone. But it shouldn't ask permission to read email. Three-tier approval architecture inside.","/img/blog/ai-agent-human-approval-guardrails.jpg",{},"/blog/ai-agent-human-approval-guardrails","10 min read",{"title":1927,"description":2251},"AI Agent Guardrails: Human Approval Without the Lag","blog/ai-agent-human-approval-guardrails",[2260,2261,2262,2263,2264,2265],"ai agent human approval","agent guardrails","human in the loop agent","agent approval workflow","ai agent safety controls","agent trust levels","CrkNFJyOVdfDHtFRL3LuF3-gYOXDS9yavzUjfqXEvNE",{"id":2268,"title":2269,"author":2270,"body":2271,"category":449,"date":3002,"description":3003,"extension":452,"featured":453,"hideToc":453,"image":3004,"imageHeight":473,"imageWidth":473,"meta":3005,"navigation":458,"path":3006,"readingTime":1909,"redirected":453,"seo":3007,"seoTitle":3008,"stem":3009,"tags":3010,"updatedDate":3021,"__hash__":3022},"blog/blog/best-openclaw-skills.md","17 Best OpenClaw Skills in 2026 (Security-Vetted, Ranked)",{"name":7,"role":8,"avatar":9},{"type":11,"value":2272,"toc":2986},[2273,2276,2279,2295,2299,2302,2459,2462,2468,2472,2475,2478,2481,2485,2495,2501,2507,2510,2516,2520,2523,2528,2548,2553,2567,2571,2574,2580,2585,2591,2605,2610,2624,2630,2636,2640,2643,2649,2655,2669,2674,2679,2693,2699,2705,2711,2716,2726,2730,2733,2739,2744,2758,2764,2770,2775,2781,2785,2788,2794,2800,2806,2812,2818,2821,2838,2842,2845,2851,2857,2862,2876,2879,2885,2889,2895,2898,2905,2914,2916,2921,2924,2929,2932,2937,2945,2950,2957,2962,2969,2983],[14,2274,2275],{},"ClawHub now holds 13,700+ community-built skills. A January 2026 security scan found 341 of them actively stealing user data. So the real question is not \"what skills exist,\" it is \"which ones are popular, safe, and actually worth installing.\"",[14,2277,2278],{},"This is that list. Below are the 17 best OpenClaw skills, ranked by real install counts and filtered for safety, each with its install command and what it is actually good for. Start with the quick-picks table, then read the why behind each pick.",[54,2280,2281,2285],{},[666,2282,2284],{"id":2283},"your-agent-working-not-broken","Your agent. Working. Not broken.",[14,2286,2287,2288,2294],{},"One AI agent that just works. No silent failures. Free forever, not a trial.\n",[17,2289,2290],{},[222,2291,2293],{"href":391,"rel":2292},[393],"Start free →","\nNo credit card · No Docker · No config files",[35,2296,2298],{"id":2297},"quick-picks-most-installed-openclaw-skills-ranked","Quick Picks: Most Installed OpenClaw Skills, Ranked",[14,2300,2301],{},"These are the skills with the highest install counts on ClawHub that also pass a basic safety bar (public source, recent updates, no permission red flags). If you only read one section, read this one.",[2303,2304,2305,2327],"table",{},[2306,2307,2308],"thead",{},[2309,2310,2311,2315,2318,2321,2324],"tr",{},[2312,2313,2314],"th",{},"Skill",[2312,2316,2317],{},"What it does",[2312,2319,2320],{},"Installs",[2312,2322,2323],{},"Safe?",[2312,2325,2326],{},"Best for",[2328,2329,2330,2348,2364,2380,2396,2412,2428,2444],"tbody",{},[2309,2331,2332,2336,2339,2342,2345],{},[2333,2334,2335],"td",{},"Skill Vetter",[2333,2337,2338],{},"Scans skills for red flags before and after install",[2333,2340,2341],{},"~256K",[2333,2343,2344],{},"Yes",[2333,2346,2347],{},"Install this first",[2309,2349,2350,2353,2356,2359,2361],{},[2333,2351,2352],{},"GitHub",[2333,2354,2355],{},"Manage repos, issues, PRs, webhooks",[2333,2357,2358],{},"~189K",[2333,2360,2344],{},[2333,2362,2363],{},"Developers",[2309,2365,2366,2369,2372,2375,2377],{},[2333,2367,2368],{},"Ontology Memory",[2333,2370,2371],{},"Persistent long-term memory across sessions",[2333,2373,2374],{},"~188K",[2333,2376,2344],{},[2333,2378,2379],{},"Everyone",[2309,2381,2382,2385,2388,2391,2393],{},[2333,2383,2384],{},"Google Workspace (gog)",[2333,2386,2387],{},"Gmail, Calendar, Docs, Sheets access",[2333,2389,2390],{},"~185K",[2333,2392,2344],{},[2333,2394,2395],{},"Productivity",[2309,2397,2398,2401,2404,2407,2409],{},[2333,2399,2400],{},"Felo Search",[2333,2402,2403],{},"AI-optimized web search with citations",[2333,2405,2406],{},"~145K",[2333,2408,2344],{},[2333,2410,2411],{},"Research",[2309,2413,2414,2417,2420,2423,2425],{},[2333,2415,2416],{},"Telegram Notify",[2333,2418,2419],{},"Message your agent from your phone",[2333,2421,2422],{},"High",[2333,2424,2344],{},[2333,2426,2427],{},"Mobile access",[2309,2429,2430,2433,2436,2438,2441],{},[2333,2431,2432],{},"Web Browser",[2333,2434,2435],{},"Headless browser automation",[2333,2437,2422],{},[2333,2439,2440],{},"Caution",[2333,2442,2443],{},"Scraping, monitoring",[2309,2445,2446,2449,2452,2454,2456],{},[2333,2447,2448],{},"SSH Manager",[2333,2450,2451],{},"Manage remote servers in plain English",[2333,2453,2422],{},[2333,2455,2440],{},[2333,2457,2458],{},"DevOps",[14,2460,2461],{},"Install counts are drawn from public ClawHub download rankings and community roundups and shift over time. \"Caution\" means the skill is genuinely useful but touches a sensitive surface (a server, a live browser session) and needs tight permission scoping.",[14,2463,2464],{},[80,2465],{"alt":2466,"src":2467},"Quick-picks comparison table of the most installed OpenClaw skills with install counts and safety ratings, hand-drawn pastel style","/img/blog/openclaw-skills-recommended.jpg",[35,2469,2471],{"id":2470},"start-with-three-then-expand","Start With Three, Then Expand",[14,2473,2474],{},"Before the full breakdown, the single most useful piece of advice: do not install 20 skills on day one. Conflicts between skills that need similar permissions are the number one reason new setups break.",[14,2476,2477],{},"Start with three. A memory skill so your agent remembers context. A search skill so it can pull current information. And Skill Vetter so everything else you add gets checked first. Run those for a week, learn the permission model, then expand based on the gaps you actually hit.",[14,2479,2480],{},"Now, the picks. But first, the distinction most guides get wrong.",[35,2482,2484],{"id":2483},"skills-vs-tools-the-distinction-that-saves-you-from-yourself","Skills vs. Tools: The Distinction That Saves You From Yourself",[14,2486,2487,2490,2491,2494],{},[17,2488,2489],{},"Tools are the muscles."," They determine what your agent can do. Read files. Execute commands. Browse the web. These are controlled by the ",[49,2492,2493],{},"tools.allow"," configuration.",[14,2496,2497,2500],{},[17,2498,2499],{},"Skills are the playbook."," They teach your agent how to combine tools for specific tasks. The GitHub skill teaches your agent how to manage repos. A memory skill teaches it how to store and recall context. But without the right tools enabled, skills are just instructions with no hands.",[14,2502,2503,2506],{},[17,2504,2505],{},"Key takeaway: installing a skill does NOT automatically grant your agent new permissions."," You still control which tools are enabled. This is your primary safety lever. Use it.",[14,2508,2509],{},"Three conditions must all be met for any skill to work: the tool must be allowed in config, the required software must be installed (on your machine or in the sandbox), and the skill must be loaded in your workspace. Miss one and nothing happens.",[14,2511,2512],{},[80,2513],{"alt":2514,"src":2515},"OpenClaw skills vs tools diagram showing the distinction between tool permissions and skill playbooks, hand-drawn pastel style","/img/blog/openclaw-skills-vs-tools.jpg",[35,2517,2519],{"id":2518},"the-safety-layer-install-these-first","The Safety Layer: Install These First",[14,2521,2522],{},"Before any feature skill, install the one that protects you from the rest.",[14,2524,2525,2527],{},[17,2526,2335],{}," (~256K installs) is the single most-downloaded skill on ClawHub for a reason. It scans skills for red flags before and after installation, flagging unverified dependency pulls, broad permission requests, and suspicious network calls. Given that a January 2026 scan found 341 skills actively harvesting data, this is not optional. Install it before anything else.",[231,2529,2533],{"className":2530,"code":2531,"language":2532,"meta":239,"style":239},"language-bash shiki shiki-themes github-light","clawhub install skill-vetter\n","bash",[49,2534,2535],{"__ignoreMap":239},[708,2536,2537,2541,2545],{"class":710,"line":711},[708,2538,2540],{"class":2539},"s7eDp","clawhub",[708,2542,2544],{"class":2543},"sYBdl"," install",[708,2546,2547],{"class":2543}," skill-vetter\n",[14,2549,2550,2552],{},[17,2551,2368],{}," (~188K installs) solves OpenClaw's biggest out-of-the-box weakness: it does not remember anything between sessions by default. This skill gives your agent persistent, structured long-term memory so context carries across conversations. The community consistently ranks memory as the \"install first\" foundation, because every other skill gets more useful when your agent remembers your project, your preferences, and what it did yesterday.",[231,2554,2556],{"className":2530,"code":2555,"language":2532,"meta":239,"style":239},"clawhub install ontology-memory\n",[49,2557,2558],{"__ignoreMap":239},[708,2559,2560,2562,2564],{"class":710,"line":711},[708,2561,2540],{"class":2539},[708,2563,2544],{"class":2543},[708,2565,2566],{"class":2543}," ontology-memory\n",[35,2568,2570],{"id":2569},"the-productivity-stack-your-agents-daily-operating-system","The Productivity Stack: Your Agent's Daily Operating System",[14,2572,2573],{},"These are the skills that turn OpenClaw from \"interesting experiment\" into \"I can't work without this.\"",[14,2575,2576],{},[80,2577],{"alt":2578,"src":2579},"Productivity skills stack showing Google Workspace, Telegram, Notion, and Meeting Prep integrations, hand-drawn pastel style","/img/blog/openclaw-productivity-stack.jpg",[14,2581,2582,2584],{},[17,2583,2384],{}," (~185K installs) is the foundational productivity skill and probably the first integration you should add after memory and search. It gives your agent access to Gmail, Calendar, Docs, and Sheets. The real power shows up paired with the heartbeat scheduler: have your agent check your calendar every morning and send a briefing before you've had coffee.",[14,2586,2587,2590],{},[24,2588,2589],{},"Security note:"," this skill gets deep access to your Google account. Scope it carefully. Read access to your calendar, write access only to specific docs. Never blanket Drive access.",[231,2592,2594],{"className":2530,"code":2593,"language":2532,"meta":239,"style":239},"clawhub install gog\n",[49,2595,2596],{"__ignoreMap":239},[708,2597,2598,2600,2602],{"class":710,"line":711},[708,2599,2540],{"class":2539},[708,2601,2544],{"class":2543},[708,2603,2604],{"class":2543}," gog\n",[14,2606,2607,2609],{},[17,2608,2416],{}," is ranked the number one skill in several community roundups, and the reason is simple: Telegram is OpenClaw's most reliable notification channel. No API approval, no rate limits that matter, works from any other skill. Connect with a BotFather token and you can message your agent from your phone, get morning briefings, task-completion alerts, and error notifications wherever you are. If you want your agent to proactively reach you, this is how.",[231,2611,2613],{"className":2530,"code":2612,"language":2532,"meta":239,"style":239},"clawhub install telegram-notify\n",[49,2614,2615],{"__ignoreMap":239},[708,2616,2617,2619,2621],{"class":710,"line":711},[708,2618,2540],{"class":2539},[708,2620,2544],{"class":2543},[708,2622,2623],{"class":2543}," telegram-notify\n",[14,2625,2626,2629],{},[17,2627,2628],{},"Notion Integration"," lets your agent create pages, update databases, query project boards, and manage docs. The sweet spot is meeting notes: your agent extracts action items from a call summary and drops them into your Notion board automatically.",[14,2631,2632,2635],{},[17,2633,2634],{},"Meeting Prep Agent"," gathers calendar details, past notes, related documents, and email threads before every meeting, then assembles a briefing you can skim in 90 seconds. No more scrambling to remember last week.",[35,2637,2639],{"id":2638},"the-developer-stack-skills-that-actually-ship-code","The Developer Stack: Skills That Actually Ship Code",[14,2641,2642],{},"If you write code, these earn their keep.",[14,2644,2645],{},[80,2646],{"alt":2647,"src":2648},"Developer skills stack showing GitHub, Cursor CLI, Docker, Vercel, and SSH integrations, hand-drawn pastel style","/img/blog/openclaw-developer-stack.jpg",[14,2650,2651,2654],{},[17,2652,2653],{},"GitHub Integration"," (~189K installs) is non-negotiable if you write code. Manage issues, PRs, repos, and webhooks through your agent. The real unlock: a webhook listener so your agent gets notified on new PRs and summarizes changes before you review. Pair it with the heartbeat for a daily repo digest.",[231,2656,2658],{"className":2530,"code":2657,"language":2532,"meta":239,"style":239},"clawhub install github\n",[49,2659,2660],{"__ignoreMap":239},[708,2661,2662,2664,2666],{"class":710,"line":711},[708,2663,2540],{"class":2539},[708,2665,2544],{"class":2543},[708,2667,2668],{"class":2543}," github\n",[14,2670,2671,2673],{},[17,2672,2448],{}," is one of the most-searched skills on ClawHub, and for good reason. It lets you manage remote servers through natural language instead of memorizing commands. Run diagnostics, deploy code, tail logs, restart services, and check disk usage from your messaging app.",[14,2675,2676,2678],{},[24,2677,2589],{}," this hands your agent live server access. Start with read-only diagnostics, scope write access tightly, and never point it at production until you trust the setup.",[231,2680,2682],{"className":2530,"code":2681,"language":2532,"meta":239,"style":239},"clawhub install ssh-manager\n",[49,2683,2684],{"__ignoreMap":239},[708,2685,2686,2688,2690],{"class":710,"line":711},[708,2687,2540],{"class":2539},[708,2689,2544],{"class":2543},[708,2691,2692],{"class":2543}," ssh-manager\n",[14,2694,2695,2698],{},[17,2696,2697],{},"Cursor CLI Agent"," bridges your OpenClaw agent to the Cursor AI coding assistant. If you already use Cursor, this lets you trigger code generation, refactoring, and analysis from any chat channel. Text your agent from Telegram and it kicks off a Cursor session in the background.",[14,2700,2701,2704],{},[17,2702,2703],{},"Docker Manager"," lets your agent manage containers, images, and compose stacks. Start, stop, inspect, and clean up through chat. Useful when you manage multiple environments and don't want to SSH in every time something needs a restart.",[14,2706,2707,2710],{},[17,2708,2709],{},"Vercel Deployment"," turns deployments into conversational commands. Manage environment variables, configure domains, trigger releases.",[14,2712,2713,2715],{},[24,2714,2589],{}," this grants production deployment rights. Start in staging. Always.",[14,2717,2718,2719,2725],{},"If your work sits closer to infrastructure than application code, Linux Handbook's guide to ",[222,2720,2724],{"href":2721,"rel":2722},"https://linuxhandbook.com/blog/devops-engineer-claude-skills/",[2723],"dofollow","Claude skills for DevOps engineers"," covers the same ground from a sysadmin angle - container and pipeline work, server diagnostics, and log triage - and maps cleanly onto the SSH Manager and Docker Manager skills above.",[35,2727,2729],{"id":2728},"the-automation-stack-making-your-agent-proactive","The Automation Stack: Making Your Agent Proactive",[14,2731,2732],{},"These move your agent from reactive (\"do this when I ask\") to proactive (\"do this because you noticed something\").",[14,2734,2735],{},[80,2736],{"alt":2737,"src":2738},"Automation skills stack showing Cron Job Manager, Web Browser, Felo Search, and n8n integrations, hand-drawn pastel style","/img/blog/openclaw-automation-stack.jpg",[14,2740,2741,2743],{},[17,2742,2400],{}," (~145K installs) is one of the most-installed skills on ClawHub. It returns AI-synthesized answers with source citations instead of a list of links, which cuts the back-and-forth in research loops. Multi-language support is a genuine differentiator if your work crosses languages. Without web search, your agent's knowledge stops at its training cutoff. With it, every task can pull current pricing, news, and docs.",[231,2745,2747],{"className":2530,"code":2746,"language":2532,"meta":239,"style":239},"clawhub install felo-search\n",[49,2748,2749],{"__ignoreMap":239},[708,2750,2751,2753,2755],{"class":710,"line":711},[708,2752,2540],{"class":2539},[708,2754,2544],{"class":2543},[708,2756,2757],{"class":2543}," felo-search\n",[14,2759,2760,2763],{},[17,2761,2762],{},"Cron Job Manager"," creates scheduled tasks in natural language. \"Remind me every Monday at 9 AM to review the sprint board.\" \"Check Hacker News every morning and send me the top 5 AI stories.\" It makes one of OpenClaw's most powerful features accessible without terminal syntax.",[14,2765,2766,2769],{},[17,2767,2768],{},"Web Browser Automation"," is a headless browser skill that navigates pages, clicks elements, fills forms, and captures screenshots. It is the backbone of any monitoring or scraping workflow.",[14,2771,2772,2774],{},[24,2773,2589],{}," browser automation can visit any URL your agent encounters, which is a significant prompt injection surface. Sandbox this aggressively.",[14,2776,2777,2780],{},[17,2778,2779],{},"n8n Workflow Manager"," connects your agent to your n8n instance so it can activate workflows, check execution status, and trigger manual runs. The value scales with how much you have already built in n8n.",[35,2782,2784],{"id":2783},"the-skills-you-should-not-install-yet","The Skills You Should NOT Install (Yet)",[14,2786,2787],{},"Here is where we get opinionated.",[14,2789,2790],{},[80,2791],{"alt":2792,"src":2793},"Warning signs for unsafe OpenClaw skills showing red flags to watch for on ClawHub, hand-drawn pastel style","/img/blog/openclaw-skills-to-avoid.jpg",[14,2795,2796,2799],{},[17,2797,2798],{},"Avoid skills from unverified authors with fewer than 100 installs."," A useful rule of thumb the community calls the 100/3 rule: prefer skills with 100+ downloads that have been on ClawHub for 3+ months. The removal process for flagged skills is slow, so do not be the test case.",[14,2801,2802,2805],{},[17,2803,2804],{},"Be cautious with \"self-improving\" or \"auto-evolution\" skills."," Several highly-starred skills claim to make your agent \"continuously enhance its own capabilities.\" That sounds exciting. It is also exactly the recursive, autonomous behavior that is hardest to audit and most likely to surprise you in production.",[14,2807,2808,2811],{},[17,2809,2810],{},"Skip any skill that asks for broader permissions than its stated purpose."," A calendar skill that wants terminal access is a red flag. A weather skill that wants to read your files is a walk-away. Apply least privilege to every install.",[14,2813,2814,2817],{},[17,2815,2816],{},"Watch for typosquatting."," The ClawHavoc campaign in early 2026 planted hundreds of malicious skills using names that mimic popular ones. Check the exact slug and the author before you install.",[14,2819,2820],{},"Our rule of thumb: if you can't read and understand a skill's SKILL.md and source in under five minutes, it is either too complex for its stated purpose or doing more than it claims.",[14,2822,2823,2824,2828,2829,2832,2833,2837],{},"For a full breakdown of every documented security incident, see our ",[222,2825,2827],{"href":2826},"/blog/openclaw-security-risks","OpenClaw security risks guide",". If you're running skills on ",[222,2830,2831],{"href":398},"BetterClaw's managed OpenClaw platform",", this risk is significantly lower. Every agent runs in a sandboxed environment with encrypted credentials, workspace scoping, and ",[222,2834,2836],{"href":2835},"/#features","real-time health monitoring that auto-pauses on anomalies",". You still choose your skills, but the blast radius of a bad one is contained by default.",[35,2839,2841],{"id":2840},"how-to-install-openclaw-skills-the-right-way","How to Install OpenClaw Skills (The Right Way)",[14,2843,2844],{},"The process is simple. Doing it safely takes a few extra steps.",[14,2846,2847,2850],{},[17,2848,2849],{},"Step 1: Search before you install."," Use ClawHub's vector search to describe what you need in plain English. \"Something that summarizes my emails every morning\" returns better results than keyword-searching \"email summarizer.\"",[14,2852,2853,2856],{},[17,2854,2855],{},"Step 2: Vet before you trust."," Check install count, last update date, and author. Read the source. Check the security scan on the skill's ClawHub page. If anything looks off, skip it.",[14,2858,2859],{},[17,2860,2861],{},"Step 3: Install with one command.",[231,2863,2865],{"className":2530,"code":2864,"language":2532,"meta":239,"style":239},"clawhub install skill-name\n",[49,2866,2867],{"__ignoreMap":239},[708,2868,2869,2871,2873],{"class":710,"line":711},[708,2870,2540],{"class":2539},[708,2872,2544],{"class":2543},[708,2874,2875],{"class":2543}," skill-name\n",[14,2877,2878],{},"The skill downloads, validates, and activates. Start a new OpenClaw session to pick it up.",[14,2880,2881,2884],{},[17,2882,2883],{},"Step 4: Scope your permissions."," Review what tools the skill needs and enable only the minimum. Don't give write access when read will do. Don't enable exec when the skill only needs web access.",[35,2886,2888],{"id":2887},"the-easier-path-skills-on-betterclaw","The Easier Path: Skills on BetterClaw",[14,2890,2891],{},[80,2892],{"alt":2893,"src":2894},"BetterClaw managed platform showing secure skill deployment with sandboxed execution and encrypted credentials, hand-drawn pastel style","/img/blog/betterclaw-skills-deployment.jpg",[14,2896,2897],{},"Everything above, the vetting, the permission scoping, the sandbox config, the tool management, is work you do yourself when self-hosting OpenClaw. It is worth doing if you want to learn the system deeply.",[14,2899,2900,2901,2904],{},"But if your goal is a production-ready agent running the best skills securely across your team's channels, ",[222,2902,2903],{"href":675},"BetterClaw handles the infrastructure"," so you can focus on choosing the right skills. One-click deploy. Sandboxed execution. Encrypted credentials. $49/month for Pro, BYOK.",[14,2906,2907,2908],{},"You pick the skills. We make sure they run safely. Already on self-hosted OpenClaw? ",[17,2909,2910],{},[222,2911,2913],{"href":2912},"/migrate","Migrate to BetterClaw in under an hour →",[35,2915,403],{"id":402},[14,2917,2918],{},[17,2919,2920],{},"How many skills are on ClawHub?",[14,2922,2923],{},"As of mid-2026, ClawHub hosts roughly 13,700 published community-built skills, up from about 6,500 in January 2026. The curated awesome-openclaw-skills list filters these down to roughly 5,400 vetted picks. The registry grows daily, so treat any exact number as a snapshot rather than a fixed figure.",[14,2925,2926],{},[17,2927,2928],{},"What is the most popular OpenClaw skill?",[14,2930,2931],{},"By raw download count, the leaders are Skill Vetter (~256K), GitHub (~189K), Ontology Memory (~188K), and Google Workspace / gog (~185K), followed by Felo Search at 145K+ installs. Popularity tracks utility here: the top skills handle safety, code, memory, and search, the four things almost every agent needs.",[14,2933,2934],{},[17,2935,2936],{},"Are ClawHub skills safe?",[14,2938,2939,2940,2944],{},"Not all of them. A January 2026 security scan found 341 skills actively stealing user data, most from a single coordinated campaign. For business use, stick to skills with high install counts, recent updates, and public source code. Always review the source, apply least-privilege permissions, and run new skills in a sandbox. On managed platforms like ",[222,2941,2943],{"href":2942},"/compare/openclaw","BetterClaw",", sandbox isolation and credential encryption are built in by default.",[14,2946,2947],{},[17,2948,2949],{},"How do I install OpenClaw skills safely?",[14,2951,2952,2953,2956],{},"Search ClawHub using vector search or the CLI, then vet the skill by checking its install count, author, last update, and security scan. Install with ",[49,2954,2955],{},"clawhub install skill-name",". After installing, scope permissions to the minimum required and run new skills in a sandbox first. Installing Skill Vetter before anything else adds an automated check on every skill you add.",[14,2958,2959],{},[17,2960,2961],{},"What are OpenClaw skills and how do they work?",[14,2963,2964,2965,2968],{},"OpenClaw skills are modular text-based extensions (a ",[49,2966,2967],{},"SKILL.md"," file plus supporting files) that teach your agent how to perform specific tasks. They do not grant new permissions on their own; they combine the tools already enabled in your config. You install them from ClawHub with a single CLI command, and they activate on your next agent session.",[54,2970,2971,2975],{},[666,2972,2974],{"id":2973},"stop-vetting-skills-by-hand","Stop vetting skills by hand.",[14,2976,2977,2978],{},"Run the best OpenClaw skills on managed, sandboxed infrastructure. Verified skills, encrypted secrets, auto-pause monitoring. Free forever, not a trial.\n",[17,2979,2980],{},[222,2981,2293],{"href":391,"rel":2982},[393],[1875,2984,2985],{},"html pre.shiki code .s7eDp, html code.shiki .s7eDp{--shiki-default:#6F42C1}html pre.shiki code .sYBdl, html code.shiki .sYBdl{--shiki-default:#032F62}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"title":239,"searchDepth":438,"depth":438,"links":2987},[2988,2989,2990,2991,2992,2993,2994,2995,2996,2997,2998,2999],{"id":2283,"depth":722,"text":2284},{"id":2297,"depth":438,"text":2298},{"id":2470,"depth":438,"text":2471},{"id":2483,"depth":438,"text":2484},{"id":2518,"depth":438,"text":2519},{"id":2569,"depth":438,"text":2570},{"id":2638,"depth":438,"text":2639},{"id":2728,"depth":438,"text":2729},{"id":2783,"depth":438,"text":2784},{"id":2840,"depth":438,"text":2841},{"id":2887,"depth":438,"text":2888},{"id":402,"depth":438,"text":403,"children":3000},[3001],{"id":2973,"depth":722,"text":2974},"2026-03-27","13,700+ ClawHub skills, 341 found malicious. Here are the 17 best OpenClaw skills, ranked by installs and security-vetted, with install commands.","/img/blog/best-openclaw-skills.jpg",{},"/blog/best-openclaw-skills",{"title":2269,"description":3003},"Best OpenClaw Skills 2026: Ranked by Installs & Security-Vetted","blog/best-openclaw-skills",[3011,3012,3013,3014,3015,3016,3017,3018,3019,3020],"best OpenClaw skills","most installed OpenClaw skills","best ClawHub skills 2026","OpenClaw skills to install","safest OpenClaw skills","OpenClaw memory skill","OpenClaw Telegram skill","OpenClaw developer skills","OpenClaw productivity skills","how to install OpenClaw skills","2026-06-16","j0nifc3AdssZ4jaAkomKxwZ7YYJuj-CoPvIJ_b-9Pzc",{"id":3024,"title":3025,"author":3026,"body":3027,"category":449,"date":3507,"description":3508,"extension":452,"featured":453,"hideToc":453,"image":3509,"imageHeight":473,"imageWidth":473,"meta":3510,"navigation":458,"path":3511,"readingTime":1909,"redirected":453,"seo":3512,"seoTitle":3513,"stem":3514,"tags":3515,"updatedDate":3507,"__hash__":3524},"blog/blog/cheapest-openclaw-ai-providers.md","Cheapest OpenClaw AI Providers: 5 Alternatives to OpenAI That Cut Costs 80%",{"name":7,"role":8,"avatar":9},{"type":11,"value":3028,"toc":3495},[3029,3034,3037,3040,3043,3046,3049,3056,3059,3063,3066,3069,3072,3075,3078,3086,3092,3096,3102,3108,3111,3114,3124,3127,3130,3136,3140,3145,3148,3151,3154,3157,3160,3168,3174,3178,3183,3186,3189,3192,3195,3201,3207,3215,3219,3224,3227,3230,3245,3253,3260,3263,3269,3280,3284,3289,3292,3298,3309,3315,3322,3328,3332,3335,3338,3342,3345,3352,3355,3362,3372,3377,3385,3389,3392,3398,3404,3413,3425,3428,3434,3442,3444,3449,3452,3457,3460,3465,3479,3484,3487,3492],[14,3030,3031],{},[24,3032,3033],{},"Your OpenClaw agent doesn't need GPT-4o for everything. Here are the providers that cost a fraction and work just as well.",[14,3035,3036],{},"My OpenAI dashboard showed $147. Fourteen days. One agent.",[14,3038,3039],{},"I'd set up my OpenClaw instance on a Friday, pointed it at GPT-4o because that's what every tutorial recommended, and let it run. Morning briefings. Email triage. Calendar management. A few research tasks. Nothing exotic.",[14,3041,3042],{},"Two weeks later, $147. For an AI assistant that mostly checked my calendar and summarized emails.",[14,3044,3045],{},"I pulled up the token logs and did the math. GPT-4o at $2.50 per million input tokens and $10 per million output tokens sounds reasonable in isolation. But OpenClaw agents are hungry. Heartbeats every 30 minutes. Sub-agents spawning for parallel tasks. Context windows that grow silently as cron jobs accumulate history.",[14,3047,3048],{},"The tokens add up. Fast.",[14,3050,3051,3052,3055],{},"Here's the thing: the ",[17,3053,3054],{},"cheapest OpenClaw AI provider isn't always the worst one",". In 2026, there are models that cost 90% less than GPT-4o and perform just as well for the kind of work most agents actually do. Some of them are better at tool calling. Some have larger context windows. One of them is literally free.",[14,3057,3058],{},"This is the guide I wish I'd read before handing OpenAI $147 for two weeks of calendar checks.",[35,3060,3062],{"id":3061},"why-openai-is-the-default-and-why-thats-costing-you","Why OpenAI is the default (and why that's costing you)",[14,3064,3065],{},"OpenAI is the default recommendation in most OpenClaw tutorials for a simple reason: familiarity. Everyone has an OpenAI account. The API is well-documented. GPT-4o is genuinely good.",[14,3067,3068],{},"But \"good\" and \"cost-effective for an always-on agent\" are very different things.",[14,3070,3071],{},"OpenClaw agents don't work like a ChatGPT conversation. They run continuously. They process heartbeats (periodic status checks) every 30 minutes using your primary model. They spawn sub-agents for parallel work. They execute skills that require multiple model calls per task.",[14,3073,3074],{},"A single browser automation task can consume 50-200+ steps, with each step using 500-2,000 tokens. At GPT-4o pricing, that's $0.50-2.00 per complex task. Run a few of those daily and your monthly bill climbs past $100 easily.",[14,3076,3077],{},"The viral Medium post \"I Spent $178 on AI Agents in a Week\" captured this pain perfectly. Most of that spend was GPT-4o running tasks that didn't need GPT-4o.",[14,3079,3080,3081,3085],{},"For a deeper look at where OpenClaw API costs actually come from (and how they compound faster than you'd expect), we wrote a ",[222,3082,3084],{"href":3083},"/blog/openclaw-api-costs","complete breakdown of OpenClaw API costs"," with real monthly projections.",[14,3087,3088],{},[80,3089],{"alt":3090,"src":3091},"OpenClaw API cost breakdown showing GPT-4o token usage across heartbeats, sub-agents, and daily tasks","/img/blog/openclaw-136k-token-overhead-1.jpg",[35,3093,3095],{"id":3094},"_1-anthropic-claude-the-agent-first-provider","1. Anthropic Claude: The agent-first provider",[14,3097,3098,3101],{},[17,3099,3100],{},"Pricing:"," Haiku 4.5: $1/$5 | Sonnet 4.6: $3/$15 | Opus 4.6: $5/$25 (per million tokens, input/output)",[14,3103,3104,3105,122],{},"Claude isn't cheaper than GPT-4o across the board. Sonnet at $3/$15 is actually more expensive per output token. But here's why it's on this list: ",[17,3106,3107],{},"Claude is better at the specific things OpenClaw agents need to do",[14,3109,3110],{},"Tool calling reliability. Long-context accuracy. Prompt injection resistance. Multi-step instruction following. These are the areas where OpenClaw community benchmarks consistently rank Claude above GPT-4o.",[14,3112,3113],{},"The real savings come from Haiku 4.5 at $1/$5. That's 60% cheaper than GPT-4o on input and 50% cheaper on output. And for heartbeats, calendar lookups, simple queries, and sub-agent tasks, Haiku handles them beautifully.",[14,3115,3116,3119,3120,3123],{},[17,3117,3118],{},"The smart setup:"," Sonnet as your primary model, Haiku for heartbeats and sub-agents, Opus available via ",[49,3121,3122],{},"/model opus"," for complex reasoning when you need it. This tiered approach typically costs $40-70/month compared to $100-200 with GPT-4o for everything.",[14,3125,3126],{},"Claude isn't the cheapest option. It's the option where you get the most capability per dollar on agent-specific tasks.",[14,3128,3129],{},"OpenClaw's founder, Peter Steinberger, recommended Anthropic models before joining OpenAI. That recommendation still holds for most serious agent workloads.",[14,3131,3132],{},[80,3133],{"alt":3134,"src":3135},"Claude model tiers showing Haiku, Sonnet, and Opus pricing with recommended OpenClaw task assignments","/img/blog/openclaw-routing-tiers.jpg",[35,3137,3139],{"id":3138},"_2-deepseek-the-028-option-that-actually-works","2. DeepSeek: The $0.28 option that actually works",[14,3141,3142,3144],{},[17,3143,3100],{}," DeepSeek V3.2: $0.28/$0.42 per million tokens (input/output)",[14,3146,3147],{},"This is where the cost math gets wild.",[14,3149,3150],{},"DeepSeek V3.2 costs roughly 10x less than GPT-4o on input tokens and 24x less on output tokens. For an always-on OpenClaw agent, that difference compounds dramatically. A workload that costs $150/month on GPT-4o drops to approximately $15-20/month on DeepSeek.",[14,3152,3153],{},"And it's not a toy model. Community reports from the OpenClaw GitHub discussions consistently mention DeepSeek alongside Claude as the two providers that work best for agent tasks. It's particularly strong at code generation and debugging.",[14,3155,3156],{},"The tradeoffs are real though. DeepSeek's tool calling is less reliable than Claude's on complex multi-step chains. Context tracking over very long conversations can degrade. And if you're processing sensitive data, the provider routes through Chinese infrastructure, which matters for some use cases.",[14,3158,3159],{},"For pure cost optimization on non-sensitive tasks, DeepSeek is hard to beat. Set it as your heartbeat and sub-agent model while keeping a more capable model as your primary, and your bill drops by 70-80%.",[14,3161,3162,3163,3167],{},"Rates have moved since: V4-Flash now lists $0.14/$0.28 with cache hits at $0.003. Our ",[222,3164,3166],{"href":3165},"/blog/cheapest-ai-models-for-agents","cheapest AI models for agents"," comparison has the current numbers alongside MiniMax M3, Kimi and GLM, plus what each one costs across three real monthly agent workloads.",[14,3169,3170],{},[80,3171],{"alt":3172,"src":3173},"DeepSeek V3.2 cost comparison against GPT-4o and Claude showing 10-24x savings per million tokens","/img/blog/cheapest-openclaw-deepseek-comparison.jpg",[35,3175,3177],{"id":3176},"_3-google-gemini-free-tier-thats-surprisingly-capable","3. Google Gemini: Free tier that's surprisingly capable",[14,3179,3180,3182],{},[17,3181,3100],{}," Gemini 2.5 Flash free tier: $0 (1,500 requests/day) | Paid: $0.075/$0.30 per million tokens",[14,3184,3185],{},"Yes, free. Google AI Studio offers a free tier for Gemini 2.5 Flash with 1,500 requests per day and a 1 million token context window. No credit card required.",[14,3187,3188],{},"For personal OpenClaw use (morning briefings, calendar management, basic research), the free tier is often enough. 1,500 requests per day is surprisingly generous for a single-user agent.",[14,3190,3191],{},"Even the paid tier at $0.075 per million input tokens is absurdly cheap. That's 33x cheaper than GPT-4o. A moderate usage pattern that costs $100/month on OpenAI costs roughly $3 on Gemini Flash.",[14,3193,3194],{},"The limitation: Gemini's tool calling isn't as reliable as Claude or even GPT-4o for complex chains. It handles straightforward tasks well but can stumble on multi-step reasoning that requires precise instruction following.",[14,3196,3197,3200],{},[17,3198,3199],{},"Best used for:"," heartbeats, simple lookups, data parsing, and as a fallback model. Not recommended as your sole primary model for complex agent workflows.",[14,3202,3203],{},[80,3204],{"alt":3205,"src":3206},"Google Gemini free tier details showing 1500 daily requests and 1M token context window for OpenClaw","/img/blog/cheapest-openclaw-gemini-free.jpg",[14,3208,3209,3210,3214],{},"To understand which tasks need a powerful model versus which tasks can run on something cheap, our guide to ",[222,3211,3213],{"href":3212},"/blog/how-does-openclaw-work","how OpenClaw works under the hood"," explains the agent architecture and where model calls actually happen.",[35,3216,3218],{"id":3217},"_4-openrouter-one-api-key-200-models-automatic-routing","4. OpenRouter: One API key, 200+ models, automatic routing",[14,3220,3221,3223],{},[17,3222,3100],{}," Varies by model (typically 0-5% markup over direct provider pricing)",[14,3225,3226],{},"OpenRouter isn't a model provider. It's a routing layer. One API key gives you access to 200+ models across every major provider, and you can switch between them without managing separate API keys for each.",[14,3228,3229],{},"Here's why that matters for OpenClaw.",[14,3231,3232,3233,3236,3237,3240,3241,3244],{},"The ",[49,3234,3235],{},"/model"," command lets you switch models mid-conversation. With OpenRouter, you type ",[49,3238,3239],{},"/model deepseek/deepseek-v3.2"," and you're on DeepSeek. ",[49,3242,3243],{},"/model anthropic/claude-sonnet-4.6"," switches to Claude. No config file edits. No gateway restarts.",[14,3246,3247,3252],{},[222,3248,3251],{"href":3249,"rel":3250},"https://www.youtube.com/results?search_query=openclaw+openrouter+setup+model+switching+2026",[393],"Watch on YouTube: OpenClaw Multi-Model Setup with OpenRouter"," (Community content)\nIf you want to see how OpenRouter's model switching works in practice with OpenClaw (including the auto-routing feature that selects the cheapest capable model per request), this community walkthrough covers the full configuration and real-time cost comparison.",[14,3254,3255,3256,3259],{},"But the real savings feature is ",[49,3257,3258],{},"openrouter/auto",". Set this as your model and OpenRouter automatically routes each request to the most cost-effective model based on the complexity of the prompt. Simple heartbeats go to cheap models. Complex reasoning gets routed to capable ones. You save money without manually managing model tiers.",[14,3261,3262],{},"The tradeoff: a small markup on token prices (typically under 5%), and you're adding a routing layer which occasionally introduces latency. For most users, the convenience of one API key and automatic cost optimization is worth it.",[14,3264,3265],{},[80,3266],{"alt":3267,"src":3268},"OpenRouter auto-routing diagram showing automatic model selection based on task complexity","/img/blog/cheapest-openclaw-openrouter-routing.jpg",[14,3270,3271,3272,3275,3276,3279],{},"If you don't want to think about model routing at all, if you want automatic cost optimization with zero configuration and built-in anomaly detection that pauses your agent before costs spiral, ",[222,3273,3274],{"href":675},"Better Claw handles all of this"," at ",[222,3277,3278],{"href":398},"$49/month for Pro",". BYOK, 60-second deploy, and you can point it at any of these providers.",[35,3281,3283],{"id":3282},"_5-ollama-local-models-0-per-month-forever","5. Ollama (local models): $0 per month, forever",[14,3285,3286,3288],{},[17,3287,3100],{}," $0 API cost. Hardware and electricity only.",[14,3290,3291],{},"Running models locally through Ollama eliminates API costs entirely. Llama 3.3 70B, Mistral, Qwen 2.5: they all run on your machine, fully private, with no token charges.",[14,3293,3294,3297],{},[17,3295,3296],{},"The math:"," A Mac Mini M4 with 16GB RAM runs 7-8B models at 15-20 tokens per second. That's fast enough for most agent tasks. Larger models (30B+) need more RAM or a dedicated GPU.",[14,3299,3300,3301,3304,3305,3308],{},"For OpenClaw specifically, the ",[49,3302,3303],{},"hermes-2-pro"," and ",[49,3306,3307],{},"mistral:7b"," models are recommended for tool calling reliability. They're not Claude or GPT-4o, but for heartbeats, simple queries, and privacy-sensitive operations, they're genuinely useful.",[14,3310,3311,3314],{},[17,3312,3313],{},"The honest reality:"," local models in 2026 still can't match cloud providers on complex multi-step reasoning, long-context accuracy, or sophisticated tool use. The community consensus in OpenClaw's GitHub discussions is clear: local models work for experimentation and privacy-first setups, but cloud models are better for production agent workflows.",[14,3316,3317,3318,122],{},"The sweet spot is hybrid: local models for heartbeats and simple tasks, cloud models for complex reasoning. OpenClaw supports this natively through its ",[222,3319,3321],{"href":3320},"/blog/openclaw-model-routing","model routing configuration",[14,3323,3324],{},[80,3325],{"alt":3326,"src":3327},"Ollama local model setup showing zero API cost with hardware requirements for different model sizes","/img/blog/cheapest-openclaw-ollama-local.jpg",[35,3329,3331],{"id":3330},"the-provider-nobody-talks-about-minimax","The provider nobody talks about: MiniMax",[14,3333,3334],{},"Quick honorable mention. MiniMax offers a $10/month plan with 100 prompts every 5 hours. Peter Steinberger himself recommended it during community discussions. It's not on the level of Opus, but community members describe it as \"competent enough for most tasks.\"",[14,3336,3337],{},"For budget-conscious users who want a flat monthly rate instead of per-token billing, it's worth testing. The predictability alone can be valuable when you're worried about runaway agent costs.",[35,3339,3341],{"id":3340},"the-real-problem-isnt-the-provider-its-the-architecture","The real problem isn't the provider. It's the architecture.",[14,3343,3344],{},"Here's what I've learned after months of optimizing OpenClaw costs across different providers.",[14,3346,3347,3348,3351],{},"Switching from GPT-4o to DeepSeek saves you money. Setting up ",[222,3349,3350],{"href":3320},"model routing"," (different models for different task types) saves you more. But the biggest cost driver in OpenClaw isn't the per-token price. It's uncontrolled context growth.",[14,3353,3354],{},"Cron jobs accumulate context indefinitely. A task scheduled to check emails every 5 minutes eventually builds a 100,000-token context window. What starts at $0.02 per execution grows to $2.00 per execution regardless of which provider you use.",[14,3356,3232,3357,3361],{},[222,3358,3360],{"href":3359},"/blog/openclaw-memory-fix","memory compaction bug in OpenClaw"," makes this worse. Context compaction can kill active work mid-session, and the workarounds require manual token limits in every skill config.",[14,3363,3364,3365,3304,3368,3371],{},"Set ",[49,3366,3367],{},"maxContextTokens",[49,3369,3370],{},"maxIterations"," in your skill configurations. Set daily spending caps on OpenRouter or your provider's dashboard. Monitor your token usage weekly. These operational habits matter more than which provider you choose.",[14,3373,3374],{},[17,3375,3376],{},"The cheapest provider in the world can't save you from a runaway agent loop burning tokens at 3 AM.",[14,3378,3379,3380,3384],{},"For a look at what tasks are worth running through a premium model versus which ones can safely run on the cheapest option available, our guide to the ",[222,3381,3383],{"href":3382},"/blog/best-openclaw-use-cases","best OpenClaw use cases"," ranks workflows by complexity and cost.",[35,3386,3388],{"id":3387},"pick-your-fighter-a-practical-recommendation","Pick your fighter (a practical recommendation)",[14,3390,3391],{},"For most people reading this, here's what I'd actually recommend:",[14,3393,3394,3397],{},[17,3395,3396],{},"If you're just starting out:"," Gemini 2.5 Flash free tier. Zero risk. Learn how OpenClaw works without spending anything. Upgrade to a paid provider when you outgrow the free limits.",[14,3399,3400,3403],{},[17,3401,3402],{},"If you want the best quality-to-cost ratio:"," Claude Sonnet 4.6 as primary, Haiku 4.5 for heartbeats and sub-agents. This is what most serious OpenClaw users run. Expect $40-70/month.",[14,3405,3406,3409,3410,3412],{},[17,3407,3408],{},"If cost is the priority:"," DeepSeek V3.2 for everything except complex reasoning. Use Claude or GPT-4o on-demand via ",[49,3411,3235],{}," for the hard stuff. Expect $15-30/month.",[14,3414,3415,3418,3419,3275,3422,3424],{},[17,3416,3417],{},"If you don't want to think about any of this:"," OpenRouter auto-routing, or ",[222,3420,3421],{"href":675},"Better Claw",[222,3423,3278],{"href":398}," with BYOK and zero-config deployment.",[14,3426,3427],{},"The AI model market is getting cheaper every quarter. Opus 4.5 at $5/$25 is 66% cheaper than Opus 4.1 was at $15/$75. The trend is clear. But until prices hit zero (they won't), smart provider selection and model routing are the most impactful cost levers you have.",[14,3429,3430,3433],{},[17,3431,3432],{},"Stop paying GPT-4o prices for calendar checks."," Your agent will work just as well. Your wallet will thank you.",[14,3435,3436,3437,3441],{},"If you've been wrestling with API costs, config files, and model routing, and you'd rather just deploy an agent that works, ",[222,3438,3440],{"href":391,"rel":3439},[393],"give Better Claw a try",". It's $49/month for Pro, BYOK with any of the providers above, and your first agent deploys in about 60 seconds. We handle the infrastructure, the model routing, and the cost monitoring. You focus on building workflows.",[35,3443,403],{"id":402},[14,3445,3446],{},[17,3447,3448],{},"What are the cheapest AI providers for OpenClaw agents?",[14,3450,3451],{},"The cheapest cloud providers for OpenClaw in 2026 are DeepSeek V3.2 at $0.28/$0.42 per million tokens and Google Gemini 2.5 Flash at $0.075/$0.30 (with a free tier offering 1,500 requests per day). For zero-cost operation, Ollama lets you run local models like Llama 3.3 and Mistral with no API charges. Claude Haiku 4.5 at $1/$5 offers the best balance of low cost and agent-specific reliability.",[14,3453,3454],{},[17,3455,3456],{},"How does Claude compare to GPT-4o for OpenClaw?",[14,3458,3459],{},"Claude models (particularly Sonnet and Haiku) consistently outperform GPT-4o on the tasks that matter most for OpenClaw: tool calling reliability, long-context accuracy, and prompt injection resistance. GPT-4o is faster on simple tasks and has broader community support. Claude Sonnet 4.6 at $3/$15 is more expensive per output token than GPT-4o at $2.50/$10, but the improved agent performance often means fewer retries and lower total cost.",[14,3461,3462],{},[17,3463,3464],{},"How do I switch AI providers in OpenClaw?",[14,3466,3467,3468,3471,3472,3474,3475,3478],{},"Edit your ",[49,3469,3470],{},"~/.openclaw/openclaw.json"," file to change the model provider and API key, then restart your gateway. For quick switching mid-conversation, use the ",[49,3473,3235],{}," command (for example, ",[49,3476,3477],{},"/model anthropic/claude-sonnet-4-6","). OpenRouter simplifies this further by giving you one API key for 200+ models. The switch takes seconds and doesn't require reinstallation.",[14,3480,3481],{},[17,3482,3483],{},"How much does it cost to run an OpenClaw agent per month?",[14,3485,3486],{},"Monthly costs vary by provider and usage: $80-200 with GPT-4o for everything, $40-70 with Claude Sonnet plus Haiku routing, $15-30 with DeepSeek for most tasks, or $0-5 with Gemini free tier or local models. These are API costs only. Hosting adds $5-29/month depending on whether you self-host on a VPS or use a managed platform like Better Claw. BYOK means you control the API spend regardless of hosting.",[14,3488,3489],{},[17,3490,3491],{},"Is DeepSeek reliable enough for production OpenClaw agents?",[14,3493,3494],{},"DeepSeek V3.2 is reliable for most standard agent tasks and excels at code generation. Community reports confirm it works well for daily operations. The tradeoffs: tool calling can be less precise than Claude on complex multi-step chains, and data routes through Chinese infrastructure, which matters for sensitive workloads. For heartbeats, sub-agents, and non-sensitive tasks, it's a solid budget choice. For critical workflows, pair it with a more capable model as your primary.",{"title":239,"searchDepth":438,"depth":438,"links":3496},[3497,3498,3499,3500,3501,3502,3503,3504,3505,3506],{"id":3061,"depth":438,"text":3062},{"id":3094,"depth":438,"text":3095},{"id":3138,"depth":438,"text":3139},{"id":3176,"depth":438,"text":3177},{"id":3217,"depth":438,"text":3218},{"id":3282,"depth":438,"text":3283},{"id":3330,"depth":438,"text":3331},{"id":3340,"depth":438,"text":3341},{"id":3387,"depth":438,"text":3388},{"id":402,"depth":438,"text":403},"2026-03-10","Stop overpaying for OpenClaw. DeepSeek at $0.28, Gemini free tier, Claude Haiku at $1. Five providers that cut your agent costs 50-90%.","/img/blog/cheapest-openclaw-ai-providers.jpg",{},"/blog/cheapest-openclaw-ai-providers",{"title":3025,"description":3508},"5 Cheapest OpenClaw AI Providers (Save 80% vs OpenAI)","blog/cheapest-openclaw-ai-providers",[3516,3517,3518,3519,3520,3521,3522,3523],"cheapest OpenClaw AI provider","OpenClaw API costs","OpenClaw DeepSeek","OpenClaw Claude vs GPT","OpenRouter OpenClaw","reduce OpenClaw spending","OpenClaw model pricing","cheap AI agent hosting","FTVT6sJTW0sDCb3HgPN7h4D2MF4e0dmF-wveu39DP74",{"id":3526,"title":3527,"author":3528,"body":3529,"category":449,"date":4027,"description":4028,"extension":452,"featured":453,"hideToc":453,"image":4029,"imageHeight":473,"imageWidth":473,"meta":4030,"navigation":458,"path":4031,"readingTime":2255,"redirected":453,"seo":4032,"seoTitle":4033,"stem":4034,"tags":4035,"updatedDate":4043,"__hash__":4044},"blog/blog/how-to-update-openclaw.md","How to Update OpenClaw Without Breaking Your Setup",{"name":7,"role":8,"avatar":9},{"type":11,"value":3530,"toc":4006},[3531,3536,3539,3542,3545,3548,3552,3555,3558,3561,3564,3567,3575,3579,3582,3586,3600,3604,3610,3614,3617,3621,3624,3634,3640,3644,3647,3654,3658,3661,3664,3670,3673,3678,3691,3707,3735,3749,3752,3756,3759,3765,3776,3782,3788,3795,3799,3802,3806,3809,3815,3819,3822,3836,3840,3843,3848,3855,3859,3862,3865,3868,3871,3874,3877,3883,3887,3890,3893,3896,3902,3908,3911,3918,3920,3925,3935,3940,3943,3948,3951,3956,3959,3964,3967,3971,4003],[14,3532,3533],{},[24,3534,3535],{},"Last time you updated, your cron jobs vanished. This time, you'll back up first, update safely, and know exactly how to roll back if anything goes wrong.",[14,3537,3538],{},"I updated OpenClaw on a Tuesday afternoon. By Tuesday evening, my customer support agent had stopped responding on Telegram, three cron jobs had silently deactivated, and my gateway was binding to a different port than before.",[14,3540,3541],{},"The update itself took 30 seconds. The debugging took four hours. The worst part: I could have prevented all of it with a 5-minute backup before hitting the update command.",[14,3543,3544],{},"OpenClaw releases multiple updates per week. Some are minor fixes. Some change config behavior without clear documentation. With 7,900+ open issues on GitHub and the project transitioning to an open-source foundation after Peter Steinberger's move to OpenAI, the pace of change is high and the communication about breaking changes is inconsistent.",[14,3546,3547],{},"Here's how to update OpenClaw safely every time. Bookmark this page. You'll need it again.",[35,3549,3551],{"id":3550},"check-your-current-version-first","Check your current version first",[14,3553,3554],{},"Before you update anything, know what version you're running right now. This matters for two reasons.",[14,3556,3557],{},"First, if something breaks after the update, you need to know which version to roll back to. If you don't know your current version, you can't roll back precisely. You're guessing.",[14,3559,3560],{},"Second, the changelog between your current version and the latest version tells you what changed. If a breaking change happened between your version and the new one, you'll know before you update instead of discovering it through broken behavior.",[14,3562,3563],{},"Run the version check command in your terminal. OpenClaw will report its current version number. Write it down or screenshot it. You'll need this if rollback becomes necessary.",[14,3565,3566],{},"Also check which version is the latest available. Compare the two. If you're one version behind, the risk is low. If you're ten versions behind, read the changelogs for each version in between. Multiple small breaking changes stack up.",[14,3568,3569,3570,3574],{},"For the ",[222,3571,3573],{"href":3572},"/blog/openclaw-setup-guide-complete","complete OpenClaw setup sequence and where updates fit",", our setup guide covers the full installation and configuration flow.",[35,3576,3578],{"id":3577},"back-up-these-four-things-before-you-update","Back up these four things before you update",[14,3580,3581],{},"This takes 5 minutes. It saves hours of debugging if something goes wrong.",[666,3583,3585],{"id":3584},"your-personality-and-memory-files","Your personality and memory files",[14,3587,3588,3589,623,3592,3595,3596,3599],{},"Copy your ",[49,3590,3591],{},"SOUL.md",[49,3593,3594],{},"MEMORY.md",", and ",[49,3597,3598],{},"USER.md"," (if it exists) to a safe location outside the OpenClaw directory. These files define your agent's personality, accumulated knowledge, and user preferences. They're the files you've spent the most time crafting. Losing them means recreating your agent's personality from scratch.",[666,3601,3603],{"id":3602},"your-config-file","Your config file",[14,3605,3588,3606,3609],{},[49,3607,3608],{},"openclaw.json"," (or wherever your configuration lives) to the same backup location. This file contains your model providers, API credentials, channel connections, gateway settings, and every customization you've made. If the update changes config key names or structure, you'll need the original to compare and migrate.",[666,3611,3613],{"id":3612},"your-installed-skills-list","Your installed skills list",[14,3615,3616],{},"Note which skills you have installed and where they came from. After an update, skills can go inactive or need reinstallation. If you don't know which skills you had, you won't notice they're missing until the agent fails to perform a task it used to handle fine.",[666,3618,3620],{"id":3619},"your-cron-jobs-and-scheduled-tasks","Your cron jobs and scheduled tasks",[14,3622,3623],{},"Export or write down anything running on a schedule: morning briefings, hourly checks, heartbeat automations. Scheduled jobs are the easiest thing to lose track of, because a missing one fails silently. Nothing errors, the agent simply stops doing something it used to do, and you notice a week later when you realise the briefing stopped arriving.",[14,3625,3626,3627,623,3629,623,3631,3633],{},"The 5-minute backup rule: copy ",[49,3628,3591],{},[49,3630,3594],{},[49,3632,3598],{},", and your config file to a separate folder before every update. This single habit prevents 90% of update disasters.",[14,3635,3636],{},[80,3637],{"alt":3638,"src":3639},"OpenClaw update backup checklist showing SOUL.md, MEMORY.md, USER.md, and config file in a safe location","/img/blog/how-to-update-openclaw-backup.jpg",[666,3641,3643],{"id":3642},"what-changed-about-backups-in-202692","What changed about backups in 2026.9.2",[14,3645,3646],{},"Two things worth knowing if you are on 2026.9.2 or later. Backup integrity got stricter: corrupt archive headers are now rejected outright rather than accepted as a partial backup, and Skill Workshop backups refuse incomplete directory snapshots. That is the right behaviour, but it means a backup that used to appear to work may now fail loudly instead. Better to find that out before you need it.",[14,3648,3649,3650,122],{},"Restoring also needs free temporary disk space, because the restore prepares a safe copy first and fails if it cannot. If you are restoring onto a nearly full disk, clear space before you start rather than halfway through. The rest of that release, including two defaults that changed, is in our ",[222,3651,3653],{"href":3652},"/blog/openclaw-2026-9-2-update","2026.9.2 breakdown",[35,3655,3657],{"id":3656},"the-actual-update-process","The actual update process",[14,3659,3660],{},"Once you've backed up, the update itself is straightforward.",[14,3662,3663],{},"Run the npm global update command for OpenClaw. This pulls the latest version and replaces the OpenClaw binary. The process typically takes 30-60 seconds depending on your internet speed.",[14,3665,3666,3669],{},[17,3667,3668],{},"What \"success\" looks like:"," The terminal shows the new version number with no error messages. If you see warnings about deprecated dependencies, those are usually harmless. If you see actual errors (permission denied, EACCES, npm ERR!), the update didn't complete and you're still on the old version.",[14,3671,3672],{},"After the update completes, restart your gateway. The new version only takes effect after a gateway restart. If you update but don't restart, you're running the old code with the new binary sitting idle.",[14,3674,3675],{},[17,3676,3677],{},"Two flags worth knowing as of the 2026.9 releases.",[14,3679,3680,3683,3684,3687,3688,3690],{},[49,3681,3682],{},"openclaw update --no-restart"," skips the automatic Gateway restart after a successful update. Use it only when you have already stopped the Gateway yourself, and restart it manually afterwards. Otherwise you get the idle-binary problem described above, just with extra steps. There is one specific case where it is the documented path rather than an option: if you are on ",[49,3685,3686],{},"2026.8.2"," on a machine with no service manager (common on bare Linux installs), run ",[49,3689,3682],{}," once to get past it.",[231,3692,3694],{"className":2530,"code":3693,"language":2532,"meta":239,"style":239},"openclaw update --no-restart\n",[49,3695,3696],{"__ignoreMap":239},[708,3697,3698,3701,3704],{"class":710,"line":711},[708,3699,3700],{"class":2539},"openclaw",[708,3702,3703],{"class":2543}," update",[708,3705,3706],{"class":1138}," --no-restart\n",[14,3708,3709,3712,3713,3716,3717,3720,3721,623,3724,623,3727,3730,3731,3734],{},[49,3710,3711],{},"openclaw update status"," reports where your install actually sits without changing anything. On extended-stable package installs it runs the same public-selector and exact-package verification the foreground update does, and it will tell you when your installed version is ",[24,3714,3715],{},"ahead"," of extended-stable rather than behind. When it fails it returns a ",[49,3718,3719],{},"registry.reason"," in its JSON (",[49,3722,3723],{},"selector_missing",[49,3725,3726],{},"selector_query_failed",[49,3728,3729],{},"exact_package_mismatch",", or ",[49,3732,3733],{},"unsupported_git_channel","), which is usually faster to act on than the update command's own output.",[231,3736,3738],{"className":2530,"code":3737,"language":2532,"meta":239,"style":239},"openclaw update status\n",[49,3739,3740],{"__ignoreMap":239},[708,3741,3742,3744,3746],{"class":710,"line":711},[708,3743,3700],{"class":2539},[708,3745,3703],{"class":2543},[708,3747,3748],{"class":2543}," status\n",[14,3750,3751],{},"The 2026.9 line also made the update itself considerably safer to run: a failed post-update Doctor check now rolls the npm candidate back, config and secret references survive a failed upgrade, failures are handed to a built-in triage agent, and the updater waits for plugin readiness before restarting. If you have been holding off on updating because a previous one stranded you, that is the change that matters.",[35,3753,3755],{"id":3754},"what-to-check-immediately-after-updating","What to check immediately after updating",[14,3757,3758],{},"Don't assume the update worked just because the terminal didn't show errors. Check three things within the first 5 minutes.",[14,3760,3761,3764],{},[17,3762,3763],{},"Is your agent responding?"," Send a test message through your primary channel (Telegram, WhatsApp, whatever you use). If the agent responds normally, the core system is working.",[14,3766,3767,3770,3771,3304,3773,3775],{},[17,3768,3769],{},"Are your memory files intact?"," Check that ",[49,3772,3591],{},[49,3774,3594],{}," are still present and contain the expected content. Some updates have been reported to reset or modify these files. If they've changed, restore from your backup.",[14,3777,3778,3781],{},[17,3779,3780],{},"Are your skills still installed and active?"," Ask your agent to perform a task that requires a specific skill (web search, file operation, calendar check). If the skill fails, it may have been deactivated by the update. Reinstall it.",[14,3783,3784,3787],{},[17,3785,3786],{},"Are your cron jobs still running?"," This is the one people miss. Cron jobs can silently deactivate after updates. Check your cron configuration and verify the schedules are still active. If your morning briefing doesn't arrive tomorrow, this is probably why.",[14,3789,3569,3790,3794],{},[222,3791,3793],{"href":3792},"/blog/openclaw-best-practices","seven practices every stable OpenClaw setup should follow",", our best practices guide covers ongoing maintenance including update hygiene.",[35,3796,3798],{"id":3797},"what-commonly-breaks-between-versions-and-the-quick-fix","What commonly breaks between versions (and the quick fix)",[14,3800,3801],{},"Three things break more often than everything else combined.",[666,3803,3805],{"id":3804},"config-key-renames","Config key renames",[14,3807,3808],{},"OpenClaw occasionally renames config keys between versions. A field that was called one thing in the old version might have a slightly different name in the new version. When this happens, the gateway either ignores the old key (silently dropping your setting) or throws a validation error.",[14,3810,3811,3814],{},[17,3812,3813],{},"Quick fix:"," Compare your backed-up config file with the default config for the new version. Look for keys that exist in your backup but not in the new default. They've probably been renamed. Update the key names and restart.",[666,3816,3818],{"id":3817},"skills-going-inactive","Skills going inactive",[14,3820,3821],{},"Updates can change how skills are loaded or validated. A skill that worked in the previous version might fail validation in the new one due to changed schema requirements, missing fields, or updated security checks.",[14,3823,3824,3826,3827,3831,3832,3835],{},[17,3825,3813],{}," Reinstall the affected skills. If reinstallation fails, check if the skill has been updated on ClawHub to match the new OpenClaw version. If not, the skill may need an update from its maintainer. For the ",[222,3828,3830],{"href":3829},"/blog/openclaw-skills-install-guide","skill vetting and installation guide",", our ",[222,3833,3834],{"href":3006},"skills post"," covers the safe installation process.",[666,3837,3839],{"id":3838},"gateway-binding-changes","Gateway binding changes",[14,3841,3842],{},"Some updates change the default gateway binding behavior. If your gateway was bound to a specific port or address, an update might reset it to the default. This breaks channel connections and API access.",[14,3844,3845,3847],{},[17,3846,3813],{}," Check your gateway config after updating. Verify the bind address and port match what you had before. Restore from your backup if they've changed.",[14,3849,3850,3851,3854],{},"If managing updates, config migrations, and skill compatibility sounds like more maintenance than you want, ",[222,3852,3853],{"href":675},"BetterClaw handles updates automatically",". Your config is preserved. Your skills stay active. Your memory files are intact. $49/month for Pro, BYOK. You never touch any of this.",[35,3856,3858],{"id":3857},"how-to-roll-back-if-something-goes-wrong","How to roll back if something goes wrong",[14,3860,3861],{},"This is the section you'll bookmark.",[14,3863,3864],{},"If the update broke something and you can't fix it quickly, rolling back to the previous version is the fastest path to a working agent.",[14,3866,3867],{},"Install the specific previous version of OpenClaw by specifying the exact version number in the npm install command. Use the version number you wrote down before the update. This replaces the new version with the old one.",[14,3869,3870],{},"After installing the old version, restore your backed-up config file and memory files. Restart the gateway. Your agent should be back to its pre-update state.",[14,3872,3873],{},"The rollback takes about 2 minutes if you have your backup. It takes much longer if you don't, because you'll be trying to recreate settings from memory. This is why the backup step isn't optional.",[14,3875,3876],{},"Rolling back is not failure. It's the smart response when an update introduces problems you can't fix immediately. Update again later when the community has identified and resolved the breaking changes.",[14,3878,3879],{},[80,3880],{"alt":3881,"src":3882},"OpenClaw rollback process showing version pinning, config restore, and gateway restart steps","/img/blog/how-to-update-openclaw-rollback.jpg",[35,3884,3886],{"id":3885},"the-update-schedule-that-actually-works","The update schedule that actually works",[14,3888,3889],{},"Here's what nobody tells you about updating OpenClaw: you don't need to update every time a new version drops.",[14,3891,3892],{},"OpenClaw releases multiple times per week. Most updates are minor. Unless the changelog specifically mentions a security fix (like the CVE-2026-25253 patch for the CVSS 8.8 vulnerability) or a feature you need, waiting a few days lets the community find breaking changes first.",[14,3894,3895],{},"Check the GitHub issues and Discord after a new release. If people report problems, wait for the fix. If the community is quiet, the update is probably safe.",[14,3897,3898,3901],{},[17,3899,3900],{},"Security updates are the exception."," When a CVE is published, update immediately. The one-click RCE vulnerability (CVE-2026-25253) demonstrated why: 30,000+ instances were found exposed without authentication. Delaying security patches creates real risk.",[14,3903,3232,3904,3907],{},[222,3905,3906],{"href":2942},"managed vs self-hosted comparison"," covers how updates are handled across different deployment approaches, including which platforms apply security patches automatically.",[14,3909,3910],{},"For everything else, update weekly or biweekly. Back up first. Check after. Roll back if needed. That's the whole process.",[14,3912,3913,3914,3917],{},"If you'd rather never think about updates again, ",[222,3915,3440],{"href":391,"rel":3916},[393],". $49/month for Pro, BYOK with 28+ providers. Updates are automatic. Config is preserved. Security patches land same-day. Your agent stays current while you focus on what it does, not how it runs.",[35,3919,403],{"id":402},[14,3921,3922],{},[17,3923,3924],{},"How do I update OpenClaw to the latest version?",[14,3926,3927,3928,623,3930,623,3932,3934],{},"Run the npm global update command for OpenClaw in your terminal. Before updating, back up your ",[49,3929,3591],{},[49,3931,3594],{},[49,3933,3598],{},", and config file. After updating, restart the gateway and verify your agent is responding, memory files are intact, skills are active, and cron jobs are running. The update takes about 30-60 seconds. The backup and verification add 10 minutes of safety.",[14,3936,3937],{},[17,3938,3939],{},"What breaks when I update OpenClaw?",[14,3941,3942],{},"The three most common issues are: config key renames (your settings silently stop working), skills going inactive (changed validation requirements), and gateway binding changes (connection settings reset to defaults). All three are fixable by comparing your backed-up config with the new defaults and restoring any changed values. The backup before updating is what makes these fixable instead of catastrophic.",[14,3944,3945],{},[17,3946,3947],{},"How do I roll back an OpenClaw update?",[14,3949,3950],{},"Install the previous version by specifying the exact version number in the npm install command. Restore your backed-up config file and memory files. Restart the gateway. The rollback takes about 2 minutes if you have your backup ready. This is why writing down your current version before updating is essential. Without it, you're guessing which version to roll back to.",[14,3952,3953],{},[17,3954,3955],{},"How often should I update OpenClaw?",[14,3957,3958],{},"For most users, weekly or biweekly updates are sufficient. Wait a day or two after each release to let the community identify breaking changes. The exception is security updates: when a CVE is published (like CVE-2026-25253, a CVSS 8.8 vulnerability), update immediately. On managed platforms like BetterClaw, updates are applied automatically with config preservation, so you never need to manage this manually.",[14,3960,3961],{},[17,3962,3963],{},"Is it safe to skip OpenClaw updates?",[14,3965,3966],{},"Skipping non-security updates for a few weeks is generally fine. Skipping security updates is risky. With 30,000+ exposed instances found without authentication and the ClawHavoc campaign targeting 824+ malicious skills, running outdated versions increases your exposure. The safest approach: apply security patches immediately, delay feature updates by a few days to let the community test them first.",[35,3968,3970],{"id":3969},"related-reading","Related Reading",[203,3972,3973,3979,3985,3991,3997],{},[206,3974,3975,3978],{},[222,3976,3977],{"href":3572},"OpenClaw Setup Guide: Complete Walkthrough"," — Full installation and configuration flow",[206,3980,3981,3984],{},[222,3982,3983],{"href":3792},"OpenClaw Best Practices"," — Seven practices for ongoing maintenance and stability",[206,3986,3987,3990],{},[222,3988,3989],{"href":3006},"Best OpenClaw Skills (Tested & Vetted)"," — Safe skill installation after an update breaks them",[206,3992,3993,3996],{},[222,3994,3995],{"href":2826},"OpenClaw Security Risks Explained"," — Why security patches can't be delayed",[206,3998,3999,4002],{},[222,4000,4001],{"href":2942},"BetterClaw vs Self-Hosted OpenClaw"," — How updates are handled across deployment approaches",[1875,4004,4005],{},"html pre.shiki code .s7eDp, html code.shiki .s7eDp{--shiki-default:#6F42C1}html pre.shiki code .sYBdl, html code.shiki .sYBdl{--shiki-default:#032F62}html pre.shiki code .sYu0t, html code.shiki .sYu0t{--shiki-default:#005CC5}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"title":239,"searchDepth":438,"depth":438,"links":4007},[4008,4009,4016,4017,4018,4023,4024,4025,4026],{"id":3550,"depth":438,"text":3551},{"id":3577,"depth":438,"text":3578,"children":4010},[4011,4012,4013,4014,4015],{"id":3584,"depth":722,"text":3585},{"id":3602,"depth":722,"text":3603},{"id":3612,"depth":722,"text":3613},{"id":3619,"depth":722,"text":3620},{"id":3642,"depth":722,"text":3643},{"id":3656,"depth":438,"text":3657},{"id":3754,"depth":438,"text":3755},{"id":3797,"depth":438,"text":3798,"children":4019},[4020,4021,4022],{"id":3804,"depth":722,"text":3805},{"id":3817,"depth":722,"text":3818},{"id":3838,"depth":722,"text":3839},{"id":3857,"depth":438,"text":3858},{"id":3885,"depth":438,"text":3886},{"id":402,"depth":438,"text":403},{"id":3969,"depth":438,"text":3970},"2026-04-06","Back up 3 files, run the update, check 4 things after. If it breaks, roll back in 2 minutes. Here's the safe OpenClaw update process.","/img/blog/how-to-update-openclaw.jpg",{},"/blog/how-to-update-openclaw",{"title":3527,"description":4028},"How to Update OpenClaw Without Breaking Anything","blog/how-to-update-openclaw",[4036,4037,4038,4039,4040,4041,4042],"how to update OpenClaw","OpenClaw update guide","update OpenClaw safely","OpenClaw breaking changes","OpenClaw rollback","OpenClaw new version","OpenClaw upgrade 2026","2026-09-07","vqZp-pB7L92Ig7XBNFfIUQ5cMoRHtrLKZwPDMHmRB3Y",{"id":4046,"title":4047,"author":4048,"body":4049,"category":449,"date":4465,"description":4466,"extension":452,"featured":453,"hideToc":453,"image":4467,"imageHeight":473,"imageWidth":473,"meta":4468,"navigation":458,"path":4469,"readingTime":4470,"redirected":453,"seo":4471,"seoTitle":4472,"stem":4473,"tags":4474,"updatedDate":4465,"__hash__":4485},"blog/blog/openclaw-agent-hallucination-fix.md","OpenClaw Agent Hallucinating? 5 Fixes That Actually Work (2026)",{"name":7,"role":8,"avatar":9},{"type":11,"value":4050,"toc":4455},[4051,4056,4062,4065,4068,4071,4075,4078,4081,4090,4102,4111,4117,4121,4124,4135,4141,4166,4172,4176,4182,4190,4195,4201,4211,4217,4221,4226,4229,4249,4254,4265,4271,4275,4280,4287,4303,4309,4313,4316,4319,4328,4331,4339,4341,4346,4355,4360,4366,4371,4374,4379,4388,4393,4396,4398],[14,4052,4053],{},[17,4054,4055],{},"Your agent says the task is done. It isn't. It invents files that don't exist, reports prices that are wrong, and confidently completes work it never started. Here are 5 fixes ranked by impact.",[14,4057,4058,4059],{},"A developer on the OpenClaw Discord posted this three weeks ago: ",[24,4060,4061],{},"\"I have been facing a lot of hallucination issues from OpenClaw where it keeps saying things are done but are really not. I can see it starting to ignore some of my questionings. It's starting to run away from problems.\"",[14,4063,4064],{},"Another developer on DEV.to shared something worse: his agent told him a £716 visa cost £70,000. Not a rounding error. A fabrication that would have broken his entire budget if he hadn't caught it.",[14,4066,4067],{},"The agent doesn't know it's wrong. That's the terrifying part.",[14,4069,4070],{},"OpenClaw agent hallucination isn't a model problem you can't fix. It's a context management problem, an instruction problem, and a verification problem. Here are five fixes ranked by how much they actually reduce hallucination in practice.",[35,4072,4074],{"id":4073},"fix-1-replace-black-box-skills-with-agentsmd-index-entries-biggest-impact","Fix 1: Replace \"black box\" skills with AGENTS.md index entries (biggest impact)",[14,4076,4077],{},"The breakthrough: A developer on DEV.to described spending weeks building complex \"Research Skills\" to force his agent to be accurate. The skills became black boxes. He pushed a button, the AI disappeared into a script, and came back with wrong answers.",[14,4079,4080],{},"Then he read Vercel's AI team research: dividing project knowledge into indices (markdown) versus skills (executable code) dramatically reduces hallucination.",[14,4082,4083,4086,4087,4089],{},[17,4084,4085],{},"Why it works:"," When the agent has structured reference material in ",[49,4088,865],{}," (a knowledge index), it looks up facts instead of generating them. When it has only a skill (executable code), it guesses at inputs and invents outputs it thinks the skill should produce.",[14,4091,4092,4095,4096,4098,4099,4101],{},[17,4093,4094],{},"The fix:"," Delete complex skills that wrap simple lookups. Replace them with index entries in ",[49,4097,865],{},". If your agent needs to know your pricing, put the pricing in ",[49,4100,865],{},". Don't make it call a skill that fetches pricing from an API. The index is cheaper (no tool call), faster (no round-trip), and more accurate (no fabrication of missing API fields).",[14,4103,4104,4107,4108,4110],{},[17,4105,4106],{},"The index vs skill rule:"," If the information is static and known, put it in ",[49,4109,865],{}," as an index entry. If the action requires executing something (sending email, calling API, writing files), keep it as a skill. Most hallucinations happen when skills are used for lookups that should be index entries.",[14,4112,4113],{},[80,4114],{"alt":4115,"src":4116},"Diagram contrasting black-box skill calls that fabricate pricing against AGENTS.md index lookups that return correct prices","/img/blog/openclaw-agent-hallucination-fix-agents-md.jpg",[35,4118,4120],{"id":4119},"fix-2-trim-your-context-window-the-hidden-cause-of-hallucination","Fix 2: Trim your context window (the hidden cause of hallucination)",[14,4122,4123],{},"Here's what nobody tells you about agent hallucination.",[14,4125,4126,4127,4129,4130,4129,4132,4134],{},"Context bloat causes hallucination. When your system prompt is 15,000+ tokens (",[49,4128,865],{}," + ",[49,4131,3591],{},[49,4133,3594],{}," + 23 tool schemas), the model's attention is spread across too much information. It starts confusing details from one section with details from another. It \"remembers\" instructions that don't exist because it's interpolating between overlapping context.",[14,4136,4137,4138,4140],{},"Research confirms this: models exhibit \"lost-in-the-middle\" bias. They track the beginning and end of context but lose the middle. If your agent's critical instructions are buried in the middle of a 10,000-token ",[49,4139,3591],{},", the model literally doesn't attend to them reliably.",[14,4142,4143,4145,4146,4129,4148,4129,4150,4152,4153,4156,4157,4160,4161,4165],{},[17,4144,4094],{}," Keep ",[49,4147,865],{},[49,4149,3591],{},[49,4151,3594],{}," under 5,000 tokens combined. Set ",[49,4154,4155],{},"contextTokens: 50000"," to prevent unbounded context growth. Start new sessions regularly with ",[49,4158,4159],{},"/new"," to clear accumulated context. For the ",[222,4162,4164],{"href":4163},"/blog/openclaw-reduce-cost","complete context optimization guide",", our guide covers the token math and specific trim targets.",[14,4167,4168],{},[80,4169],{"alt":4170,"src":4171},"Attention curve over a 15,000-token system prompt showing the lost-in-the-middle drop-off and the three-part fix to trim AGENTS.md, SOUL.md, MEMORY.md under 5,000 tokens","/img/blog/openclaw-agent-hallucination-fix-context.jpg",[35,4173,4175],{"id":4174},"fix-3-add-verification-instructions-to-your-soulmd","Fix 3: Add verification instructions to your SOUL.md",[14,4177,4178,4181],{},[17,4179,4180],{},"The problem:"," By default, OpenClaw agents don't verify their own work. The agent says \"I've sent the email\" without checking whether the email tool returned a success response. It says \"I've created the file\" without confirming the file exists.",[14,4183,4184,4186,4187,4189],{},[17,4185,4094],{}," Add explicit verification rules to your ",[49,4188,3591],{},":",[54,4191,4192],{},[14,4193,4194],{},"\"After completing any task, verify the result before reporting. If you used a tool, check the tool's response for errors. If you created a file, read it back to confirm. If you sent a message, confirm delivery. Never report a task as complete without verification evidence.\"",[14,4196,4197,4200],{},[17,4198,4199],{},"Why this works:"," Claude Opus 4.7 introduced self-verification behavior (\"devises ways to verify its own outputs before reporting back\"). But this behavior isn't activated by default in OpenClaw. You need to explicitly instruct the agent to verify. Other models (GPT-5.5, DeepSeek V4) don't self-verify at all without instructions.",[14,4202,4203,4204,4207,4208,4210],{},"For the best practices for agent configuration, ",[222,4205,4206],{"href":3792},"our OpenClaw best practices guide"," covers ",[49,4209,3591],{}," patterns that reduce both hallucination and token waste.",[14,4212,4213],{},[80,4214],{"alt":4215,"src":4216},"Default no-verification flow on top showing agent reports done without checking, contrasted with the SOUL.md verification rule that catches \"says done but is not\" errors","/img/blog/openclaw-agent-hallucination-fix-verification.jpg",[35,4218,4220],{"id":4219},"fix-4-use-the-right-model-for-the-task-model-mismatch-causes-hallucination","Fix 4: Use the right model for the task (model mismatch causes hallucination)",[14,4222,4223,4225],{},[17,4224,4180],{}," Different models hallucinate at different rates on different tasks. Using a cheap model for complex reasoning produces more fabrication. Using a powerful model for simple tasks wastes money without reducing hallucination.",[14,4227,4228],{},"The pattern from real usage:",[203,4230,4231,4237,4243],{},[206,4232,4233,4236],{},[17,4234,4235],{},"DeepSeek V4 Flash ($0.14/M tokens):"," Good for routine Q&A, FAQ, scheduling. Hallucinates on multi-step research, number-heavy tasks, and anything requiring precise recall of specific facts.",[206,4238,4239,4242],{},[17,4240,4241],{},"Claude Sonnet 4.6 ($3/$15/M tokens):"," The sweet spot for most agent tasks. Low hallucination rate on structured tasks. Good instruction following.",[206,4244,4245,4248],{},[17,4246,4247],{},"Claude Opus 4.7 ($5/$25/M tokens):"," Lowest hallucination rate overall, especially on complex multi-step tasks. Self-verification behavior reduces \"says done but isn't\" errors. But the new tokenizer adds 12-35% more tokens, increasing cost.",[14,4250,4251,4253],{},[17,4252,4094],{}," Route complex, high-stakes tasks (research, financial data, client communications) to Opus or Sonnet. Route routine tasks (FAQ, scheduling, simple Q&A) to V4 Flash. Don't use one model for everything.",[14,4255,4256,4257,4259,4260,4264],{},"If managing model routing, context limits, verification instructions, and ",[49,4258,865],{}," structure sounds like more agent tuning than you want, ",[222,4261,4263],{"href":4262},"/openclaw-alternative","BetterClaw's smart context management reduces hallucination at the platform level",". We don't inject bloated workspace files. We optimize context delivery. We monitor for anomalous outputs and auto-pause when the agent loops. Free tier with 1 agent and BYOK. $49/month for Pro.",[14,4266,4267],{},[80,4268],{"alt":4269,"src":4270},"Per-task hallucination-rate comparison across DeepSeek V4 Flash, Claude Sonnet 4.6, and Claude Opus 4.7 with routing recommendations for complex vs routine tasks","/img/blog/openclaw-agent-hallucination-fix-models.jpg",[35,4272,4274],{"id":4273},"fix-5-constrain-tool-calling-stop-the-hallucination-loop","Fix 5: Constrain tool calling (stop the hallucination loop)",[14,4276,4277,4279],{},[17,4278,4180],{}," Sometimes the agent hallucinates tool calls. It calls a tool with invented parameters, gets an error, then hallucinates a \"fix\" by calling the tool again with different invented parameters. This loops until the model hits its token limit or the session stalls.",[14,4281,4282,4286],{},[222,4283,4285],{"href":4284},"/blog/openclaw-common-errors","The BetterClaw blog documented this"," as one of the 10 most common OpenClaw errors: \"agent stuck in loop, hallucinating tool use.\"",[14,4288,4289,4291,4292,4295,4296,4298,4299,122],{},[17,4290,4094],{}," Set ",[49,4293,4294],{},"maxToolCalls"," in your agent config to limit tool calls per turn (5-10 is reasonable). Add to your ",[49,4297,3591],{},": \"If a tool call fails twice, stop and report the error. Do not retry with guessed parameters.\" Enable OpenClaw's health monitoring to detect and ",[222,4300,4302],{"href":4301},"/blog/openclaw-agent-stuck-in-loop","pause looping agents",[14,4304,4305],{},[80,4306],{"alt":4307,"src":4308},"Anatomy of a hallucination loop where the agent retries tool calls with invented parameters until tokens run out, and the three-part fix using maxToolCalls, SOUL.md rule, and OpenClaw health monitoring","/img/blog/openclaw-agent-hallucination-fix-tool-loop.jpg",[35,4310,4312],{"id":4311},"the-honest-take-hallucination-is-a-feature-not-a-bug","The honest take (hallucination is a feature, not a bug)",[14,4314,4315],{},"Here's the uncomfortable truth.",[14,4317,4318],{},"Hallucination is what makes these models useful. The same ability that lets the model generate creative responses, draft emails in your tone, and solve problems it hasn't seen before is the same ability that lets it invent files that don't exist and report tasks it didn't complete.",[14,4320,4321,4322,4324,4325,4327],{},"You can't eliminate hallucination without eliminating creativity. What you can do is constrain it: give the model facts instead of making it guess (",[49,4323,865],{}," index), limit how much context it juggles (trim workspace files), force it to verify its work (",[49,4326,3591],{}," instructions), match the model to the task (routing), and stop it from looping (tool call limits).",[14,4329,4330],{},"The agents that work best in production aren't the ones that never hallucinate. They're the ones whose operators built the guardrails to catch hallucination before it matters.",[14,4332,4333,4334,4338],{},"If you want those guardrails built into the platform, ",[222,4335,4337],{"href":391,"rel":4336},[393],"give BetterClaw a try",". Free tier with 1 agent and BYOK. $49/month for Pro. Smart context management. Anomaly detection. Auto-pause on loops. The agent still uses an LLM. But the platform catches the moments when the LLM loses the plot.",[35,4340,403],{"id":402},[14,4342,4343],{},[17,4344,4345],{},"Why does my OpenClaw agent hallucinate?",[14,4347,4348,4349,4351,4352,4354],{},"Five main causes: bloated context (15,000+ token system prompts cause the model to lose focus), vague instructions (no verification requirements in ",[49,4350,3591],{},"), wrong model for the task (cheap models hallucinate more on complex tasks), black box skills that should be ",[49,4353,865],{}," index entries, and unconstrained tool calling (the agent loops on failed tool calls with invented parameters). Each cause has a specific fix.",[14,4356,4357],{},[17,4358,4359],{},"How do I stop my OpenClaw agent from saying tasks are done when they aren't?",[14,4361,4362,4363,4365],{},"Add explicit verification instructions to your ",[49,4364,3591],{},": \"After completing any task, verify the result before reporting. Check tool responses for errors. Read back files you created. Confirm message delivery. Never report a task as complete without evidence.\" Claude Opus 4.7 has built-in self-verification behavior, but other models need explicit instructions.",[14,4367,4368],{},[17,4369,4370],{},"Does the AI model affect OpenClaw hallucination rate?",[14,4372,4373],{},"Yes, significantly. Claude Opus 4.7 has the lowest hallucination rate and built-in self-verification. Claude Sonnet 4.6 is the best value for low-hallucination agent tasks. DeepSeek V4 Flash hallucinates more on complex reasoning but is fine for routine Q&A. Route complex tasks to better models. Don't use one model for everything.",[14,4375,4376],{},[17,4377,4378],{},"Can I reduce hallucination without switching models?",[14,4380,4381,4382,4384,4385,4387],{},"Yes. Three non-model fixes work immediately: trim workspace files to under 5,000 tokens combined (reduces context confusion), replace complex skills with ",[49,4383,865],{}," index entries (gives the model facts instead of making it guess), and add verification instructions to ",[49,4386,3591],{}," (forces the agent to check its work). These three fixes reduce hallucination noticeably regardless of model.",[14,4389,4390],{},[17,4391,4392],{},"Does BetterClaw reduce agent hallucination compared to self-hosted OpenClaw?",[14,4394,4395],{},"BetterClaw's smart context management reduces the context bloat that causes hallucination. The platform doesn't inject 15,000+ tokens of overhead on every call. Anomaly detection catches looping agents (hallucinating tool use) and auto-pauses them. Verified skills eliminate the black-box skill problem. The model still hallucinates sometimes (all LLMs do), but the platform reduces the structural causes.",[35,4397,3970],{"id":3969},[203,4399,4400,4407,4421,4429,4435,4441,4448],{},[206,4401,4402,4406],{},[222,4403,4405],{"href":4404},"/blog/openclaw-agent-hallucinating-fix","OpenClaw Agent Hallucinating? Why It's Describing Tasks Instead of Doing Them"," — The diagnostic-first companion piece on tool-call failure modes",[206,4408,4409,4413,4414,623,4416,623,4418,4420],{},[222,4410,4412],{"href":4411},"/blog/openclaw-agents-md-optimization","Stop Making Your OpenClaw Agent Re-Read Files on Every Message"," — How to trim ",[49,4415,865],{},[49,4417,3591],{},[49,4419,3594],{}," token bloat",[206,4422,4423,4425,4426,4428],{},[222,4424,3983],{"href":3792}," — ",[49,4427,3591],{}," patterns that reduce hallucination",[206,4430,4431,4434],{},[222,4432,4433],{"href":4301},"OpenClaw Agent Stuck in Loop"," — Detect and break tool-call retry loops",[206,4436,4437,4440],{},[222,4438,4439],{"href":4284},"10 Most Common OpenClaw Errors"," — Quick-reference index of failure modes",[206,4442,4443,4447],{},[222,4444,4446],{"href":4445},"/blog/openclaw-model-does-not-support-tools","\"Model Does Not Support Tools\" Fix"," — Tool-calling compatibility by model",[206,4449,4450,4454],{},[222,4451,4453],{"href":4452},"/blog/openclaw-context-window-reached","OpenClaw Context Window Reached"," — Fix the bloat that causes \"lost-in-the-middle\"",{"title":239,"searchDepth":438,"depth":438,"links":4456},[4457,4458,4459,4460,4461,4462,4463,4464],{"id":4073,"depth":438,"text":4074},{"id":4119,"depth":438,"text":4120},{"id":4174,"depth":438,"text":4175},{"id":4219,"depth":438,"text":4220},{"id":4273,"depth":438,"text":4274},{"id":4311,"depth":438,"text":4312},{"id":402,"depth":438,"text":403},{"id":3969,"depth":438,"text":3970},"2026-05-12","OpenClaw agent says tasks are done but they aren't? Five fixes: AGENTS.md index, context trimming, verification rules, model routing, tool call limits.","/img/blog/openclaw-agent-hallucination-fix.jpg",{},"/blog/openclaw-agent-hallucination-fix","11 min read",{"title":4047,"description":4466},"OpenClaw Agent Hallucinating? 5 Fixes (2026)","blog/openclaw-agent-hallucination-fix",[4475,4476,4477,4478,4479,4480,4481,4482,4483,4484],"OpenClaw hallucination fix","OpenClaw agent making things up","OpenClaw wrong answers","AI agent hallucination","OpenClaw verification","reduce OpenClaw hallucination","AGENTS.md index","OpenClaw context trimming","OpenClaw SOUL.md","OpenClaw tool call limits","cElGvb43pqSJ9pzO0_JPvuErOqsTBw_RpoF3N6XC3yc",{"id":4487,"title":4412,"author":4488,"body":4489,"category":449,"date":4891,"description":4892,"extension":452,"featured":453,"hideToc":453,"image":4893,"imageHeight":473,"imageWidth":473,"meta":4894,"navigation":458,"path":4411,"readingTime":2255,"redirected":453,"seo":4895,"seoTitle":4896,"stem":4897,"tags":4898,"updatedDate":4891,"__hash__":4909},"blog/blog/openclaw-agents-md-optimization.md",{"name":7,"role":8,"avatar":9},{"type":11,"value":4490,"toc":4877},[4491,4496,4499,4502,4512,4515,4521,4524,4528,4539,4548,4559,4565,4576,4582,4594,4607,4613,4619,4623,4626,4639,4642,4649,4657,4676,4679,4685,4689,4692,4697,4706,4712,4716,4719,4725,4728,4736,4742,4749,4755,4759,4765,4779,4784,4801,4804,4810,4817,4819,4823,4833,4837,4847,4851,4860,4864,4867,4871,4874],[14,4492,4493],{},[17,4494,4495],{},"Your AGENTS.md, SOUL.md, and MEMORY.md are injected into every API call. At 10,000 tokens combined, that's 10K tokens of overhead before you've even said hello. Here's how to cut it by 60%.",[14,4497,4498],{},"One user reported their OpenClaw session context hitting 56-58% of a 400K token window. That's 230,000 tokens being resent with every single message. Not because the conversation was long. Because the workspace files were bloated.",[14,4500,4501],{},"The conversation was 20 messages. The overhead was 230,000 tokens.",[14,4503,4504,4505,623,4507,623,4509,4511],{},"Here's what nobody tells you about OpenClaw's architecture: your ",[49,4506,865],{},[49,4508,3591],{},[49,4510,3594],{},", tool schemas, skill descriptions, and runtime metadata are rebuilt and injected into the system prompt on every API call. Not once per session. Every message. Every heartbeat. Every tool call response.",[14,4513,4514],{},"The base system prompt alone contributes approximately 15,000 tokens before you've typed anything. That's 23 tool definitions with their schemas, your workspace files, skill descriptions, self-update instructions, time and runtime metadata, and safety headers.",[14,4516,4517,4518],{},"At Opus 4.7 pricing ($5 per million input tokens), 15,000 tokens of overhead on every message costs about $0.075 per message. Send 50 messages a day? That's $3.75/day in pure overhead. ",[17,4519,4520],{},"$112/month on tokens that have nothing to do with your actual conversations.",[14,4522,4523],{},"Here's how to cut that by 60% in about 10 minutes.",[35,4525,4527],{"id":4526},"the-three-files-that-drain-your-tokens-and-what-to-do-about-each","The Three Files That Drain Your Tokens (and What to Do About Each)",[14,4529,4530,4531,4534,4535,4538],{},"OpenClaw injects several workspace files into every API call. These are the bootstrap files controlled by ",[49,4532,4533],{},"agents.defaults.bootstrapMaxChars"," (default: 12,000 per file) and ",[49,4536,4537],{},"agents.defaults.bootstrapTotalMaxChars"," (default: 60,000 total).",[14,4540,4541,4544,4545,4547],{},[17,4542,4543],{},"AGENTS.md is usually the biggest offender."," Community examples range from 200 lines (lean) to 420+ lines (bloated). A 420-line ",[49,4546,865],{}," can easily consume 5,000-8,000 tokens. Every. Single. Message.",[14,4549,4550,4552,4553,4555,4556,4558],{},[17,4551,4094],{}," Cut your ",[49,4554,865],{}," to under 100 lines. Remove verbose explanations. Remove examples the model doesn't need. Remove redundant instructions. The model is smart enough to infer intent from concise instructions. If your ",[49,4557,865],{}," tells the model how to format responses in 50 lines, replace it with 5.",[14,4560,4561,4564],{},[17,4562,4563],{},"SOUL.md defines your agent's personality and behavior."," Most users write this as a creative essay. It should be a checklist.",[14,4566,4567,4145,4569,4571,4572,4575],{},[17,4568,4094],{},[49,4570,3591],{}," under 1,500 tokens. ",[24,4573,4574],{},"\"You are a helpful assistant. Be concise. Use casual tone. Don't apologize unnecessarily.\""," is 20 tokens. A 3-paragraph personality essay is 500 tokens. The model performs identically on both.",[14,4577,4578,4581],{},[17,4579,4580],{},"MEMORY.md grows over time"," as you add facts about yourself. After months of use, it can reach 5,000+ tokens.",[14,4583,4584,4586,4587,4589,4590,4593],{},[17,4585,4094],{}," OpenClaw's official guidance: keep ",[49,4588,3594],{}," under 3,000 tokens. Review it monthly. Remove outdated facts. Consolidate redundant entries. Use the daily memory files (",[49,4591,4592],{},"memory/*.md",") for time-specific context that doesn't need to be in every prompt.",[14,4595,4596,4599,4600,4129,4602,4129,4604,4606],{},[17,4597,4598],{},"The optimization rule:"," ",[49,4601,865],{},[49,4603,3591],{},[49,4605,3594],{}," combined should stay under 5,000 tokens. The default cap is 60,000. Most users are burning 10,000-15,000 tokens per message on these files alone. Cutting to 5,000 saves 5,000-10,000 tokens per message, per heartbeat, per tool call.",[14,4608,3569,4609,4612],{},[222,4610,4611],{"href":4163},"complete guide to reducing OpenClaw costs",", our cost optimization stack covers the other five token drains beyond workspace files.",[14,4614,4615],{},[80,4616],{"alt":4617,"src":4618},"Diagram of the three workspace files (AGENTS.md, SOUL.md, MEMORY.md) that drain tokens and what to do about each","/img/blog/openclaw-agents-md-three-files.jpg",[35,4620,4622],{"id":4621},"the-tool-call-multiplication-problem-the-part-nobody-talks-about","The Tool Call Multiplication Problem (the Part Nobody Talks About)",[14,4624,4625],{},"But that's not even the real problem.",[14,4627,4628,4629,623,4632,623,4635,4638],{},"Here's what the workspace file optimization guides miss: tool calls multiply the overhead. When your agent calls a tool (",[49,4630,4631],{},"file_read",[49,4633,4634],{},"run_bash",[49,4636,4637],{},"web_search","), the tool result is added to the context. Then the model is called again to process the result. That second call includes the full system prompt again.",[14,4640,4641],{},"A single user message that triggers 5 tool calls means 6 API calls (original + 5 tool responses). Each one includes your full 15,000-token system prompt. That's 90,000 tokens of system prompt overhead for one user message.",[14,4643,4644,4645,4648],{},"Example from real OpenClaw usage: ",[24,4646,4647],{},"\"Help me organize today's emails and create to-do items.\""," This triggers: email skill to fetch list, analyze each email, determine priority, call Todoist skill to create tasks, generate summary. Five to ten API calls, each carrying the full context.",[14,4650,4651,4653,4654,4656],{},[17,4652,4094],{}," Two things. First, trim the workspace files (previous section). Second, set ",[49,4655,3367],{}," to cap how much history accumulates between compactions:",[231,4658,4662],{"className":4659,"code":4660,"language":4661,"meta":239,"style":239},"language-yaml shiki shiki-themes github-light","agents.defaults.contextTokens: 50000\n","yaml",[49,4663,4664],{"__ignoreMap":239},[708,4665,4666,4670,4673],{"class":710,"line":711},[708,4667,4669],{"class":4668},"shJU0","agents.defaults.contextTokens",[708,4671,4672],{"class":1116},": ",[708,4674,4675],{"class":1138},"50000\n",[14,4677,4678],{},"This limits the total context window to 50K tokens instead of letting it grow to the model's maximum (200K-1M). Smaller context = faster responses + lower cost per message. The trade-off: the agent forgets older conversation history sooner.",[14,4680,4681],{},[80,4682],{"alt":4683,"src":4684},"Diagram of the tool call multiplication problem showing how 5 tool calls become 6 API calls each carrying the full 15,000-token system prompt","/img/blog/openclaw-agents-md-tool-call-multiplication.jpg",[35,4686,4688],{"id":4687},"the-heartbeat-overhead-the-silent-drain-nobody-checks","The Heartbeat Overhead (the Silent Drain Nobody Checks)",[14,4690,4691],{},"OpenClaw's heartbeat system fires every 55-60 minutes, 24/7. Each heartbeat is a full API call with the complete system prompt. That's 15,000 tokens minimum per heartbeat, even if the heartbeat does nothing.",[14,4693,4694,4696],{},[17,4695,3296],{}," 24 heartbeats/day × 15,000 tokens = 360,000 tokens/day in heartbeat overhead alone. At Opus 4.7 pricing: $1.80/day just to keep the agent alive. That's $54/month before you've asked a single question.",[14,4698,4699,4701,4702,4705],{},[17,4700,4094],{}," Route heartbeats to your cheapest model. The heartbeat doesn't need Opus-level reasoning to check if an email arrived. DeepSeek V4 Flash at $0.14/M tokens handles heartbeats perfectly. That drops the heartbeat cost from $54/month to $1.50/month. For the ",[222,4703,4704],{"href":3511},"cheapest model options",", our provider guide covers routing by task type.",[14,4707,4708],{},[80,4709],{"alt":4710,"src":4711},"Diagram of the heartbeat overhead: 24 heartbeats per day × 15,000 tokens = $54/month before any user message","/img/blog/openclaw-agents-md-heartbeat-overhead.jpg",[35,4713,4715],{"id":4714},"the-prompt-caching-trick-the-90-discount-most-users-miss","The Prompt Caching Trick (the 90% Discount Most Users Miss)",[14,4717,4718],{},"Here's what nobody tells you about Anthropic's prompt caching.",[14,4720,4721,4722],{},"If your system prompt stays identical between API calls, Anthropic caches it and charges only 10% on subsequent calls. That 15,000-token system prompt costs $0.075 on the first call and $0.0075 on every cached call. ",[17,4723,4724],{},"A 90% discount on the overhead.",[14,4726,4727],{},"But here's the catch: If you include dynamic content in your workspace files (timestamps, dates, changing metadata), the cache is invalidated on every call. Every call pays full price.",[14,4729,4730,4732,4733,4735],{},[17,4731,4094],{}," Keep workspace files 100% static. Don't include \"Current Date: May 8, 2026\" in your ",[49,4734,865],{},". Let the model infer the date from conversation context, or inject it in the user message (not the system prompt). One user reported that removing a dynamic timestamp from their workspace file dropped their effective input cost by 80%.",[14,4737,4738,4741],{},[17,4739,4740],{},"For heartbeat caching:"," Set the heartbeat interval to just under your model's cache TTL. If the cache TTL is 60 minutes, set heartbeat to 55 minutes. The heartbeat keeps the cache warm, and every subsequent message benefits from cached pricing. The heartbeat pays for itself.",[14,4743,4744,4745,4748],{},"If managing workspace file sizes, context limits, heartbeat routing, prompt caching TTLs, and tool call multiplication sounds like more optimization work than you signed up for, ",[222,4746,4747],{"href":4262},"BetterClaw's smart context management handles all of this at the platform level",". We don't inject bloated workspace files on every call. We don't send full context with heartbeats. We optimize the token flow so you pay for conversations, not housekeeping. Free tier with 1 agent and BYOK. $49/month for Pro.",[14,4750,4751],{},[80,4752],{"alt":4753,"src":4754},"Diagram of Anthropic prompt caching: identical system prompts get a 90% discount on subsequent calls when workspace files stay static","/img/blog/openclaw-agents-md-prompt-caching.jpg",[35,4756,4758],{"id":4757},"the-real-savings-before-and-after","The Real Savings (Before and After)",[14,4760,4761,4762],{},"Here's a real scenario from the community. ",[17,4763,4764],{},"Before optimization:",[14,4766,4767,4769,4770,4772,4773,4775,4776],{},[49,4768,865],{},": 420 lines (8,000 tokens). ",[49,4771,3591],{},": personality essay (3,000 tokens). ",[49,4774,3594],{},": 6 months of facts (4,000 tokens). Dynamic timestamp in workspace. Heartbeats on Opus. No context limit. ",[17,4777,4778],{},"Monthly cost: $166.",[14,4780,4781],{},[17,4782,4783],{},"After applying the four fixes:",[14,4785,4786,4788,4789,4791,4792,4794,4795,4797,4798],{},[49,4787,865],{},": 80 lines (2,000 tokens). ",[49,4790,3591],{},": checklist format (500 tokens). ",[49,4793,3594],{},": pruned to current facts (2,500 tokens). Static workspace files (caching active). Heartbeats on DeepSeek V4 Flash. ",[49,4796,4155],{},". ",[17,4799,4800],{},"Monthly cost: $27. Saved: $139/month.",[14,4802,4803],{},"One tech blogger reported dropping from $87/month to $27/month by applying just the top three optimizations (model routing, workspace trimming, and heartbeat routing).",[14,4805,4806,4807,4809],{},"The optimization that saves the most is the one you should do first: trim your ",[49,4808,865],{},". Ten minutes of editing. Measurable savings on every message, every heartbeat, every tool call, from that point forward.",[14,4811,4812,4813,4816],{},"If you want the optimized context management without the manual work, ",[222,4814,4337],{"href":391,"rel":4815},[393],". Free plan. $49/month Pro. 28+ model providers. Smart context management that keeps tokens low on every call. The bootstrap overhead is our problem. The conversations are yours.",[35,4818,403],{"id":402},[666,4820,4822],{"id":4821},"what-is-openclaw-agentsmd-and-why-does-it-cost-tokens","What is OpenClaw AGENTS.md and why does it cost tokens?",[14,4824,4825,4827,4828,623,4830,4832],{},[49,4826,865],{}," is one of several workspace files that OpenClaw injects into the system prompt on every API call. Along with ",[49,4829,3591],{},[49,4831,3594],{},", tool schemas, and skill descriptions, it forms the \"bootstrap\" context that the model reads before processing your message. The base system prompt contributes approximately 15,000 tokens per call. This is re-sent with every message, heartbeat, and tool call response.",[666,4834,4836],{"id":4835},"how-many-tokens-does-the-openclaw-system-prompt-use","How many tokens does the OpenClaw system prompt use?",[14,4838,4839,4840,623,4842,623,4844,4846],{},"Approximately 15,000 tokens before you've typed anything. This includes 23 tool definitions with schemas (~5,000 tokens), workspace files (",[49,4841,865],{},[49,4843,3591],{},[49,4845,3594],{},", typically 5,000-15,000 tokens combined), skill descriptions, runtime metadata, and safety headers. The default bootstrap cap is 60,000 total characters, but most users hit 10,000-15,000 tokens.",[666,4848,4850],{"id":4849},"how-do-i-reduce-my-openclaw-agentsmd-token-count","How do I reduce my OpenClaw AGENTS.md token count?",[14,4852,4853,4854,4856,4857,4859],{},"Cut it to under 100 lines and 2,000 tokens. Remove verbose explanations (the model infers intent from concise instructions). Remove examples it doesn't need. Remove redundant formatting instructions. Keep ",[49,4855,3591],{}," under 500 tokens (checklist, not essay). Keep ",[49,4858,3594],{}," under 3,000 tokens (prune monthly). Combined target: under 5,000 tokens for all three.",[666,4861,4863],{"id":4862},"how-much-does-openclaw-context-bloat-actually-cost","How much does OpenClaw context bloat actually cost?",[14,4865,4866],{},"At Opus 4.7 pricing ($5/M input tokens): 15,000 tokens of overhead per message costs $0.075. At 50 messages/day plus 24 heartbeats: approximately $5.55/day or $166/month in pure overhead. After optimization (5,000 tokens, heartbeats on V4 Flash, caching active): approximately $0.90/day or $27/month. Savings: $139/month.",[666,4868,4870],{"id":4869},"does-betterclaw-have-the-same-agentsmd-token-drain","Does BetterClaw have the same AGENTS.md token drain?",[14,4872,4873],{},"No. BetterClaw's smart context management doesn't inject bloated workspace files on every API call. The platform manages context at the infrastructure level, keeping token overhead minimal regardless of how much configuration or memory your agent has. This is one of the key technical differences between self-hosted OpenClaw and BetterClaw as a managed platform.",[1875,4875,4876],{},"html pre.shiki code .shJU0, html code.shiki .shJU0{--shiki-default:#22863A}html pre.shiki code .sgsFI, html code.shiki .sgsFI{--shiki-default:#24292E}html pre.shiki code .sYu0t, html code.shiki .sYu0t{--shiki-default:#005CC5}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"title":239,"searchDepth":438,"depth":438,"links":4878},[4879,4880,4881,4882,4883,4884],{"id":4526,"depth":438,"text":4527},{"id":4621,"depth":438,"text":4622},{"id":4687,"depth":438,"text":4688},{"id":4714,"depth":438,"text":4715},{"id":4757,"depth":438,"text":4758},{"id":402,"depth":438,"text":403,"children":4885},[4886,4887,4888,4889,4890],{"id":4821,"depth":722,"text":4822},{"id":4835,"depth":722,"text":4836},{"id":4849,"depth":722,"text":4850},{"id":4862,"depth":722,"text":4863},{"id":4869,"depth":722,"text":4870},"2026-05-11","Your AGENTS.md adds 15,000 tokens to every API call. Trim it, cache it, and route heartbeats to save $139/month. Here is the 10-minute fix.","/img/blog/openclaw-agents-md-optimization.jpg",{},{"title":4412,"description":4892},"OpenClaw AGENTS.md Token Drain: 60% Cost Reduction (2026)","blog/openclaw-agents-md-optimization",[4899,4900,4901,4902,4903,4904,4905,4906,4907,4908],"OpenClaw AGENTS.md optimization","OpenClaw token cost","OpenClaw reduce tokens","OpenClaw system prompt overhead","AGENTS.md token drain","OpenClaw context bloat","OpenClaw workspace files","OpenClaw heartbeat cost","OpenClaw prompt caching","SOUL.md MEMORY.md tokens","L8ep-34NgpMaRkRd3uOAelQpYKNUSdZ9dH252JhfZLg",{"id":4911,"title":4912,"author":4913,"body":4914,"category":449,"date":5411,"description":5412,"extension":452,"featured":453,"hideToc":453,"image":5413,"imageHeight":473,"imageWidth":473,"meta":5414,"navigation":458,"path":3083,"readingTime":5415,"redirected":453,"seo":5416,"seoTitle":5417,"stem":5418,"tags":5419,"updatedDate":5411,"__hash__":5428},"blog/blog/openclaw-api-costs.md","OpenClaw API Costs: Why You're Overspending and How to Fix It",{"name":7,"role":8,"avatar":9},{"type":11,"value":4915,"toc":5389},[4916,4921,4924,4929,4932,4939,4945,4950,4953,4960,4966,4971,4974,4977,4981,4987,4994,5001,5004,5007,5012,5015,5018,5022,5025,5029,5032,5035,5042,5045,5049,5052,5055,5061,5064,5068,5071,5074,5080,5084,5087,5090,5093,5097,5100,5107,5114,5118,5121,5127,5131,5134,5139,5145,5151,5157,5160,5164,5167,5177,5183,5187,5190,5197,5201,5204,5211,5215,5218,5221,5224,5228,5231,5234,5237,5244,5248,5254,5257,5268,5274,5278,5284,5287,5290,5293,5310,5316,5321,5327,5331,5334,5337,5344,5347,5349,5354,5357,5362,5365,5370,5373,5378,5381,5386],[14,4917,4918],{},[17,4919,4920],{},"Your agent is burning tokens while you sleep. Here's how to stop the bleeding and take back control of your AI spend.",[14,4922,4923],{},"Last Tuesday, I woke up to a Slack notification from a user that made my stomach drop.",[14,4925,4926],{},[24,4927,4928],{},"\"Hey, is it normal to spend $22 per day on API costs? I'm using Haiku 4.5 and all I'm doing is setting up a mission control and second brain.\"",[14,4930,4931],{},"Twenty-two dollars a day. On Haiku. The cheapest model in the Anthropic lineup.",[14,4933,4934,4935,4938],{},"That's $660 a month for an agent that's supposed to save you time, not drain your bank account. And this person isn't an edge case. They shared their OpenClaw usage dashboard on Reddit, and the numbers told a painful story: 670 messages, 505 tool calls, 80.6K average tokens per message, and an error rate that suggested something was deeply wrong with their setup. If you're still in the ",[222,4936,4937],{"href":3572},"setup phase",", getting the model routing right from the start prevents most of these cost blowouts.",[14,4940,4941],{},[80,4942],{"alt":4943,"src":4944},"Reddit post from r/openclaw showing a user spending $22 per day on Haiku API costs with OpenClaw usage dashboard","/img/blog/openclaw-reddit-api-costs.jpg",[14,4946,4947],{},[24,4948,4949],{},"Real Reddit post from r/openclaw. This is more common than you think.",[14,4951,4952],{},"But that's not even the worst case we've seen.",[14,4954,4955,4956,4959],{},"Another developer posted their multi-agent workflow results. They'd burned through ",[17,4957,4958],{},"400 million tokens with zero tangible output",". The agents were looping, re-analyzing the same steps, stalling mid-workflow, and hemorrhaging context like a broken pipe.",[14,4961,4962],{},[80,4963],{"alt":4964,"src":4965},"Developer dashboard showing 400 million tokens consumed by OpenClaw multi-agent workflow with zero tangible output","/img/blog/openclaw-400m-tokens-wasted.jpg",[14,4967,4968],{},[24,4969,4970],{},"400 million tokens consumed. No output. This is the nightmare scenario nobody warns you about.",[14,4972,4973],{},"These aren't isolated incidents. A GitHub discussion thread titled \"Burning through tokens\" has developers sharing war stories of $10+ days on moderate usage, $50 heartbeat bills, and one memorable case of a $3,600 monthly API bill.",[14,4975,4976],{},"If you're running OpenClaw and your costs feel out of control, you're not alone. And you're probably making at least two of the five mistakes I'm about to break down.",[35,4978,4980],{"id":4979},"the-136k-problem-nobody-talks-about","The 136K Problem Nobody Talks About",[14,4982,4983],{},[80,4984],{"alt":4985,"src":4986},"Diagram showing OpenClaw's 136K token system prompt overhead sent with every API call, breaking down tool schemas, agent config, and memory context","/img/blog/openclaw-136k-token-overhead.jpg",[14,4988,4989,4990,4993],{},"Here's something that shocked me when I first dug into ",[222,4991,4992],{"href":3212},"how OpenClaw works"," under the hood.",[14,4995,4996,4997,5000],{},"Every single API call your agent makes carries a base system prompt of roughly ",[17,4998,4999],{},"136,000 tokens",". That's not your personality files. That's not your custom instructions. That's OpenClaw's internal framework overhead: tool schemas, agent configuration, memory context, and system-level instructions.",[14,5002,5003],{},"One hundred and thirty-six thousand tokens. Sent with every request.",[14,5005,5006],{},"On Claude Haiku 4.5, that's about $0.0136 just for the system prompt alone. Sounds small? Multiply it by 500 tool calls in a day. That's $6.80 per day in pure overhead before your agent does a single useful thing.",[54,5008,5009],{},[14,5010,5011],{},"The biggest line item on your OpenClaw API bill isn't the work your agent does. It's the context it carries while doing it.",[14,5013,5014],{},"And here's what makes it worse: Anthropic's prompt caching only helps if your requests hit the cache window, which has a 5-minute TTL. If your agent goes idle for six minutes between tasks, the next request is a cold start. Full price. Every token.",[14,5016,5017],{},"That Reddit user spending $22/day? Their dashboard showed an 86.5% cache hit rate, which sounds great until you realize the remaining 13.5% of cold starts were eating them alive at 80,600 tokens per message.",[35,5019,5021],{"id":5020},"the-five-ways-your-openclaw-agent-bleeds-money","The Five Ways Your OpenClaw Agent Bleeds Money",[14,5023,5024],{},"I've spent months watching users rack up unnecessary API costs. The patterns are remarkably consistent.",[666,5026,5028],{"id":5027},"_1-the-wrong-model-for-every-job-trap","1. The \"Wrong Model for Every Job\" Trap",[14,5030,5031],{},"This is the most common and most expensive mistake.",[14,5033,5034],{},"Your agent is using Claude Opus 4.6 to check the weather. It's using Sonnet 4.5 to read a file name. It's deploying a $15-per-million-token model for tasks that a $0.25-per-million-token model handles perfectly.",[14,5036,5037,5038,5041],{},"The cost difference is staggering. Running GPT-4o-mini at 3,000 messages per month costs about $3. Running Claude Opus 4.6 at the same volume? ",[17,5039,5040],{},"$420",". That's a 140x difference for many tasks where the output quality is indistinguishable.",[14,5043,5044],{},"Most OpenClaw users set one model as their default and forget about it. That single decision can be the difference between a $15 month and a $150 month.",[666,5046,5048],{"id":5047},"_2-the-heartbeat-money-pit","2. The Heartbeat Money Pit",[14,5050,5051],{},"OpenClaw's heartbeat feature is brilliant in concept: your agent proactively wakes up, checks for tasks, and takes action without being prompted.",[14,5053,5054],{},"In practice, it's a cost bomb.",[14,5056,5057,5058,122],{},"Every heartbeat trigger is a full API call. It carries the entire session context. If you've configured it to run every 5 minutes, that's 288 API calls per day of pure overhead. One developer on GitHub reported their heartbeat alone was costing ",[17,5059,5060],{},"$50 per day",[14,5062,5063],{},"Here's what makes it insidious: the heartbeat runs whether or not there's anything to do. Your agent wakes up at 3 AM, sends 136K tokens to check if there are new emails, finds nothing, and goes back to sleep. Then does it again five minutes later.",[666,5065,5067],{"id":5066},"_3-context-bloat-the-silent-killer","3. Context Bloat (The Silent Killer)",[14,5069,5070],{},"Every message in your conversation history gets sent with every new API call. Every. Single. One.",[14,5072,5073],{},"Start a fresh session and your first message might cost $0.02. By message 50, you're carrying so much context that each request costs $0.15+. By message 200, you're pushing the context window limits and your agent starts forgetting things anyway.",[14,5075,5076,5077,122],{},"That second Reddit user who burned 400 million tokens? Their agents were stuck in loops, re-analyzing the same steps because the context had grown so large that the model was losing track of what it had already done. The irony is brutal: the more context you carry, ",[17,5078,5079],{},"the worse your agent performs and the more you pay",[666,5081,5083],{"id":5082},"_4-unmonitored-automations","4. Unmonitored Automations",[14,5085,5086],{},"This is where OpenClaw costs go from \"annoying\" to \"terrifying.\"",[14,5088,5089],{},"A workflow that triggers 10 times per day during testing might trigger 500 times per day once connected to live inputs. Browser automation sessions are especially expensive because every navigation step requires a model decision. And if an automated task gets stuck in a loop? One user reported burning $200 in a single day because a task was retrying infinitely.",[14,5091,5092],{},"Without spending limits and monitoring, an OpenClaw agent is a credit card with no maximum and no alerts.",[666,5094,5096],{"id":5095},"_5-skills-stuffed-into-personality-files","5. Skills Stuffed into Personality Files",[14,5098,5099],{},"This is a sneaky one.",[14,5101,5102,5103,5106],{},"Many users put detailed instructions, templates, and workflow guides directly into their personality markdown files (SOUL.md, IDENTITY.md, USER.md). The problem? ",[17,5104,5105],{},"Those files are loaded with every single API call",". Every instruction you add increases your per-message cost across the board.",[14,5108,5109,5110,5113],{},"A community member on the OpenClaw GitHub shared a smarter approach: move instructions into ",[222,5111,5112],{"href":3006},"skills"," instead. Skills are only loaded when relevant, not with every request. This alone can cut your per-message token overhead significantly.",[35,5115,5117],{"id":5116},"how-to-actually-fix-your-openclaw-api-costs","How to Actually Fix Your OpenClaw API Costs",[14,5119,5120],{},"Enough about the problems. Let's talk solutions.",[14,5122,5123],{},[80,5124],{"alt":5125,"src":5126},"OpenClaw cost optimization playbook showing three-tier model routing from Haiku to Sonnet to Opus based on task complexity","/img/blog/openclaw-model-routing-tiers.jpg",[666,5128,5130],{"id":5129},"set-up-model-routing-this-alone-saves-50-70","Set Up Model Routing (This Alone Saves 50-70%)",[14,5132,5133],{},"The single highest-impact change you can make is configuring a model failover chain that matches capability to task complexity.",[14,5135,5136],{},[17,5137,5138],{},"The playbook:",[14,5140,5141,5144],{},[17,5142,5143],{},"Tier 1 (routine tasks):"," Use Haiku 4.5 or GPT-4o-mini for simple queries, file operations, and basic tool calls. Cost: fractions of a cent per message.",[14,5146,5147,5150],{},[17,5148,5149],{},"Tier 2 (moderate complexity):"," Route to Sonnet 4.5 or GPT-4o for tasks requiring nuanced understanding. Cost: a few cents per message.",[14,5152,5153,5156],{},[17,5154,5155],{},"Tier 3 (complex reasoning):"," Reserve Opus 4.6 or GPT-5.2 for genuinely difficult problems, debugging, and multi-step analysis. Use sparingly.",[14,5158,5159],{},"Most agent tasks live in Tier 1. Responding to simple queries, performing file operations, executing basic tool calls: Haiku handles these perfectly. You save Opus for when you actually need it.",[666,5161,5163],{"id":5162},"tame-the-heartbeat","Tame the Heartbeat",[14,5165,5166],{},"Two options here:",[14,5168,5169,5172,5173,5176],{},[17,5170,5171],{},"Option A:"," Increase your heartbeat interval to 30 minutes or 1 hour. For most personal assistant ",[222,5174,5175],{"href":3382},"use cases",", checking for new tasks every 5 minutes is overkill.",[14,5178,5179,5182],{},[17,5180,5181],{},"Option B:"," Configure a local heartbeat check that runs without making API calls. Check system memory and task queues locally, and only trigger an API call when there's actually something to do. This approach was highlighted by a developer who cut their monthly costs from $90 to $6 by implementing local heartbeat logic.",[666,5184,5186],{"id":5185},"reset-sessions-aggressively","Reset Sessions Aggressively",[14,5188,5189],{},"After completing each independent task, reset the session context. Don't let a morning email summary inflate the context for an afternoon calendar check.",[14,5191,5192,5193,5196],{},"Use the ",[49,5194,5195],{},"/compact"," command to compress session history. Delete old session files. Treat context like RAM: the less you carry, the faster and cheaper everything runs.",[666,5198,5200],{"id":5199},"monitor-everything-or-dont-bother","Monitor Everything (Or Don't Bother)",[14,5202,5203],{},"Set hard spending limits on your API keys. Enable alerts at 50%, 75%, and 90% thresholds. Use separate API keys per workflow so you can track exactly where costs originate.",[14,5205,5206,5207,5210],{},"The OpenClaw ",[49,5208,5209],{},"/usage full"," command shows per-request token consumption. Use it. The dashboard shown in that first Reddit screenshot? That user had the data to diagnose their problem. The issue was that they didn't know what the numbers meant.",[666,5212,5214],{"id":5213},"the-chatgpt-oauth-trick-flat-rate-conversations","The ChatGPT OAuth trick (flat-rate conversations)",[14,5216,5217],{},"If you have a ChatGPT Plus subscription ($20/month), you can connect OpenClaw to your ChatGPT account using OAuth. This routes your agent's requests through your ChatGPT subscription instead of the API, meaning you pay the flat subscription fee instead of per-token pricing.",[14,5219,5220],{},"The catch: ChatGPT has usage limits on the Plus plan. You'll hit rate limits during heavy agent usage. It's not suitable for high-frequency cron jobs or tasks that need consistent throughput. But for direct interactions and moderate daily usage, it effectively gives you GPT-4o access for a flat $20/month instead of variable per-token billing.",[14,5222,5223],{},"The ChatGPT OAuth approach works best as a supplement, not a replacement. Use it for your direct conversations with the agent. Keep Haiku or DeepSeek for automated operations. This hybrid approach caps your conversational costs at a flat rate while keeping background operations cheap.",[666,5225,5227],{"id":5226},"the-gemini-flash-hack-almost-free","The Gemini Flash hack (almost free)",[14,5229,5230],{},"Google Gemini 2.5 Flash offers a free tier through Google AI Studio: 1,500 requests per day, 1 million token context window, no credit card required. For personal OpenClaw use (morning briefings, basic calendar management, simple automations), the free tier is often enough.",[14,5232,5233],{},"Even the paid tier at $0.075 per million input tokens is essentially free at agent scale. A full month of moderate usage runs $1-3 total.",[14,5235,5236],{},"The tradeoff: Gemini's tool calling isn't as reliable as Claude for complex chains. It works well for straightforward operations but stumbles on multi-step reasoning that needs precise instruction following. Best used for heartbeats, simple lookups, and as a fallback model.",[14,5238,5239,5240,5243],{},"For a deeper look at all the budget-friendly providers that work with OpenClaw, our guide to the ",[222,5241,5242],{"href":3511},"cheapest OpenClaw AI providers"," covers five alternatives with real pricing data.",[35,5245,5247],{"id":5246},"the-deeper-question-should-you-be-managing-this-at-all","The Deeper Question: Should You Be Managing This at All?",[14,5249,5250,5251,122],{},"Here's what nobody tells you about ",[222,5252,5253],{"href":2826},"OpenClaw's security and cost risks",[14,5255,5256],{},"Every hour you spend optimizing token routing, debugging heartbeat configs, monitoring spending dashboards, and resetting bloated sessions is an hour you're not spending on the thing your agent was supposed to help with in the first place.",[14,5258,5259,5260,5263,5264,5267],{},"The OpenClaw maintainer Shadow put it bluntly: ",[24,5261,5262],{},"\"if you can't understand how to run a command line, this is far too dangerous of a project for you to use safely.\""," That warning extends to cost management too. If you're not comfortable diving into token economics and model routing configurations, ",[17,5265,5266],{},"you will overspend",". It's not a question of if, but how much.",[14,5269,5270,5271,5273],{},"We built ",[222,5272,3421],{"href":675}," because we got tired of watching smart people burn money on infrastructure problems instead of building actual agent workflows. At $49/month for Pro, you get automatic session management, built-in usage monitoring, and anomaly detection that auto-pauses your agent when costs spike unexpectedly. No heartbeat misconfiguration nightmares. No 136K token overhead bloat. The infrastructure is handled so you can focus on what your agent actually does.",[35,5275,5277],{"id":5276},"the-real-cost-isnt-the-api-bill","The Real Cost Isn't the API Bill",[14,5279,5280],{},[80,5281],{"alt":5282,"src":5283},"Cost comparison breakdown showing self-hosted OpenClaw total cost including time, VPS, API bills, and surprise charges versus BetterClaw managed deployment","/img/blog/openclaw-true-cost-comparison.jpg",[14,5285,5286],{},"Let me share a quick calculation that changed how I think about this.",[14,5288,5289],{},"Say you spend 5 hours per month configuring, monitoring, and troubleshooting your self-hosted OpenClaw setup. If your time is worth $50/hour (conservative for a developer or founder), that's $250/month in opportunity cost.",[14,5291,5292],{},"Add $30/month in API costs. Plus $6/month for a VPS. Plus the $200 surprise bill when an automation loops at 2 AM and you don't catch it until morning.",[14,5294,5295,5296,5299,5300,5304,5305,5309],{},"Compare that to a ",[222,5297,5298],{"href":2942},"managed deployment"," where all of this is handled for you. Or explore ",[222,5301,5303],{"href":5302},"/openclaw-hosting","BetterClaw's managed OpenClaw hosting"," with built-in cost monitoring and auto-pause safety. See how ",[222,5306,5308],{"href":5307},"/compare/xcloud","BetterClaw compares to xCloud"," for managed hosting.",[14,5311,5312,5313,122],{},"The math doesn't lie. But more importantly, the experience doesn't lie. Every minute you spend in a YAML file or debugging Docker is a minute you're not iterating on your agent's actual capabilities - the ",[222,5314,5315],{"href":3382},"use cases that make OpenClaw genuinely transformative",[54,5317,5318],{},[14,5319,5320],{},"The cheapest token is the one your infrastructure never wastes.",[14,5322,5323,5324,5326],{},"If any of this hit close to home - if you've stared at an API bill and felt that sinking feeling - ",[222,5325,4337],{"href":398},". It's $49/month for Pro, bring your own API keys, and your first deploy takes about 60 seconds. We handle the infrastructure headaches. You handle the interesting part.",[35,5328,5330],{"id":5329},"whats-coming-next","What's Coming Next",[14,5332,5333],{},"The OpenClaw ecosystem is evolving fast. With 230K+ GitHub stars, 1.27 million weekly npm downloads, and the project moving to an open-source foundation, the tooling around cost management will improve.",[14,5335,5336],{},"But today, right now, the gap between \"free open-source software\" and \"affordable to actually run\" is massive. The users posting on Reddit about $22/day costs aren't doing anything wrong. The framework just isn't optimized for cost efficiency out of the box.",[14,5338,5339,5340,5343],{},"Whether you self-host with careful optimization or ",[222,5341,5342],{"href":4262},"choose a managed alternative",", the key insight is the same: treat your AI agent's API costs like a production expense, not an afterthought.",[14,5345,5346],{},"Your agent should be saving you money. Not the other way around.",[35,5348,403],{"id":402},[14,5350,5351],{},[17,5352,5353],{},"What are typical OpenClaw API costs per month?",[14,5355,5356],{},"Most users spend between $5 and $30 per month on API costs for moderate usage (around 50 messages per day). However, costs can skyrocket to $100-600+ per month with premium models, misconfigured heartbeats, or unmonitored automations. The model you choose matters more than anything else: Haiku 4.5 costs roughly 25x less than Opus 4.6 for the same number of messages.",[14,5358,5359],{},[17,5360,5361],{},"How does BetterClaw compare to self-hosted OpenClaw for cost management?",[14,5363,5364],{},"Self-hosted OpenClaw gives you full control but requires manual configuration of model routing, session management, heartbeat intervals, and spending limits. BetterClaw handles all infrastructure and monitoring for $49/month for Pro (BYOK), including anomaly detection that auto-pauses agents on cost spikes. For users spending 5+ hours monthly on infrastructure management, the managed approach typically costs less when you factor in time.",[14,5366,5367],{},[17,5368,5369],{},"How do I reduce OpenClaw token usage quickly?",[14,5371,5372],{},"The three fastest wins are: configure model routing so cheap models handle simple tasks (saves 50-70%), increase your heartbeat interval from 5 minutes to 30+ minutes (saves $30-90/month for heavy users), and reset session context after each independent task to prevent context bloat. Moving instructions from personality files into skills also reduces per-message overhead significantly.",[14,5374,5375],{},[17,5376,5377],{},"Is $49/month for BetterClaw Pro worth it compared to a $5 VPS?",[14,5379,5380],{},"The VPS is only one piece of the puzzle. A $5 VPS still requires you to manage Docker, security, updates, SSL, monitoring, and cost optimization yourself. Users report spending 5-10 hours per month on maintenance. BetterClaw includes Docker-sandboxed execution, AES-256 encryption, auto-updates, health monitoring, and multi-channel support. The real comparison is $49/month fully managed for 5 agents versus $5/month plus your time and the risk of surprise API bills from unmonitored agents. If you only need one agent and want to test the difference first, the free plan (1 agent, 500 credits/month, BYOK) costs nothing.",[14,5382,5383],{},[17,5384,5385],{},"Is OpenClaw safe to run if I'm worried about runaway API costs?",[14,5387,5388],{},"Without proper safeguards, no. CrowdStrike published a full security advisory on OpenClaw enterprise risks, 30,000+ instances were found exposed without authentication, and 824+ malicious skills were discovered on ClawHub. On the cost side, agents can loop infinitely, heartbeats can drain hundreds of dollars silently, and there's no built-in spending cap in the default configuration. If you self-host, set hard API key limits and monitor daily. Or choose a managed provider with built-in anomaly detection and auto-pause.",{"title":239,"searchDepth":438,"depth":438,"links":5390},[5391,5392,5399,5407,5408,5409,5410],{"id":4979,"depth":438,"text":4980},{"id":5020,"depth":438,"text":5021,"children":5393},[5394,5395,5396,5397,5398],{"id":5027,"depth":722,"text":5028},{"id":5047,"depth":722,"text":5048},{"id":5066,"depth":722,"text":5067},{"id":5082,"depth":722,"text":5083},{"id":5095,"depth":722,"text":5096},{"id":5116,"depth":438,"text":5117,"children":5400},[5401,5402,5403,5404,5405,5406],{"id":5129,"depth":722,"text":5130},{"id":5162,"depth":722,"text":5163},{"id":5185,"depth":722,"text":5186},{"id":5199,"depth":722,"text":5200},{"id":5213,"depth":722,"text":5214},{"id":5226,"depth":722,"text":5227},{"id":5246,"depth":438,"text":5247},{"id":5276,"depth":438,"text":5277},{"id":5329,"depth":438,"text":5330},{"id":402,"depth":438,"text":403},"2026-02-27","Spending $20+/day on OpenClaw API costs? Learn the 5 hidden cost traps and proven fixes to cut your AI agent spending by 50-90%.","/img/blog/openclaw-api-costs.jpg",{},"14 min read",{"title":4912,"description":5412},"OpenClaw API Costs Explained: 5 Hidden Traps + Fixes","blog/openclaw-api-costs",[5420,5421,5422,5423,5424,5425,5426,5427],"openclaw api costs","openclaw token usage","reduce openclaw costs","openclaw spending","ai agent api costs","openclaw cost optimization","openclaw pricing","openclaw haiku costs","NeYLuZTl_t1Z5cpV-1m9xlNyDGDH_KGU4lRgbogpo3w",1788958433936]