Astra GateEnglish

客户端

一键接管 Codex / Claude Code / Gemini CLI 等本机客户端

「接管」是 Astra 的核心体验:不用手工编辑客户端配置文件,控制台里点一下即可把客户端指向网关,随时可还原。

每个客户端一个标签页

客户端页:Codex 已启用并绑定 DeepSeek

页面顶部是本机检测到的客户端标签(启用过的带 ✓)。选中某个客户端后,下方是它的接管卡片:

  • 状态行 — 「已启用」徽标 + 已写入的配置文件路径;右侧 禁用并还原;下方是最近一次写入配置的时间;
  • 使用的提供商 — 可添加多个并拖动排序,修改后立即生效,不需要修改客户端配置文件。还没选过提供商的客户端默认使用列表里第一个可用的提供商,不用先手动添加就能直接启用;之后增删或调整顺序时,这个默认值会随列表一起保存;
  • 令牌 — 写入客户端配置的令牌,默认是「默认令牌」,多个客户端可以共用一个;
  • 模型 — 启用时写入客户端配置的默认模型。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 写入这些位置(括号内为可覆盖目录的环境变量):

客户端配置文件Astra 写入的内容
Pi~/.pi/agent/models.json、settings.json(PI_CODING_AGENT_DIR)新增 astra 提供商(含所绑定提供商的模型列表,以及已知的上下文、输出上限、是否支持图片和推理);原生协议不是 Chat 的模型带自己的 api(及对应的 baseUrl)。选了模型时设置 defaultProvider / defaultModel
Hermes Agent~/.hermes/config.yaml(HERMES_HOME;Windows 为 %LOCALAPPDATA%\hermes)model 段:provider: custom、base_url、api_key,选了模型时写 default;所选模型的原生协议是 Anthropic 时写 api_mode: anthropic_messages。Hermes 不给自定义端点用 Responses,原生协议为 Responses 的模型走 Chat,由网关转换
MiniMax Code~/.minimax/config.yaml(MINIMAX_DATA_DIR)新增 custom_provider.astra(含模型列表);原生协议为 Responses / Anthropic 的模型放进 astra-responses / astra-anthropic(MiniMax 的协议按提供商设置,没有这类模型时不创建)。选了模型时设置 defaultModel
Copilot CLI~/.copilot/providers.json、settings.json(COPILOT_HOME)在 BYOK 列表里新增 astra 提供商及其模型(不动你已有的条目);原生协议为 Responses / Anthropic 的模型挂在 astra-responses(wireApi: responses)/ astra-anthropic 提供商下,需要时才创建。选了模型时设置 model 为 <提供商>/<模型>
VS Code CopilotVS Code 用户目录下的 chatLanguageModels.json(macOS ~/Library/Application Support/Code/User,Windows %APPDATA%\Code\User,Linux ~/.config/Code/User)新增名为 Astra 的 Custom Endpoint 模型组,列出所绑定提供商的模型;每个模型按原生协议设置 apiType(chat-completions / responses / messages)和对应的 url,令牌写在每个模型的 requestHeaders 里。模型在 VS Code 的模型选择器中挑选
Crush~/.config/crush/crush.json(CRUSH_GLOBAL_CONFIG 为目录;也认 XDG_CONFIG_HOME)新增 providers.astra(openai-compat,含模型列表);原生协议不是 Chat 的模型放进 astra-responses(openai,Crush 只对 gpt-4 及以后的 id 走 Responses)、astra-anthropic 或 astra-gemini,需要时才创建。选了模型时设置 models.large。若同目录有 crushrc,它对同名顶层键优先于 crush.json,卡片会提示
Qwen Code~/.qwen/settings.json按模型的原生协议在 modelProviders.openai(Responses 模型带 wireApi: responses)、anthropic 或 gemini 数组里新增 Astra 的模型条目,令牌写入 env.ASTRA_QWEN_API_KEY;选了模型时设置对应的 security.auth.selectedType 与 model.name。模型列表热加载,切换模型可能需要重启
Droid~/.factory/settings.json在 customModels 里为每个模型新增一条 BYOK 条目(显示名 Astra: <模型>;provider 按原生协议取 generic-chat-completion-api、openai(Responses)或 anthropic,并带上已知的上下文与输出上限)。Droid 不公开自定义模型的默认 id,所以 Astra 不设默认模型,请在 /model 里挑选
Kimi Code~/.kimi-code/config.toml(KIMI_CODE_HOME)新增 [providers.astra](type = "openai")与每个模型一张 [models.astra-<模型>] 表(模型 id 里的 . 等符号在别名中换成 -;原生协议为 Responses / Anthropic 的模型带 protocol);选了模型时设置 default_model。旧版 Python Kimi CLI 的 ~/.kimi 不会被改动
Zed~/.config/zed/settings.json(Windows %APPDATA%\Zed,Linux 认 XDG_CONFIG_HOME)新增 language_models.openai_compatible.astra(含模型列表,原生协议为 Responses 的模型设 capabilities.chat_completions: false);选了模型时设置 agent.default_model。Zed 不从 settings.json 读取密钥,所以令牌不会被写入:请在 Zed 的智能体设置里选 Astra 提供商,把令牌页的令牌粘贴一次(或启动 Zed 前设置环境变量 ASTRA_API_KEY)
VS Code Insiders / VSCodium各自用户目录下的 chatLanguageModels.json(Code - Insiders/User、VSCodium/User),写法与 VS Code Copilot 相同VSCodium 默认不带 Copilot(Copilot Chat 也不在 Open VSX 上):需要 "chat.disableAIFeatures": false、自定义 product.json 并手动安装 Copilot Chat 扩展,Astra 只写端点文件,卡片会提示
omp(oh-my-pi)~/.omp/agent/models.yml、config.yml(PI_CODING_AGENT_DIR)新增 providers.astra(openai-completions,auth: apiKey,含模型列表);原生协议不是 Chat 的模型带自己的 api。选了模型时设置 modelRoles.default 为 astra/<模型>
MiMo Code~/.config/mimocode/mimocode.json(c)(Windows %LOCALAPPDATA%\mimocode)与 OpenCode 相同的 provider.astra;选了模型时设置 model。该客户端的 MIMOCODE_HOME 对路径的影响没有文档,设置了会提示
DeepSeek Harness~/.dsh/profiles/desktop/cordis.patch.yml、~/.dsh/profiles/web/cordis.patch.yml(取其中已存在的;DSH_HOME)和 ~/.dsh/.env在 llm-pi-ai 行里新增 providers.astra(自定义模型 API,openai-completions,含模型列表;原生协议为 Responses / Anthropic 的模型放进 astra-responses / astra-anthropic),保留你已有的提供商;选了模型时把 agent-default-model 行的 provider / model 改为 Astra(其 reasoningEffort 暂时移除,因为所选模型未必声明了它,停用时还原)。Astra 已知会思考的模型在列表里额外带 reasoningEfforts(low / medium / high),Harness 据此在输入框旁显示思考程度选择;不确定是否支持思考的模型不声明,Harness 就不显示。Harness 的配置里不放明文密钥,只放 apiKeyEnv 引用,所以令牌写进 ~/.dsh/.env 的 ASTRA_GATEWAY_API_KEY(优先级最低,不会盖过你在 Harness 里保存的密钥或启动环境里的变量)。Harness 还没创建过 desktop / web 配置时请先启动一次;$DSH_HOME/cordis.patch.yml(家目录层)里若也有 llm-pi-ai 行,它会盖过 profile 里的,卡片会提示
Muse Code用户的 shell 配置文件 ~/.zshrc(只存在 ~/.bashrc 时用它);检测目录为 ~/.config/muse。Muse 没有可写入的端点配置项在 rc 文件里写入一段 # >>> astra muse-code >>> 受管块,定义 muse shell 函数:muse exec 与无子命令的交互式 muse 会带上 --base-url <网关>/v1、META_API_KEY(本客户端的网关令牌)和 MUSE_MODEL 运行,仅限这一次调用;resume、login 等其它子命令照常使用你的 Meta 账号。MUSE_MODEL 取你选的模型,未选时取绑定提供商的第一个模型(Muse 不带 --model 时的默认模型解析会报 "no visible models")。需要重新打开终端。模型列表由网关的 /muse-code/models(主机根路径,不在 /v1 下)提供
WorkBuddy~/.workbuddy/models.json在 models 数组里为每个模型新增一条自定义模型(Chat Completions,url 为完整的 /v1/chat/completions 地址,显示名 Astra: <模型>),不动你已有的条目。WorkBuddy 会读取这里配置的模型并可在「设置 → 模型」里查看;文件热加载。0.3.0 及更早的 Astra 误写入 CodeBuddy 的 ~/.codebuddy/models.json,重新「应用」后会把那里的 Astra 条目清掉。Astra 不设默认模型,请在模型选择器的自定义模型分组里挑选。若你设置了 availableModels,需把 Astra 的模型 id 加进去。models.json 顶层是空数组(含 [ ]、带注释的)时会被换成对象;顶层是有内容的数组时 Astra 不会改它并提示出错,请自行改成 {"models": [...]}才会显示
WorkBuddy AI~/.workbuddy-ai/models.jsonWorkBuddy 国际版(workbuddy.ai)。与 WorkBuddy 是同一个应用,数据放在 ~/.workbuddy-ai,写法相同:每个模型一条 Astra: <模型> 自定义模型,不动你已有的条目;文件热加载。两个版本是两个独立的客户端,各自启用、各自还原
Paseo~/.paseo/config.json(PASEO_HOME)在 agents.providers 里新增一个名为 Astra 的自定义提供商 astra:extends: "claude"(仍由你本机的 Claude Code 运行),env 里写 ANTHROPIC_BASE_URL(网关地址)与 ANTHROPIC_AUTH_TOKEN(本客户端的令牌),models 列出所绑定提供商的模型(选了模型时它是默认模型,否则第一个),并按 Paseo 文档把第三方端点不支持的 WebSearch 放进 disallowedTools。原生协议为 Responses 的模型另放进 astra-codex(extends: "codex",用你本机的 Codex 运行,env 里写 OPENAI_BASE_URL / OPENAI_API_KEY)。你自己的提供商与 profile 不动。改动在 paseo reload 或重启守护进程后生效;需要本机已装好 Claude Code。注意 Claude Code 会读取 ~/.claude/settings.json 的 env,若那里设了别的 ANTHROPIC_BASE_URL 会盖过这里的值(同时启用 Astra 的 Claude Code 客户端则没有冲突)
NextCoWork~/.next-cowork/providers.json新增提供商 providers.astra(openai-chat,baseUrl 为 <网关>/v1),列出所绑定提供商的模型;原生协议为 Responses / Anthropic 的模型带 protocolOverride。文件热加载。NextCoWork 改动这个条目时(在它的界面里编辑模型、同步模型目录)会补上思考设置、完整能力表等字段,这些归 NextCoWork 管,Astra 重写时原样保留、也不算作改动;你在 NextCoWork 里改的模型协议会被记录为该模型的协议选择
ZCode~/.zcode/v2/provider_config.json(ZCODE_DESKTOP_HOME_DIR)在「自定义供应商」里新增名为 Astra 的供应商 astra(openai-chat-completions,baseUrl 为 <网关>/v1),列出所绑定提供商的模型,并为每个模型写一条模型规则(已知的上下文窗口、是否支持图片 / PDF,以及 supportsNativeWebSearch: false——网关不提供服务端搜索工具)。ZCode 的协议按供应商设置,原生协议为 Responses / Anthropic 的模型放进 astra-responses / astra-anthropic(后者 baseUrl 为网关根地址,ZCode 自己补 /v1/messages),用不到时不创建。文件热加载(ZCode 每秒检查一次)。ZCode 只在这个文件不存在时导入旧版 config.json 里的供应商,所以 Astra 不会替它创建:请先启动一次 ZCode 再启用。你在 ZCode 里关掉这个供应商、拖动模型顺序或开关某个模型,Astra 重写时原样保留,也不算作改动;默认模型由 ZCode 自己管理,请在它的模型选择器里挑 Astra 的模型
TKCode~/.tkcode/settings.json(TKCODE_HOME)在 providers 里新增自定义厂商 astra(api 为 chat,baseUrl 为 <网关>/v1),列出所绑定提供商的模型,并写入已知的名称、上下文窗口、最大输出、是否推理 / 支持图片;选了模型时同时把顶层 model 设为 astra/<模型>。原生协议为 Responses / Anthropic 的模型单独带 api(responses / messages),三种协议共用同一个 <网关>/v1 地址(TKCode 对 messages 会自己去掉 /v1)。文件是 JSONC,TKCode 热加载;文件不存在时由 Astra 创建。你在 TKCode 设置页里停用这个厂商、给模型加覆盖项(如推理档位)或改某个模型的协议,Astra 重写时原样保留,也不算作改动(改过的协议会记为该模型的协议选择);关掉某个模型,或改了 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 的输出为准。

