跳到主要内容

配置

Anyy 读取一个 YAML 配置文件，并将其叠加在内置默认值之上。本页说明配置 模型：设置存放在哪里、配置文件如何被定位，以及各项取值的解析顺序。

本页不罗列每一个配置键。完整的逐项表格请参见 配置参考与 环境变量参考。若要交互式地创建或修改 配置，请使用安装向导。关于服务商与模型相关字段， 请参见配置模型和 Provider 配置参考。

目录结构​

一个安装实例的全部状态都位于单一的 home 目录下 —— 普通用户安装为 ~/.anyy，以 root 运行时为 /root/.anyy。配置文件始终是 home 目录 根部的 config.yaml：

<home>/
  config.yaml      # 配置文件（本页主题）
  secrets/         # 解析后的密钥材料（env:/file:/secret: 后端）
  memory/          # MEMORY.md、USER.md 及记忆状态
  state.db         # 会话、消息、审批、任务、审计与运行时状态
  raw/             # 供检查/恢复使用的逐会话 JSONL 镜像
  skills/          # 已安装的技能
  anyy.sock   # gateway Unix 套接字
  logs/  cache/  workspace/  backups/  channels/  ...

home 目录按以下顺序解析：

  1. 命令行传入的 --home PATH 标志。
  2. 环境变量 ANYY_HOME。
  3. 默认值 —— 普通用户安装为 ~/.anyy，以 root 运行时为 /root/.anyy（当没有以其他方式解析出 home 时，/root/.anyy 是内置的回退值）。

运行 anyy config 可打印当前 home 解析出的路径与设置。该命令是只读的。

配置文件​

每个 home 只有一个配置文件：config.yaml。它是纯 YAML，是所有非密钥设置的唯一 来源。源码树中附带一个带大量注释的示例文件（configs/config.example.yaml）， 演示了每个配置段。

一个最小可用的文件如下所示：

profile: default
timezone: ""              # IANA 名称（例如 Asia/Shanghai）；留空则使用主机时区

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

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

agent:
  max_turns: 90

该文件按严格模式解析：未知的顶层或嵌套键会被拒绝而非忽略，因此键名写错会产生 加载错误，而不会被悄悄丢弃。

你会遇到的顶层配置段包括 providers、main_model、auxiliary_models、 gateway、channels、toolsets、tool_governance、skills、memory、mcp、 media_understanding、media_generation、tts、voice、storage、 retention 和 observability。每一项都在配置参考 中说明。

通常你不需要手工编辑 config.yaml。安装向导以及 anyy setup model、anyy setup channels、anyy mcp add、 anyy computer-use enable 等子命令会替你写入相应配置段。

配置优先级​

有效设置按从低到高的优先级解析：

  1. 内置默认值。 每个可选设置都会在加载时被赋予默认值。例如：profile 默认为 default，agent.max_turns 默认为 90，gateway TCP 监听默认为 open 模式下的 0.0.0.0:8765，gateway Unix 套接字默认为 <home>/anyy.sock。文件中省略的键会继承其默认值。
  2. 配置文件。 config.yaml 中出现的任何取值都会覆盖相应的默认值。
  3. 用于定位的命令行标志。 --home 选择使用哪个 home（从而决定使用哪个 config.yaml）；--config PATH 让命令指向某个特定的配置文件，而不是 <home>/config.yaml。它们选择的是加载哪个文件，而不会覆盖文件内部的单项 设置。

不存在与本文件合并的独立的按用户或全系统级配置文件：单个 config.yaml 加上 默认值即定义了一个 home 的有效配置。若要运行多套相互独立的配置，请使用不同的 home（参见配置档案）。

注意

由于当前默认值会以 open 模式启用 gateway TCP 监听，如果你只需要本地套接字访问， 请设置 gateway.tcp.enabled: false；若要使用 TCP，请先明确绑定并加上访问控制， 再把网关放到共享网络上。

环境变量替换​

Anyy 不在 config.yaml 内部执行通用的、shell 风格的 ${VAR} 替换。 环境变量以两种特定方式影响配置：

  • home 选择。 当未提供 --home 时，ANYY_HOME 选择 home 目录（从而 决定配置文件），如上文所述。

  • 密钥引用。 敏感取值绝不会直接写入 config.yaml。相反，以 _ref 结尾的 字段（例如 api_key_ref、token_ref、app_secret_ref）保存一个带类型的 引用，在运行时解析。支持的方案有：

    方案解析来源
    env:NAMENAME 环境变量
    file:PATH某个文件的内容
    secret:scope/keyAnyy 在 <home>/secrets 下托管的密钥存储
    literal:value内联的字面量取值

    因此 api_key_ref: env:OPENAI_API_KEY 会在运行时从该环境变量读取密钥；密钥 本身从不出现在文件中。完整的变量列表请参见 环境变量参考。

    并不是每个 _ref 字段都接受每一种 scheme。Provider 和 MCP 的密钥字段会拒绝 literal:，避免 secret 落入 config.yaml。

