Configuration Reference

Anyy reads profile configuration from config.yaml in the active Anyy home unless a command accepts and receives --config PATH. The parser uses known YAML fields, so misspelled top-level fields fail instead of being silently ignored.

For an annotated starting point, see configs/config.example.yaml.

Recommended Path

Use setup commands for first-time config instead of hand-writing YAML:

anyy setup
anyy setup model
anyy setup channels telegram --write-config

Use anyy config to render the resolved summary, and use doctor to validate local files:

anyy config --home ~/.anyy
anyy doctor --home ~/.anyy
anyy doctor --config ./candidate-config.yaml

There is no anyy config set or anyy config edit subcommand in this build. Edit config.yaml with your normal editor when setup does not cover the field you need.

Config File

The top-level shape is:

home: /root/.anyy
profile: default
timezone: ""
default_model: openai-compatible/your-model-name
main_model:
  provider_id: openai-compatible
  model: your-model-name
auxiliary_models: {}
agent:
  max_turns: 90
providers: []
gateway: {}
channels: {}
toolsets: {}
computer_use: {}
tool_governance: {}
skills: {}
cron: {}
heartbeat: {}
memory: {}
mcp: {}
media_understanding: {}
media_generation: {}
tts: {}
voice: {}
channel_webhooks: {}
storage: {}
retention: {}
observability: {}

Important defaults:

Field	Default
`profile`	`default`
`agent.max_turns`	`90`
`gateway.unix_socket`	`<home>/anyy.sock`
`gateway.tcp.enabled`	`true` when omitted
`gateway.tcp.listen`	`0.0.0.0:8765`
`gateway.tcp.mode`	`open`
`memory.maintenance_enabled`	`true`
`memory.suggestion_ttl_days`	`14`
`memory.daily_keep_days`	`180`
`memory.daily_mode`	`delete`
`memory.auto_dream_enabled`	`true`
`memory.auto_dream_min_hours`	`168`
`memory.auto_dream_min_user_turns`	`50`
`memory.auto_dream_scan_interval`	`8h`
`mcp.client.session_idle_ttl_ms`	`300000`
`channel_webhooks.enabled`	`false`
`channel_webhooks.listen`	`127.0.0.1:8770`
`storage.hot_window_hours`	`72`
`storage.preview_bytes`	`1024`
`storage.raw_ttl_days`	`30`

warning

gateway.tcp.enabled defaults to true, with listen address 0.0.0.0:8765 and mode open when omitted. Review the effective gateway listener before exposing a host beyond your trusted local network.

Profiles

Profiles are selected before loading config. The config's profile field is the profile name stored inside that home; the CLI selection decides which home is loaded.

Selection precedence is:

Command --home PATH when supported.
Global --profile NAME.
ANYY_HOME.
Active profile under the profile root.
The default profile home.

Use:

anyy profile list
anyy profile create work --display-name "Work"
anyy --profile work status

Providers

Providers are configured under providers. Each provider needs an id, an API mode either directly or through a recognized provider profile, a base URL either directly or through that profile, and credentials compatible with its auth mode. The single provider entry is Provider Integrations; the compact field table is Provider Config Reference.

providers:
  - id: openai-compatible
    api_mode: openai-compatible
    base_url: https://api.openai.com/v1
    api_key_ref: env:OPENAI_API_KEY
    default_model: your-model-name

Supported API modes are openai-compatible, anthropic-messages, google-gemini, openai-responses, and codex-responses. Supported auth modes are api_key, oauth, none, external_process, and aws_sdk.

auth_mode: none is accepted only for local provider URLs.

General secret references use these schemes:

Ref	Use
`secret:path/name`	Durable profile-local service credentials.
`env:NAME`	Credentials injected by a shell or service manager.
`file:/absolute/path`	Credentials stored outside the profile home.
`literal:value`	Local testing or non-secret values only.

Provider credential fields reject literal:. Use credential_ref or api_key_ref with env:, file:, or secret: instead.

Models

The canonical model selection is:

main_model:
  provider_id: openai-compatible
  model: your-model-name

default_model: provider/model remains a compatibility alias and must include a known provider id. Auxiliary model slots are grouped under auxiliary_models:

