配置文件与设置入口

排查“设置了却没生效”时，先运行 anyy config 核对当前 Profile，再到对应功能入口修改。模型、渠道、工具、定时任务、凭据、Workspace 和状态都按 Profile 保存。

找到负责这项设置的入口

修改内容	推荐入口
第一次设置	anyy setup
模型与凭据	Dashboard → Models 或 anyy setup model
消息渠道	Dashboard → Channels 或 anyy setup channel
图片、视频与语音路由	Dashboard → Models 或对应 Tools 页面
联网搜索	Dashboard → Tools → Web Search
Role、Skill、MCP、Cron	Dashboard 中各自的栏目
查看最终生效配置	anyy config

anyy config 是只读命令。它会显示当前 Profile、路径、provider/model 选择以及凭据引用是否可解析，但不会输出密钥明文。

修改时优先走产品入口

Dashboard 和设置向导会做字段校验、凭据保护，并在支持时刷新正在运行的服务。直接改 YAML 更适合高级排障，因为它不会经过这些引导检查。

手动修改前认清目录

一个 Profile 目录保存该 Profile 的规范数据，常见路径包括：

路径	内容
config.yaml	设置与凭据引用；MCP 配置值保留输入字符串
secrets/	由 Anyy 管理的 Secret
state.db	会话、消息、任务、审计等持久状态
memory/USER.md	长期用户事实与偏好
memory/MEMORY.md	助理的长期记忆
objects/	由规范状态引用的按内容寻址的持久内容
workspace/	上下文文件和用户工作文件
skills/	安装在这个 Profile 的 Skills
roles/	这个 Profile 的 Role 定义

workspace/ 是上下文和文件空间，不是权限边界。工具仍然遵守操作系统权限和执行限制。

检查另一个 Profile

anyy status
anyy config

查看另一个命名 Profile：

anyy --profile work config

部分命令还支持 --home PATH，可直接指定一个 Profile 目录。除非是在排查路径解析，否则不要混用 --profile、--profile-root 和临时 --home。

推理配置与迁移

Profile 的全局推理偏好保存在 main_model.inference，可选的精确模型覆盖保存在根级 model_thinking_levels：

main_model:
  provider_id: your-provider
  model: your-model
  inference:
    enabled: true
    # 省略 level，让全局等级保持未设置。
model_thinking_levels:
  "your-provider/your-model": high

请换成实际配置的 provider/model ID。键按第一个 / 分隔；去除两侧空白后都须非空，但校验不会改写键，查找要求精确匹配。尚未注册的模型键也可保存备用。值为 Pi 命名等级 off、minimal、low、medium、high、xhigh、max；运行时读取会去除值两端空白，空值无效。

全局 enabled 默认 true；为 true 或省略时，省略 level 表示未设置。enabled: false 即使没有 level 也明确请求 off，命名值 off 本身同样有效。请求会按所选模型的支持范围调整；inference.effective_level 只读，不是 YAML 配置项。优先级见推理默认值。

从旧配置升级到 v0.1.107 时：

• 删除 prompt_program.inference_level，空值、null 和其他类型也会被拒绝。全局偏好迁移到 main_model.inference，精确模型偏好迁移到 model_thinking_levels。
• 删除 prompt_program.render_profile，空值或 null 也不能保留；没有替代选择器，也没有必须使用 high 的限制。
• 把产品配置中的 provider_default 换成 Pi 命名等级。全局等级也可直接删除 level 以保持未设置；Map 条目须选择命名值或删除条目。

JSON/YAML 和产品模型 API 会明确拒绝旧输入，不提供别名，也不静默转换为 medium。prompt_program 的公开配置只保留 resource_class。Anyy 不会静默改写这些旧值；请先手动迁移。底层调用合法的省略推理语义继续保留。

重试与模型接口

会话重试、服务商 SDK 重试、fallback 和虚拟模型回调分别控制；retry.enabled 不是关闭所有重试的总开关。providers[].models[] 的有类型模型、采样字段，以及 retry、httpIdleTimeoutMs 的准确设置见服务商协议与模型接口。

MCP 配置

Profile 全局 MCP 定义仍保存在 config.yaml 的 mcp.client.servers 中。该 Profile 的规范 Workspace 还可以包含 .anyy/mcp.json，当前路径为 <ProfileHome>/workspace/.anyy/mcp.json。完整项目定义替换同名 Profile 定义；部分条目只覆盖启用状态、暴露方式及整份有序工具规则。文件格式和表达式见 Profile 与项目配置。

启用状态与默认暴露方式保存到所选定义文件或已有项目覆盖，只影响该服务。通过 Profile 命令修改 description、工具覆盖、连接定义或凭据，仍然编辑原始 Profile 配置；CLI 设置参数与 Profile 定义参数必须分开提交。enable／disable --project 只为尚无覆盖的 Profile 服务创建启用状态覆盖；add／remove --local 则只编辑项目定义，保留 Profile 定义和独立凭据，文件改动要到下次启动或空闲会话重新加载后才生效。

anyy mcp reload 使用已加载的值重新连接，不重新读取文件。启动时或调用既有的空闲 session.reload RPC 时，会重新读取 Profile／项目配置。配置文件中的值表达式、暴露规则及 OAuth 认证详见 MCP 文档。

凭据怎样保存

Anyy 托管凭据通过引用进入配置，不直接保存密钥本身。Dashboard 和设置命令中的显式凭据操作会把支持的密钥写入 Profile 的 secrets/，并限制文件权限。普通 MCP 配置值写入会保留输入的字符串和表达式，不自动创建托管密钥；详见 MCP 配置值。

替换、清除、连接或断开凭据时，应回到创建它的 Models、Tools 或 Channels 页面。不要把 Secret 放入聊天内容、截图、Shell 历史或诊断材料。

已保存，但运行时还没变化

大多数 Dashboard 和设置操作在成功写入后会刷新对应运行时。渠道也可以明确重新加载：

anyy channel reload

配置已经保存、行为却没有变化时，依次检查：

anyy status
anyy doctor
anyy gateway status

只有功能给出的修复建议要求重启，或实时重载无法完成时，才重启 Gateway。

v0.1.107 会拒绝以下旧 MCP 设置，手动维护配置时应删除或迁移：

• mcp.client.enabled：改用各服务自己的 enabled；
• mcp.client.session_idle_ttl_ms：已退休，工具目录按通知和显式操作刷新；
• 服务级 connect_timeout_ms：改用既有 call_timeout_ms，分别限制初始化、发现和工具请求；
• tools.include、tools.exclude、tools.trusted：改用 exposure 和 toolExposure；tools.resources 与 tools.prompts 也已退休。

没有新增 request_timeout_ms 配置键。完整格式与迁移见 MCP Servers。

手动修改前先备份

anyy backup create

备份会保存配置和 Workspace 文件，其中已经写入的内联凭据仍可能原样入包，不能认定普通归档已全量脱敏。默认排除的是托管 secrets/ 目录和受支持的 mcp/oauth/ 存储；--include-secrets 会额外加入这些内容。所有归档都应作为私密资料保护，包含托管秘密时更须按凭据库级别保管。完整流程见 备份与恢复。

常见问题

现象	检查项
设置看起来没有变化	核对当前 Profile，并查看 anyy config
Gateway 仍使用旧值	执行对应 Reload，再查看 anyy status
配置校验失败	回到 Dashboard 表单或设置向导定位具体字段
已配置凭据但无法解析	从所属的 Models、Tools 或 Channels 页面重新保存
手改 YAML 后无法启动	恢复上一份有效文件，或把备份恢复到新的 Profile