故障排查

本页是症状索引。它把你带到正确命令和负责该领域的页面，而不是复制每一份 setup guide。如需完整本地健康报告，先运行 anyy status 和 anyy doctor。

如何使用本页

先运行下面的 first-step commands。
将失败区域匹配到症状索引。
按链接页面中的详细步骤修复。
如果要把输出发给别人，请先移除 secrets 和 tokens。

大多数命令接受 --home PATH；只要你不确定当前 active profile/home，就显式传入它。

先收窄范围

改 config 之前，先确认问题是跟着 profile、resident gateway、某个 channel，还是某个 session 走：

anyy profile list
anyy status --home ~/.anyy
anyy gateway status --home ~/.anyy

如果只有一个 channel 失败，先运行 anyy channels doctor CHANNEL。如果只有一段 conversation 失败，先在 active surface 中尝试 /status、/sessions、/history 和 /stop，再编辑全局 config。

第一步：status 与 doctor

检查运行时 surface：

anyy status --home ~/.anyy
anyy status --home ~/.anyy --json

status 会报告 resolved home、profile、default role、timezone、gateway state、gateway listener、cron、heartbeat、storage 和 MCP summary。如果 gateway 可达，它会把 live gateway status 合入本地报告。

然后运行 doctor：

anyy doctor --home ~/.anyy
anyy doctor --home ~/.anyy --json

doctor 会检查 filesystem、profile、config validity、timezone、gateway listener、channel config 和 secret refs、cron、heartbeat、MCP 以及 storage。JSON 输出最适合 bug report，因为每个 check 都有 name、status 和 detail。

症状索引

安装与更新

症状	检查	下一页
找不到 `anyy`	`which anyy` 和 `anyy --version`	安装
已安装版本与正在运行的 gateway 不一致	`anyy gateway status`	Gateway
更新检查失败	`anyy update --check --home ~/.anyy`	更新
需要移除 Anyy	`anyy uninstall --keep-data --yes` 或 `--full --yes`	数据、留存与删除

Setup 与 providers

症状	检查	下一页
Config parse 或 validation 失败	`anyy config --home ~/.anyy`；`anyy doctor --home ~/.anyy`	配置参考
Provider key 缺失	检查 `api_key_ref` 或 `credential_ref` 及其引用的 env/file/secret	凭据与鉴权
选错模型	`anyy setup model --home ~/.anyy`	配置模型
Fallback routing 未使用	`anyy setup model fallback --home ~/.anyy`	配置模型

Gateway 无法启动或无法保持运行

症状	检查	下一页
TUI 可用但一次性 `chat` 失败	启动 resident gateway：`anyy gateway start`	Gateway
Socket 无法连接	`anyy status --socket PATH`；检查 `anyy.sock` 和 `runtime.json`	Gateway
Service manager 不受支持	`anyy gateway status --home ~/.anyy`	常驻服务运行
Gateway 运行的是旧 binary	`anyy gateway restart`	更新
Heartbeat 过旧或 degraded	`anyy heartbeat status --home ~/.anyy`	Heartbeat

Channels 不投递

症状	检查	下一页
Channel config 存在但 disabled	`anyy channels doctor CHANNEL --home ~/.anyy`	Channels Reference
Secret ref 失败	解析该 channel 的 `secret:`、`env:` 或 `file:` 引用	Channels Reference
Telegram 无响应	`anyy channels doctor telegram --home ~/.anyy`	Telegram 设置
配置变更未生效	`anyy channels reload --home ~/.anyy`	Messaging Gateway
Live smoke 是 `warn`	设置 `ANYY_LIVE_CHANNEL_TESTS=1` 和该 channel 的测试环境变量	Channels Reference

MCP server 失败

症状	检查	下一页
Server 未列出	`anyy mcp list --home ~/.anyy`	MCP 配置参考
Server config 存在但 tools 缺失	`anyy mcp show SERVER_ID --home ~/.anyy --json`	MCP 集成
Server 无法连接	`anyy mcp probe SERVER_ID --home ~/.anyy`	MCP 集成
Runtime 需要 reload	`anyy mcp reload [SERVER_ID] --home ~/.anyy`	MCP 配置参考

认证错误

症状	检查	下一页
Env ref 为空	对 `env:NAME` 引用运行 `printenv NAME`	环境变量
Profile-local secret 缺失	对 `secret:<name>` 引用检查 `~/.anyy/secrets/<name>`	数据、留存与删除
Provider auth profile 不受支持	检查 provider 的 `profile`、`auth_mode` 和 `auth_profile`	Provider 配置
OAuth 或 external auth 需要刷新	重新运行 provider setup/auth flow	凭据与鉴权

性能与状态体积

症状	检查	下一页
State database 变大	`anyy status --json` 的 storage section	数据、留存与删除
Raw backlog 增长	`anyy maintenance prune-inactive-sessions --home ~/.anyy`	维护
Token estimates 缺失	`anyy maintenance cache-token-estimates --home ~/.anyy --execute`	维护
Turn 卡住	使用 TUI `/stop`、`/queue`、`/btw` 或 `/busy interrupt`	Sessions

常见模式

模式	原因	修复
TUI 可用，但 `anyy chat` 失败	Embedded gateway 存在，但 resident gateway 不可达	为同一个 home/profile 启动 resident gateway。
Default profile 可用，另一个 profile 失败	Config、secrets、skills 或 channel state 是 profile-local	在该 profile 中运行 setup，或只复制确实需要的 config。
Doctor 通过，但 live request 失败	Doctor 主要是本地验证	运行 provider、MCP 或 channel-specific live probe。
Secret 在 shell 中可用，但 service 不可用	Service manager 没继承你的 shell environment	存为 `secret:`，或注入到 service environment。

收集 Debug Bundle

在 active TUI 或兼容 command surface 中可用时，使用 debug 命令：

/debug

如果只有 CLI 输出，请收集：

anyy --version
anyy status --home ~/.anyy --json
anyy doctor --home ~/.anyy --json
anyy gateway status --home ~/.anyy

不要包含原始 secret values、bot tokens、OAuth credentials、private channel messages，或可能包含用户数据的完整日志。Anyy 会脱敏已知 secret values，但你仍应审阅任何要分享的内容。

如何寻求帮助

提问时请包含：

Anyy version。
OS 和安装方式。
你运行的精确命令。
相关的 status --json 和 doctor --json checks。
问题是否只和某个 profile/home、某个 channel 或某个 session 相关。

避免发送会暴露 tokens、channel IDs、private messages，或你不想公开的本地文件系统路径的截图。

如何使用本页​

先收窄范围​

第一步：status 与 doctor​

症状索引​

安装与更新​

Setup 与 providers​

Gateway 无法启动或无法保持运行​

Channels 不投递​

MCP server 失败​

认证错误​

性能与状态体积​

常见模式​

收集 Debug Bundle​

如何寻求帮助​