常见问题
为什么我装了某工具但 ATM 不显示
ATM 只显示能从磁盘文件验证存在的 Agent。常见原因：
- 工具从未在本机运行过，配置文件尚不存在。请先运行一次该工具，再点 Rescan。
- 工具配置不在默认路径。可在 Settings → Paths 中覆盖。
- 工具配置 schema 已变更，当前版本 ATM 不支持。请提交 issue 并附上版本号。
- 工具已卸载但残留配置文件仍存在。手动删除即可。
为什么我刚切到 ATM Gateway，请求就失败
最常见原因：网关未启动。将 Agent 路由切换为 ATM Gateway 不会自动启动网关。请打开 Overview 页面，点击 Start Gateway，再重试。
其他原因：
- Agent 未绑定策略。打开 Agents → \
- 绑定的策略中没有与当前协议家族兼容的 target。打开 Routing → \<策略> 验证配置。
- Agent 进程未完全重启。完全退出后重新启动。
为什么 Usage 和网关日志对不上
两者反映的是不同数据源：
- Usage 合并了本地历史（该工具产生的所有请求）与网关日志（仅经过 ATM Gateway 的请求）。
- 网关日志 仅记录网关自身处理的请求。
如需两者完全一致，将所有 Agent 路由至 ATM Gateway。否则 Usage 始终是网关日志的严格超集。
Provider key 安全吗
ATM 将 Provider key 交由 macOS Keychain 加密保存，不会离开本机。ATM 不主动发起外部请求，仅在以下两种情况下产生出站流量：（a）通过网关代表 Agent 调用上游；（b）手动触发更新下载时。
网关仅绑定 127.0.0.1:4317，来自非回环地址的入站连接一律被拒绝。
为什么网关端口是 4317
4317 不在标准本地应用端口段（3000–8000），与常见工具冲突最少。OpenTelemetry collector 的 OTLP gRPC 端点同样使用 4317，但 ATM 网关为 HTTP 协议；除非在同一机器上运行了 OTel collector，否则不产生冲突。
能否同时运行两个 ATM 实例
不支持。网关只能绑定一个端口，第二个实例无法启动网关。桌面端同样拒绝第二个实例，以维护数据库状态一致性。
能否多个工具共用同一把 ATM key
技术上可行，但不建议：单个 key 无法区分各工具的 Token 归属；策略绑定到 Agent，共用 key 会造成策略混淆；当某个 key 泄漏需要撤销时，不应波及其他工具。建议每个 Agent 独立签发 key。
请求实际使用的模型与配置不符
两种常见原因：
- 该 Agent 绑定了
Test策略。Test策略根据请求意图动态选择 target，模型切换属于预期行为。如需固定模型，切换至Default策略。 - 默认 target 的 Provider 不健康，ATM 执行了 fallback，由备用 Provider 的默认模型处理请求。可通过
/api/logs定位触发原因。
为什么策略无法以 ATM Gateway 为 target
策略不能将流量路由回网关——否则会形成路由环路。策略 target 必须为普通 API Provider。详见 路由页。
升级会丢失数据吗
升级过程中 ~/.atm/ 目录保留。schema 迁移前会自动向 ~/.atm/backups/ 写入备份。迁移失败时 ATM 将提示从备份恢复。正常升级不会丢失数据。
ATM 支持哪些平台
当前支持 macOS 和 Windows。macOS 安装包为 .dmg（Apple Silicon aarch64 为主，Intel-Mac 由同一流水线产出）；Windows 安装包为 .zip（x86_64）。
如何提交 bug
一份有效的 bug 报告应包含：
- ATM 版本（Settings → About）。
- 操作系统版本。
- 操作步骤、预期行为与实际行为。
atm doctor输出。~/.atm/logs/相关片段（Provider key 需脱敏）。