客户端
一键接管 Codex / Claude Code / Gemini CLI 等本机客户端
「接管」是 Astra 的核心体验:不用手工编辑客户端配置文件,控制台里点一下即可把客户端指向网关,随时可还原。
每个客户端一个标签页
页面顶部是本机检测到的客户端标签(启用过的带 ✓)。选中某个客户端后,下方是它的接管卡片:
- 状态行 — 「已启用」徽标 + 已写入的配置文件路径;右侧 禁用并还原;下方是最近一次写入配置的时间;
- 使用的提供商 — 可添加多个并拖动排序,修改后立即生效,不需要修改客户端配置文件。还没选过提供商的客户端默认使用列表里第一个可用的提供商,不用先手动添加就能直接启用;之后增删或调整顺序时,这个默认值会随列表一起保存;
- 令牌 — 写入客户端配置的令牌,默认是「默认令牌」,多个客户端可以共用一个;
- 模型 — 启用时写入客户端配置的默认模型。Claude Code 还提供 Fable / Opus / Sonnet / Haiku 四档选择,对应
ANTHROPIC_DEFAULT_FABLE_MODEL/ANTHROPIC_DEFAULT_OPUS_MODEL/ANTHROPIC_DEFAULT_SONNET_MODEL/ANTHROPIC_DEFAULT_HAIKU_MODEL(Haiku 档兼作快速/后台模型)。所有模型选项默认留空,留空就不写入,配置文件里已有的同名设置也不会被改动;修改后需要重新写入客户端配置; - 维护 — 复制配置文件路径、配置备份。
支持的客户端:Codex、Claude Code、Gemini CLI、OpenCode、Claude Desktop、Grok Build、Pi、Hermes Agent、MiniMax Code、GitHub Copilot CLI、VS Code 中的 GitHub Copilot,以及 Crush、Qwen Code、Droid、Kimi Code、Zed、VS Code Insiders、VSCodium、omp(oh-my-pi)、MiMo Code、DeepSeek Harness、WorkBuddy、WorkBuddy AI、Muse Code、NextCoWork、Paseo、ZCode、TKCode。
后加入的几个客户端由 Astra 写入这些位置(括号内为可覆盖目录的环境变量):
Pi、MiniMax Code、Copilot CLI、VS Code 系列、Crush、Qwen Code、Droid、Kimi Code、Zed、omp、MiMo Code、DeepSeek Harness、WorkBuddy、WorkBuddy AI、NextCoWork、Paseo、ZCode、TKCode 与 OpenCode 一样会列出所绑定提供商的模型,提供商的模型增减后会自动同步到客户端配置。
模型协议
网关能在四种协议(OpenAI Chat、OpenAI Responses、Anthropic Messages、Gemini)之间互相转换,但转换会丢东西,比如只在原协议里有效的加密推理内容。所以 Astra 给每个模型配置它的原生协议:所绑定提供商能原样转发、不必转换的协议,按模型自身的限制、再按提供商的「首选上游协议」排序,取客户端支持的第一个。例如 ChatGPT(Codex)订阅的模型只走 Responses,Claude 订阅与 Copilot 的 Claude 模型只走 Anthropic。
客户端能表达的粒度不同:NextCoWork、OpenCode、MiMo Code、Pi、omp、Qwen Code、Kimi Code、Droid、VS Code 系列、Grok Build 和 TKCode 可以按模型设置协议;Crush、Copilot CLI、MiniMax Code、DeepSeek Harness、Paseo 和 ZCode 的协议跟着提供商走,Astra 会按协议拆成几个提供商(astra-responses、astra-anthropic 等),用不到时不创建;Hermes Agent 只额外支持 Anthropic,Zed 只额外支持 Responses。Codex、Claude Code、Claude Desktop、Gemini CLI、Muse Code、WorkBuddy 只说一种协议,其它模型由网关转换。
能按模型选协议的客户端,详情页会多出 模型协议 一组:每个模型默认「自动」(即原生协议),也可以手动指定,修改后重新应用。提供商的端点或首选协议改了,已启用的客户端会和模型列表一起自动更新。
Codex 的模型目录
Codex 的「选项」里有 写入模型目录(默认关闭)。打开后,Astra 在 config.toml 同目录(遵循 CODEX_HOME)写入 astra-models.json,并把 model_catalog_json 指向它,这样 /model 里就能直接选到所绑定提供商的模型:
- Codex 的模型目录会整体替换内置模型列表,所以这个文件先完整保留 Codex 原有的模型(你自己设置过
model_catalog_json时取那份目录,否则取 Codex 缓存的~/.codex/models_cache.json),再追加 Codex 还没有的模型;同名模型保留 Codex 自己的条目; - 追加的模型复制自 Codex 原有条目(包括系统指令),再换上模型 id、显示名,以及已知的上下文窗口、是否支持图片和推理;
- 需要先运行过一次 Codex,让它生成
models_cache.json(或者你自己设置过模型目录),否则不会写入目录; - Codex 只在启动时读取模型目录:提供商的模型增减后 Astra 会自动更新这个文件,但要重启 Codex 才能看到变化;
- 关闭选项后重新应用,
model_catalog_json恢复原值、目录内容被撤回;「禁用并还原」时连astra-models.json一起删除。你自己的目录文件始终不会被改动。
安装与更新
npm 分发的客户端(Codex、Claude Code、Gemini CLI、OpenCode、Grok Build、Pi、MiniMax Code、Copilot CLI、Crush、Qwen Code、Droid、Kimi Code、MiMo Code)可以在客户端页直接安装、检查并更新(npm install -g <包>@latest)。Hermes Agent 用它官方的安装脚本安装(macOS / Linux 为 curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash,Windows 为 install.ps1;Astra 会以 --non-interactive / -NonInteractive 运行,不弹交互),更新走它自带的 hermes update,最新版本来自 GitHub Releases。Zed、VS Code Insiders、VSCodium、omp(运行在 Bun 上)、DeepSeek Harness(桌面应用或 npx @deepseek-ai/dsh web)、WorkBuddy 与 WorkBuddy AI(桌面应用)和 Claude Desktop 一样只显示已安装版本和下载主页,Astra 不会替你运行安装命令。Qwen Code 需要 Node 22 及以上,Kimi Code 需要 Node 22.19 及以上;Node 太旧时 npm 会给出警告或客户端无法运行。kimi 命令也可能指向已归档的 Python 版 Kimi CLI,版本以 kimi --version 的输出为准。
卸载
已安装客户端的「版本」分组里有一行 卸载:
如果 Astra 正在接管这个客户端的配置(已启用),卸载会先禁用并还原它的原始配置——和「禁用并还原」走同一条路径,你手动改过的配置项保持原样——再运行卸载命令,确认框会写明这一点。卸载只删除程序本身,客户端自己的数据与配置文件(如 ~/.codex)不会被删除。卸载后如果仍能找到这个客户端(例如另有一份不是 npm 装的),日志会指出它的位置。
启用
切换到一个未启用的客户端标签,点 启用…,Astra 会:
- 展示将要写入的改动清单(只新增 / 修改 Astra 自己的配置项);
- 首次修改前备份原文件(这份备份永久保留);
- 写入网关地址与所选令牌。
写入客户端的密钥形如 sk-astra-xxxx.codex:前半是令牌本身,. 后面是客户端标识,网关据此识别是哪个客户端发来的请求,再按该客户端绑定的提供商转发。用量记在令牌名下。
启用后客户端需要重启一次使配置生效;之后切换提供商、模型都在控制台完成,客户端无需再动。更换令牌需要重新写入配置:在「令牌」分区选择新令牌后点 应用,确认改动即可。
维护
需要让密钥失效时,到令牌页重置对应令牌:使用它的已启用客户端会自动改写配置。
禁用与还原
- 禁用并还原 — 撤销 Astra 写入的配置项,恢复到启用前的状态;
- 如果某些配置项在你启用后又被手动改过(「漂移」),Astra 不会擅自覆盖,会列出这些项并询问是否强制还原;
- 服务器已经卸载、控制台打不开?终端运行
astra restore-all可以离线还原全部客户端配置(见 CLI 参考)。