10. Configuration Reference

This is a CLI-centric index to every config file the CLI reads. The schema reference for each file lives in docs/reference/configuration.md — every row below links to the right section there.

All config surfaces at a glance

File	Project path	User-global path	Used by	Schema reference
LLM credentials	.env (cwd)	shell env	/model, /provider, /temperature	§2
Runtime settings	.agentao/settings.json	—	/mode (persist), /replay on/off	§3
Permission rules	— (project file ignored)	~/.agentao/permissions.json	/mode, /permission, tool confirmation UI	§4
Shell sandbox	.agentao/sandbox.json	~/.agentao/sandbox.json	/sandbox	Part 6.2
MCP servers	.agentao/mcp.json	~/.agentao/mcp.json	/mcp	§5
ACP servers	.agentao/acp.json	—	/acp	§6
Skill enable/disable	.agentao/skills_config.json	—	/skills enable, /skills disable	§7
Project instructions	AGENTAO.md (cwd)	—	system prompt every turn	§8
Memory store	.agentao/memory.db	~/.agentao/memory.db	/memory, save_memory tool	§9

"Where do I change X?" cheat-sheet

What you want to change	Edit
Default model / API key	.env (OPENAI_API_KEY, OPENAI_MODEL, OPENAI_BASE_URL)
Add a second provider	.env (GEMINI_API_KEY etc. — see chapter 2)
Default temperature	.env (LLM_TEMPERATURE)
Default permission mode for fresh sessions	.agentao/settings.json → mode (persisted-last-known, see §3)
Allow / deny extra shell commands	~/.agentao/permissions.json
Allow / deny extra web domains	~/.agentao/permissions.json
Default sandbox profile (macOS)	.agentao/sandbox.json or ~/.agentao/sandbox.json → default_profile
Default context window	AGENTAO_CONTEXT_TOKENS environment variable
Default replay recording state	.agentao/settings.json → replay.enabled
Replay max instances	.agentao/settings.json → replay.max_instances
Add MCP servers	.agentao/mcp.json (or /mcp add — same file)
Add ACP servers	.agentao/acp.json
Disable a buggy skill globally	.agentao/skills_config.json (or /skills disable <name> — same file)
Project-specific behavior the agent should always follow	AGENTAO.md (or copy from examples/personas/)

Runtime overrides vs. config files

A few things you set with slash commands are session-only and don't write to disk:

Slash command	Persisted?	Where if persisted
/model <name>	No	— (use OPENAI_MODEL in .env for default)
/provider <name>	No	— (set provider env triple)
/temperature <n>	No	.env (LLM_TEMPERATURE)
/mode <mode>	No	.agentao/settings.json (last-known)
/context limit <n>	No	— (current process only; restart reads AGENTAO_CONTEXT_TOKENS)
/sandbox profile <name>	No	— (edit sandbox.json to persist)
/replay on / /replay off	Yes	.agentao/settings.json (replay.enabled)
/skills disable <name> / /skills enable <name>	Yes	.agentao/skills_config.json
/skills activate / /skills deactivate	No	—
/mcp add / /mcp remove	Yes	.agentao/mcp.json (project)
/memory delete / /memory clear	Yes	memory.db (soft-delete)

Most "feels temporary" commands are temporary by design. If you want a setting to outlive the session, edit the file.

Precedence summary

Three things to know:

1. Permissions are user-only. A project-level permissions.json would let any cloned repo override your security policy, so the loader ignores it (with a warning). Edit ~/.agentao/permissions.json for personal rules.
2. MCP merges, but project is add-only. A project entry can declare a new server name, but cannot redefine a user-defined github to point at a different transport. Same-name collisions are skipped with a warning.
3. Memory is independent per scope. Project DB and user DB are both injected into the prompt; project doesn't override user. Use /memory user and /memory project to inspect each.

For the full precedence rules see docs/reference/configuration.md §1.

AGENTAO.md persona gallery

If you don't want to write an AGENTAO.md from scratch, the repo ships a small persona gallery under examples/personas/. Each persona is a single AGENTAO.md you copy into your project root.

Persona	Vibe	Use when
daily-driver/	Evidence-first, privacy-conscious, workspace-organized	Day-to-day research / coding assistant
kawaii-buddy/	Cute, bilingual chatter, asks how you feel	Emotional-value pocket helper

# Pick one and drop into the project you launch agentao from
cp examples/personas/daily-driver/AGENTAO.md /path/to/your/project/AGENTAO.md

AGENTAO.md is recomposed into the system prompt every turn — edits apply on the next message, no restart needed. Treat the gallery as starting points, not contracts; rewrite freely.

Internal state files

Files that exist under .agentao/ but you should not hand-edit:

Path	Purpose
.agentao/background_tasks.json	Sub-agent state; in-memory mirror exists
.agentao/replay/*.jsonl	Replay recordings
.agentao/sessions/	Per-session artifacts
.agentao/plan.md, .agentao/plan-history/	Plan-mode state
.agentao/tool-outputs/	Cached tool outputs

Editing them while the CLI is running can desync state. Stop the CLI first if you must.

Verify your config

Two non-interactive commands inspect the files in the tables above without starting an agent:

agentao config validate      # config files only (.env, settings, permissions, mcp, replay, memory)
agentao config validate --json

agentao doctor               # adds plugin diagnostics, ACP schema, optional-dep probes
agentao doctor --json

Use them in CI, in a make check target, or right after editing one of the files in the table above. Errors (malformed JSON, non-object MCP entries, unparseable LLM_TEMPERATURE, etc.) exit 1; warnings (missing API key on a fresh clone, user/project MCP collisions) keep exit 0 so CI doesn't trip on benign states. Full surface is documented in chapter 12.

Where to go next

Want to…	Read
Full schema reference for any of the files above	docs/reference/configuration.md
Validate your config files from CI	12. Non-Interactive Entry Points → agentao config validate
Change default permission rules with intent	Part 5.4 · Permissions
Author an AGENTAO.md for your project	Part 5.6 · System Prompt Customization

---

Where this fits

The same files are loaded identically when embedding. .env becomes constructor kwargs (or you can pass them directly), permissions.json is consumed by the same PermissionEngine, mcp.json / acp.json by the same managers. The split between "host configures programmatically" and "user edits files" is up to your application.

Authoritative reference

Schemas: docs/reference/configuration.md (English) · docs/reference/configuration.zh.md (Chinese). Loaders: see the linked sections above. The schema file is the single source of truth for field names and defaults — this index just tells you which row to look at.