Gateway

Gateway 是常驻的 Anyy runtime。它拥有长生命周期状态，并在 TUI、CLI chat、dashboard、 channels、cron 和 background work 之间进行调度。

最快路径不要求你先启动 service：运行 anyy 会打开 TUI，并在需要时启动 embedded gateway。 当你希望 TUI 退出后 Anyy 仍然可用，或希望 one-shot chat、channels、dashboard 和 scheduled work 持续运行时，再启动 resident gateway。

什么时候需要运行它

Workflow	Gateway mode
只进行交互式终端使用	运行 anyy；TUI 会在需要时启动 embedded gateway。
使用 anyy chat 发送 one-shot shell prompts	先启动 resident gateway。
Messaging channels	运行 resident gateway，让 adapters 可以接收和回复。
Cron、heartbeat 和 background delivery	持续运行 resident gateway。
在 TUI 外访问 dashboard	运行 resident gateway 和 dashboard sidecar。

Gateway 拥有什么

Gateway 拥有不应属于单个 client 的 runtime concerns：

• Session creation、resume、active turns、queueing、stopping、branching 和 compression。
• 每个 turn 的 context assembly。
• Provider/model runtime state 和 fallback handling。
• Tool registry、toolsets、approvals、ChangePlans 和 audit events。
• Messaging channel adapters 和 channel reload。
• Cron、heartbeat、background jobs，以及 session inbox/outbox delivery。
• RPC status、diagnostics 和 local event streaming。

Clients 连接到它；它们不拥有 agent loop 或 durable session state。

启动与停止

启动 resident gateway：

anyy gateway start

检查：

anyy gateway status
anyy status

修改 gateway-level configuration 或升级 binary 后重启：

anyy gateway restart

停止：

anyy gateway stop

这四个命令都接受 --home PATH，全局 --profile / --profile-root flags 会在解析 home 前选择 profile。

作为 Service 安装

anyy gateway start 会管理 resolved home 对应的 background service。如果尚未安装受支持的 service，它会先安装，然后等待 gateway RPC endpoint 可达。

当前实现支持的 service hosts：

Host	Status 中显示的 label
macOS launchd user service	launchd user service
Linux systemd user service	systemd user service
procd	procd service

在不受支持的 host 上，命令会报告 gateway service management 不可用。TUI embedded gateway 仍可用于 交互式本地使用。

Unix Socket

Profile home 包含默认 Unix-domain socket：

<home>/anyy.sock

多数本地 clients 默认使用该 socket。只有在命令明确支持 --socket PATH 时才覆盖它：

anyy status --socket /path/to/anyy.sock
anyy chat --socket /path/to/anyy.sock "Hello"

Gateway config 也有 TCP listener fields。不要因为某个 listener 在你的环境中是本地的，就假定它安全； 请检查有效配置和运行时状态：

anyy status --json

配置字段和默认值见配置参考。暴露面和 token 建议见 安全与隐私。

RPC Boundary

RPC 是 clients 与 resident runtime 之间的 transport boundary。TUI、CLI chat、dashboard、 channels 和 internal service entrypoints 会调用 gateway RPC methods，用于 sessions、commands、 status、approvals、tools、profiles、roles、MCP、channels 和 diagnostics。

这个边界让 client surfaces 保持轻量。Dashboard 或 chat adapter 可以请求一个 session turn， 但 context assembly、tool governance、approvals 和 persistence 仍由 gateway 拥有。

Session Queue

同一个 session 同一时间只应有一个 turn 主动运行。当 turn 正在运行时又有输入到来，runtime 会根据 command behavior 决定处理方式：

Behavior	示例
排到 running turn 后面	/queue，或 busy mode 为 queue 时的普通输入。
Steer running turn	/btw 或 /steer。
停止 running turn	/stop、TUI interrupt 或 session stop RPC。
Running 时拒绝	/branch、/compress、/retry 等命令。

Queue 是 per session 的，因此一个 busy conversation 不会阻塞无关 sessions。

Channel Runtime

Messaging channels 在 resident gateway 内运行。修改 channel configuration 后，重启 gateway 或 reload channel adapters：

anyy channels reload

Channel doctors 在 gateway 外运行，并校验单个 channel 的本地 readiness：

anyy channels doctor telegram

Channel-specific setup 从 Messaging Gateway 和 Channels Reference 开始。

Background Jobs

Gateway 拥有可超出单个 foreground reply 生命周期的工作：cron jobs、heartbeat checks、 background child agents、managed shell/process jobs、channel delivery，以及 session inbox/outbox records。

常用入口：

anyy cron list
anyy heartbeat status

在 TUI 中，/background、/agents、/jobs 和 /job 会暴露当前 session 的 background work。

Logs 与 Status

关心 resident process 是否已安装并可达时，使用 service-level status：

anyy gateway status

想查看 profile、role、home、timezone、subsystem 和 gateway listener summary 时，使用 runtime status：

anyy status
anyy status --json

本地诊断使用 doctor：

anyy doctor
anyy doctor --json

Gateway 会在 profile home 下写本地 logs。TUI /logs 命令显示最近本地 lines；debug bundles 和 diagnostics 会在输出前脱敏已知 secrets。

常见失败模式

现象	检查什么	常见修复
TUI 可用，但 anyy chat 失败	anyy gateway status	为同一个 profile/home 启动或重启 resident gateway。
Service management 不受支持	anyy gateway status --home PATH	使用 TUI embedded gateway，或在 launchd、systemd user、procd host 上运行。
Status 显示版本不一致	Command 与 running process versions	更新 binary 后运行 anyy gateway restart。
Socket 不可达	anyy status --socket PATH 和 <home>/runtime.json	使用 resolved socket path，或重启 gateway。
出现错误 sessions 或 config	anyy status 中的 resolved profile/home	显式传入 --profile NAME 或 --home PATH。