卸载

已安装客户端的「版本」分组里有一行 卸载:

安装方式卸载
npm 全局包点 卸载 运行 npm uninstall -g <包>(装在旧的 npm 前缀下时带上 --prefix),输出与安装一样实时显示。只有终端里运行的那一份确实是 npm 全局安装的,才提供这个按钮;通过原生安装器、Homebrew、bun 等方式装的,Astra 会提示你用原来的方式卸载——这时 npm uninstall 删不掉正在用的那一份。npm 全局目录属于系统管理员时,和安装一样会弹出管理员授权
VS Code 扩展(Copilot Chat)运行 code --uninstall-extension GitHub.copilot-chat;VS Code 自带的那份无法单独卸载
官方安装脚本(Hermes Agent)、桌面应用与手动安装的客户端Astra 不会自动卸载,请按官网说明操作(「主页」按钮)

如果 Astra 正在接管这个客户端的配置(已启用),卸载会先禁用并还原它的原始配置——和「禁用并还原」走同一条路径,你手动改过的配置项保持原样——再运行卸载命令,确认框会写明这一点。卸载只删除程序本身,客户端自己的数据与配置文件(如 ~/.codex)不会被删除。卸载后如果仍能找到这个客户端(例如另有一份不是 npm 装的),日志会指出它的位置。

