Astra Gate客户端
一键接管 Codex / Claude Code / Gemini CLI 等本机客户端
「接管」是 Astra 的核心体验：不用手工编辑客户端配置文件，控制台里点一下即可把客户端指向网关，随时可还原。
每个客户端一个标签页
Astra — 客户端
页面顶部是本机检测到的客户端标签（启用过的带 ✓）。选中某个客户端后，下方是它的接管卡片：
- 状态行 — 「已启用」徽标 + 已写入的配置文件路径；右侧 禁用并还原；下方是最近一次写入配置的时间；
- 使用的提供商 — 单选卡片，切换后立即生效，不需要修改客户端配置文件；
- 模型 — 启用时写入客户端配置的默认模型（修改后需要重新写入客户端配置）；
- 维护 — 复制配置文件路径、配置备份、轮换本地密钥。
支持的客户端：Codex、Claude Code、Gemini CLI、OpenCode、Claude Desktop、Grok Build、Pi、Hermes Agent、MiniMax Code、GitHub Copilot CLI、VS Code 中的 GitHub Copilot。
后加入的几个客户端由 Astra 写入这些位置（括号内为可覆盖目录的环境变量）：
| 客户端 | 配置文件 | Astra 写入的内容 |
|---|---|---|
| Pi | ~/.pi/agent/models.json、settings.json（PI_CODING_AGENT_DIR） | 新增 astra 提供商（含所绑定提供商的模型列表）；选了模型时设置 defaultProvider / defaultModel |
| Hermes Agent | ~/.hermes/config.yaml（HERMES_HOME；Windows 为 %LOCALAPPDATA%\hermes） | model 段：provider: custom、base_url、api_key，选了模型时写 default |
| MiniMax Code | ~/.minimax/config.yaml（MINIMAX_DATA_DIR） | 新增 custom_provider.astra（含模型列表）；选了模型时设置 defaultModel |
| Copilot CLI | ~/.copilot/providers.json、settings.json（COPILOT_HOME） | 在 BYOK 列表里新增 astra 提供商及其模型（不动你已有的条目）；选了模型时设置 model 为 astra/<模型> |
| VS Code Copilot | VS Code 用户目录下的 chatLanguageModels.json（macOS ~/Library/Application Support/Code/User，Windows %APPDATA%\Code\User，Linux ~/.config/Code/User） | 新增名为 Astra 的 Custom Endpoint 模型组（Chat Completions），列出所绑定提供商的模型；本地密钥写在每个模型的 requestHeaders 里。模型在 VS Code 的模型选择器中挑选 |
Pi、MiniMax Code、Copilot CLI、VS Code Copilot 与 OpenCode 一样会列出所绑定提供商的模型，提供商的模型增减后会自动同步到客户端配置。
启用
Astra — 客户端
切换到一个未启用的客户端标签，点 启用…，Astra 会：
- 展示将要写入的改动清单（只新增 / 修改 Astra 自己的配置项）；
- 首次修改前备份原文件（这份备份永久保留）；
- 写入网关地址与本地访问密钥。
启用后客户端需要重启一次使配置生效；之后切换提供商、模型都在控制台完成，客户端无需再动。
维护
| 项 | 说明 |
|---|---|
| 复制配置文件路径 | 快速定位 Astra 代管的客户端配置文件 |
| 配置备份 | 每次修改前自动备份，可随时恢复；首次修改前的备份永久保留，另有约 20 份滚动备份 |
| 轮换本地密钥 | 生成新的本地访问密钥并写入客户端配置，旧密钥立即失效 |
Claude Desktop 与角色映射
Claude Desktop 只认 Sonnet / Opus / Haiku 这类「角色模型」。Astra 会把它们映射到你选择的提供商模型 （该客户端标签页里的「角色映射」分区），至少设置一个角色，未设置的角色沿用第一个已设置的。
禁用与还原
- 禁用并还原 — 撤销 Astra 写入的配置项，恢复到启用前的状态；
- 如果某些配置项在你启用后又被手动改过（「漂移」），Astra 不会擅自覆盖，会列出这些项并询问是否强制还原；
- 服务器已经卸载、控制台打不开？终端运行
astra restore-all可以离线还原全部客户端配置（见 CLI 参考）。
密钥安全
Astra 写入客户端的是一把本地访问密钥（不是上游 API Key）。它只对本机网关有效， 可随时在「维护」里轮换，使其立即失效重发。