auxiliary_models:
  fallback:
    - provider_id: openai-compatible
      model: fallback-model
      allow_reasoning_drop: true
  image_understanding:
    - provider_id: vision-compatible
      model: vision-model

Model and provider capability flags are exact overrides. Omit a capability key to keep the provider profile default; set true or false to override it. Use Configuring Models for model routing and fallback behavior, and Provider Config Reference for the complete field list.

Tool Governance

toolsets controls which groups are visible by default, while tool_governance.overrides can override individual tool risk and execution policy. See Toolsets Reference for selection order, default-visible toolsets, optional toolsets, and MCP toolset names.

toolsets:
  default:
    - web
    - sessions
    - memory
    - tasks
    - automation
    - clarify
    - file
    - messaging
    - skills
    - subagents
    - terminal
    - tts

computer_use is intentionally not default-visible in the example config.

Skills

Skills are configured under the open skills map. Anyy currently reads these keys:

skills:
  external_roots:
    - ~/.agents/skills
    - ${TEAM_SKILLS_ROOT}
  disabled:
    - skill_user_abc123
  disabled_by_surface:
    tui:
      - experimental-skill
    api:
      - /internal-command

Field	Type	Default	Meaning
`external_roots`	list of strings, comma string, or string list-compatible value	empty	Additional skill roots scanned after `<home>/skills` and before system skills. `~`, `$VAR`, and `${VAR}` are expanded. Roots with missing environment variables are skipped.
`disabled`	list of strings or comma string	empty	Globally hide matching skills. Each entry can be a skill ID, skill name, or command name.
`disabled_by_surface`	map of surface name to list/string	empty	Hide matching skills only for a surface such as `tui`, `cli`, `api`, `channel`, `weixin`, or `cron`.

<home>/skills remains the managed root for CLI installs and agent-managed skill writes. External roots and system skills are scanned into the catalog but are not the target of anyy skills install, anyy skills uninstall, or agent create/edit/patch writes.

See Skills System and Skill Management.

Channels

Channels are configured under channels.<name>. Every block uses enabled and usually account_id; channel-specific fields and secret refs are listed in Channels Reference.

channels:
  telegram:
    enabled: true
    account_id: personal
    token_ref: secret:telegram/personal/token
    dm_policy: pairing
    group_policy: mention

channel_webhooks is separate. It controls the shared webhook listener for adapters that support verified webhook routes:

channel_webhooks:
  enabled: false
  listen: 127.0.0.1:8770

MCP

MCP has a client side and a server side:

mcp:
  client:
    enabled: false
    session_idle_ttl_ms: 300000
    servers: {}
  server:
    enabled: false
    transport: stdio

When MCP server policy fields are omitted, runtime defaults are tools.default_risk: read, tools.approval_policy: none, and tools.execution_policy: direct. The anyy mcp add path writes a more conservative external-server policy: tools.default_risk: runtime-high and tools.execution_policy: confirm.

Use anyy mcp add and anyy mcp configure rather than hand-writing server blocks where possible. See MCP Integration for the workflow, and MCP Config Reference for all client/server fields, transport rules, secret-ref validation, and policy values.

Voice And Media

media_understanding controls inbound image, audio, and video understanding. media_generation controls output image generation. tts configures speech synthesis providers; voice.auto_tts controls whether voice/audio conversations reply with speech by default.

media_generation:
  image:
    enabled: true
    default_aspect_ratio: square
    timeout_ms: 120000
    max_bytes: 5242880
tts:
  provider: openai
  timeout_ms: 60000
voice:
  auto_tts: false

Configuring a TTS provider does not automatically turn every response into audio; voice reply behavior is controlled separately.

Dashboard

The dashboard is usually started with CLI flags, not static config:

anyy dashboard [--home PATH] [--socket PATH] [--listen ADDR] [--no-open]
anyy dashboard lan [--home PATH] [--socket PATH]

LAN mode is explicit because it exposes a dashboard URL to other trusted devices on the same network.

Recommended Path​

Config File​

Profiles​

Providers​

Models​

Tool Governance​

Skills​

Channels​

MCP​

Voice And Media​

Dashboard​