启用

未启用的客户端:点「启用…」由 Astra 代写配置

切换到一个未启用的客户端标签,点 启用…,Astra 会:

  1. 展示将要写入的改动清单(只新增 / 修改 Astra 自己的配置项);
  2. 首次修改前备份原文件(这份备份永久保留);
  3. 写入网关地址与所选令牌。

写入客户端的密钥形如 sk-astra-xxxx.codex:前半是令牌本身,. 后面是客户端标识,网关据此识别是哪个客户端发来的请求,再按该客户端绑定的提供商转发。用量记在令牌名下。

启用后客户端需要重启一次使配置生效;之后切换提供商、模型都在控制台完成,客户端无需再动。更换令牌需要重新写入配置:在「令牌」分区选择新令牌后点 应用,确认改动即可。

维护

项说明
复制配置文件路径快速定位 Astra 代管的客户端配置文件
配置备份每次修改前自动备份,可随时恢复;首次修改前的备份永久保留,另有约 20 份滚动备份
修复配置文件有些客户端(目前是 Claude Desktop)按标准 JSON 读取配置,文件里多一个逗号或一行注释就读不了。客户端页会指出是哪个文件、第几行,点 修复 只删掉这些逗号和注释,其余内容不动,修改前照常备份

需要让密钥失效时,到令牌页重置对应令牌:使用它的已启用客户端会自动改写配置。

禁用与还原

  • 禁用并还原 — 撤销 Astra 写入的配置项,恢复到启用前的状态;
  • 如果某些配置项在你启用后又被手动改过(「漂移」),Astra 不会擅自覆盖,会列出这些项并询问是否强制还原;
  • 服务器已经卸载、控制台打不开?终端运行 astra restore-all 可以离线还原全部客户端配置(见 CLI 参考)。