Provider 与模型设置​

服务商连接与当前模型在 providers、main_model / default_model 以及 auxiliary_models 下配置。它们决定助手与哪个服务通信，以及由哪个模型回复每一 轮对话。由于这是配置中最复杂的部分，它有专门的指南： 配置模型。字段参考见 服务商配置参考。

辅助模型设置​

auxiliary_models 为非主要工作定义模型槽位——fallback、image_understanding、 video_understanding、speech_synthesis、search 和 image_generation。每个 槽位列出一个或多个 { provider_id, model } 条目，并可单独启用或禁用。这让纯文本 的主模型能够把视觉、语音或搜索委托给另一个具备相应能力的模型。相关的 media_understanding 配置段则调节图片、音频和视频如何被概括进一轮对话。配置方法 参见配置模型。

工具治理​

tool_governance 配置段无需改动代码即可调整单个工具的行为。每条覆盖项通过 source 与 name 定位某个工具，并可设置其 risk、approval_policy、 execution_policy、输出预算、超时，以及是否 enabled。这正是你提高或降低某个 特定工具的审批要求、或彻底禁用某个工具的方式。哪些工具集会暴露给某一轮对话，则由 toolsets 配置段单独控制；参见工具集参考。

Skills 设置​

skills 配置段控制 skill catalog 可见性和 external roots：

skills:
  external_roots:
    - ~/.agents/skills
  disabled:
    - skill_user_abc123
  disabled_by_surface:
    tui:
      - noisy-helper

使用 external_roots 配置共享的只读 skill 目录；使用 disabled 或 disabled_by_surface 隐藏某个 skill ID、skill name 或 command name。已安装和 agent-created skills 仍然位于 <home>/skills。参见 Skills 系统和 配置参考。

MCP 配置​

MCP 配置分为 client side 和 server side：client side 让 Anyy 连接外部 MCP server， server side 则让 Anyy 通过 stdio 暴露一个 bridge。

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

常规管理请使用 anyy mcp add、anyy mcp configure、anyy mcp test 和 anyy mcp reload。MCP 工具只有在选中对应 mcp-<server> 工具集时才可见。 字段级细节见 MCP 配置参考。

记忆配置​

memory 配置段控制长期记忆的维护：maintenance_enabled 开关后台维护， suggestion_ttl_days（默认 14）设定记忆建议的存活时长，daily_keep_days （默认 180）与 daily_mode（默认 delete）则决定每日记忆汇总如何保留或清理。 记忆本身存放在 <home>/memory 下。

模型可见的 memory 工具、受信任 suggestion RPC、后台 review 和维护行为细节见 持久化记忆。

上下文配置​

对话上下文的组装与压缩由运行时管理。压缩通过概括较早的对话轮、同时保护最近和最早 的消息，使长会话保持在模型的上下文窗口之内。当前的有效默认值（可通过 anyy config 查看）为：启用、在窗口的 50% 处开始压缩、目标约 20%、保护最后 20 条与最前 3 条消息。retention 配置段则决定磁盘上保留多少原始历史与消息预览 文本；参见配置参考。

消息平台配置​

消息平台在 channels 下配置，以平台为键——例如 weixin、telegram、slack、 discord、feishu、whatsapp 等。每个渠道块都带有自己的 enabled 标志、一个 account_id、其令牌的密钥引用（如 token_ref 或 bot_token_ref），以及 dm_policy、group_policy 等投递策略字段。channel_webhooks 配置段则配置可选的 webhook 监听器（默认禁用，127.0.0.1:8770）。请使用 anyy setup channels 进行配置；字段级细节见渠道参考。

Dashboard 设置​

anyy config 为当前 home 渲染一份只读配置摘要：状态、解析出的路径、服务商凭据 检查、所选模型、时区、上下文压缩默认值，以及已配置的消息平台。它不会改动任何东西 ——它是确认运行配置实际解析结果的最快方式。运行时的实时健康状况由 状态与诊断单独报告。

隐私与脱敏​

按设计，密钥不会进入 config.yaml：文件只保存 _ref 引用，真正的材料位于环境 变量、被引用的文件，或 <home>/secrets 下托管的密钥存储中。诊断输出会对密钥取值 做脱敏——例如 anyy config 只把凭据报告为已设置 / 未设置 / 无效，绝不显示其 内容。当为了支持而分享配置文件或日志时，_ref 模型意味着你可以原样分享文件而不会 泄露密钥。

时区​

顶层 timezone 字段设定助手用于调度、时间戳和时间相关回复的时钟。它接受 IANA 时区 名称，例如 Asia/Shanghai 或 America/New_York。留空（""）则回退到 gateway 主机 的本地时区。解析出的时区会在 anyy config 的 Timezone 下显示（未设置时为 (host-local)）。