使用教程 · vibecli 配置助手 · 全流程实测

一条命令配好 Claude Code 与 Codex —— vibecli 使用教程

vibecli（npm 包名 @vibeapi/cli，与 @vibeapi/api-helper 为同一产物的双包名）是 VibeAPI 官方的命令行配置助手： 向导式把您的 API Key 与模型写入各 AI 编码工具的配置文件， 不需要手工编辑 JSON / TOML，也不需要设置环境变量。 本文覆盖从安装到卸载的完整生命周期，所有带「真实输出」标记的终端内容都来自实际运行， 与您在自己终端里看到的一致。

Claude Code Codex · gpt-5.6-sol npx 免安装可用 自动备份还原 密钥加密存储 多 Profile
我要配置：

选「只配某一个」后，页面自动隐藏另一个工具的内容，只保留您需要的步骤；选择会记住，随时可切回。

00 · vibecli 是什么

在多个 AI 编码工具之间配置同一把 API Key，通常要分别改 ~/.claude/settings.json、 ~/.codex/config.toml 等好几个格式各异的文件，改错一个字段工具就连不上。 vibecli 把这件事收敛成一个交互式向导：选工具 → 选模型 → 自动写入，全程不需要了解各工具的配置格式。

  • 一键写入配置 —— 把当前 API Key 与模型注入 Claude Code、Codex 等工具，写入时做幂等合并，只改与接入相关的字段，不影响您已有的其他设置。
  • 改前自动备份 —— 每次覆盖前先快照（每个文件保留 10 份），vibecli config <tool> restore 随时回退；还原操作本身也可以再撤销。
  • 密钥加密存储 —— API Key 经 AES-256-GCM 加密存放在 ~/.vibecli/secrets.enc，与本机绑定，绝不明文落盘。
  • 多 Profile 管理 —— 工作 / 个人各一套 Key 与模型配置，一条命令切换。
  • 残留环境变量自动清理 —— 启动时检测并清除 shell 里残留的 ANTHROPIC_BASE_URL / ANTHROPIC_API_KEY，杜绝「配置不生效」的头号原因（第 11 章）。

当前主力支持 Claude Code 与 Codex 两个工具，Claude Desktop 桌面端（0.0.46+，见专篇）/ Grok Build（xAI 官方终端代理，见专篇）/ OpenClaw / Hermes / AtomCode 同样可以配置。默认接入点已指向 VibeAPI，不需要手动填 API 地址。

01 · 前置准备

① 确认 Node.js ≥ 20

vibecli 需要 Node.js 20 或更高版本，Windows / macOS / Linux 均支持。已装过的先确认版本：

终端真实输出
node -v v22.17.0 # 只要 ≥ v20 即可；未安装或低于 v20 按下面方式安装

未安装的话不用去官网——Windows 直接用下载中心的国内高速镜像安装包， macOS / Linux 一条命令搞定（脚本同样走国内镜像）：

Node.js · v24.15.0 .msi Windows · x64 · npmmirror 国内高速镜像
macOS 一键装 Node命令示意
curl -fsSL https://cnb.cool/vibeapi/scripts/-/git/raw/main/init-node-mac.sh | sed 's/\r$//' | sh
Linux 一键装 Node命令示意
curl -fsSL https://cnb.cool/vibeapi/scripts/-/git/raw/main/init-node-linux.sh | sed 's/\r$//' | sh
需要 Git、其他版本或架构？ → 打开下载中心 · 基础环境（Node / Git 全集）

② 获取 VibeAPI API Key

  1. 登录 vibeapi.cn 控制台，进入令牌管理；
  2. 点右上角「添加令牌」，令牌名称自定义，分组与额度按需选择，提交；
  3. 回到令牌列表，复制生成的 sk- 开头的密钥备用。

02 · 安装与验证

两种方式二选一：想立刻体验，用 npx 免安装直接跑，一条命令几秒后就进向导； 长期使用建议全局安装，得到更短的 vibecli 命令（与 api-helper 等价）。 两个窗口各自独立，复制自己选的那一个即可：

方式一 · npx 免安装即刻体验真实输出
npx @vibeapi/cli@latest # 首次自动下载，几秒后直接进向导； # @latest 确保每次都是最新版
方式二 · 全局安装（长期使用）真实输出
npm install -g @vibeapi/cli added 187 packages in 12s vibecli -v 0.0.29 # 出版本号即成功

npx 方式下，本文后续所有 vibecli xxx 命令都等价于 npx @vibeapi/cli@latest xxx，功能完全一致。

macOS / Linux 提示权限不足（EACCES）时：在命令前加 sudo，或参考 npm 官方的全局目录方案。Windows 下如提示权限问题，vibecli 安装工具时会自动尝试 --force 并给出逐步指引。

npmjs.com 连不上时：先执行 npm config set registry https://registry.npmmirror.com 切国内镜像再安装（包在镜像同步发布）。

03 · 首次配置向导

直接输入 vibecli，首次运行会自动进入初始化向导（之后任何时候都可以用 vibecli init 重新走一遍）。向导里全程用 ↑↓ 方向键选择、回车确认。

省时路径：一条命令直配（无需进向导）

不想走交互向导，或者要给两个工具配不同分组的令牌，用 vibecli setup 一条命令完成；重复执行即换令牌。

一把 Key · 按能力自动分配真实输出
vibecli setup --key sk-您的密钥 正在验证 --key 的 API Key... √ Claude Code 配置完成（运行 `claude` 即可使用） √ Codex 配置完成（运行 `codex` 即可使用） 完成: 已配置 2 个工具。终端输入 claude / codex 即可开始编码！ # 自动探测这把 Key 能访问哪些模型：只开通了 Claude 分组就只配 # Claude Code、只开通 GPT 分组就只配 Codex，并说明跳过原因
双令牌 · 两个工具各配各的真实输出
vibecli setup --claudekey sk-Claude分组令牌 --codexkey sk-GPT分组令牌 正在验证 --claudekey 的 API Key... √ Claude Code 配置完成（运行 `claude` 即可使用） 正在验证 --codexkey 的 API Key... √ Codex 配置完成（运行 `codex` 即可使用） 完成: 已配置 2 个工具。终端输入 claude / codex 即可开始编码！ # 两把令牌各自校验 + 能力核对（给 --codexkey 传不含 GPT 分组的 # 令牌会被拒绝），加密存为该工具的专属 Key，互不影响

只配一个工具：单独给 --claudekey / --codexkey / --grokkey（0.0.44+，配 Grok Build）/ --desktopkey（0.0.46+，配 Claude Desktop 桌面端）即可；工具专属 Key 与默认 Key 一样走 AES-256-GCM 加密存储，vibecli status 可查看各自指纹。需要交互式体验（选模型等）再走下面的向导。

01
运行 vibecli · 语言自动适配

中文系统会自动以中文界面进入，不需要选语言；只有非中文系统才会弹出语言选择菜单。

vibecli · 首次运行（中文系统）真实输出
vibecli 检测到首次运行,启动初始化向导... ╔═══════════════════════════════════════════════════════════════╗ ║ ▄▀▄ █▀▄ █ █▄█ ██▀ █ █▀▄ ██▀ █▀▄ ║ ║ █▀█ █▀ █ █ █ █▄▄ █▄▄ █▀ █▄▄ █▀▄ ║ ║ API Helper v0.0.29 ║ ║ 统一管理您的 Claude Code 等编码工具 ║ ╚═══════════════════════════════════════════════════════════════╝ 欢迎使用编码工具助手! 我们重视您的隐私,所有配置信息仅保存在本地. 检测到系统语言为中文，已自动使用中文界面（主菜单或 vibecli lang set 可随时切换）。 （直接进入下一步：输入 API Key）
02
粘贴 API Key · 自动校验

把第 01 章复制的 sk-xxx 粘贴进来（输入时隐藏显示）。vibecli 会立即联网校验这把 Key 是否有效，校验不通过不会进入下一步，杜绝配完才发现 Key 错了：

vibecli · API Key 校验真实输出
? 请在这里输入您的 API key, 回车键确认: **************** - 正在验证 API Key... √ API Key 验证通过
03
选择要配置的工具 · 未安装可代装
vibecli · 选择工具界面示意
? ✨ 请选择要配置的编码工具 ❯ Claude Code Codex OpenClaw Hermes AtomCode Grok Build Claude Desktop

如果选的工具本机还没装，vibecli 会代为执行安装（以 Codex 为例）：

vibecli · 代装工具真实输出
? 是否现在安装? (Y/n) Y $ npm install -g @openai/codex added 2 packages in 6s √ 工具安装成功
04
选择模型 · 写入完成

模型菜单四条路径任选：使用默认（推荐）、实时从 API 拉取可用模型列表、 内置预设、手动输入模型名：

vibecli · 选择模型（Claude Code）界面示意
? ✨ 选择 Claude Code 使用的模型 ❯ 使用默认模型 (Claude 官方组合) # 推荐：Haiku 4.5 / Sonnet 5·1M / Opus 4.8·1M 实时从 API 获取模型... 自定义输入模型名 提示：在 Claude Code 里也可以随时用 /model 命令切换模型
vibecli · 选择模型（Codex）界面示意
? ✨ 选择 Codex 使用的模型 ❯ 使用默认模型 (gpt-5.6-sol) 实时从 API 获取模型... ── 其他模型 ── GPT-5.5 / GLM-5.2 / MiniMax-M3 / Kimi-K2.6 / Qwen3.7-Max / DeepSeek-V4-Pro 自定义输入模型名

确认后配置立即写入，向导结尾直接告知启动命令：

vibecli · 写入成功真实输出
√ 配置已应用，现在就能用 Claude Code 写代码了。 ✅ 现在运行 `claude` 就能用上你的配置了
vibecli · 写入成功真实输出
√ 配置已应用，现在就能用 Codex 写代码了。 ✅ 现在运行 `codex` 就能用上你的配置了

写入前自动备份：vibecli 覆盖任何工具配置之前都会先快照原文件，随时可用 vibecli config <tool> restore 回退（第 09 章）。

04 · 写入了什么（可审计）

vibecli 写入的内容完全透明，您可以随时打开文件核对。两个工具的配置各写各的文件、互不影响。

Claude Code 写 ~/.claude/settings.json：密钥、接入地址和一套调校好的 Claude 官方模型组合（Sonnet 与 Opus 均为 1M 上下文变体）：

~/.claude/settings.json（写入后）真实输出
{ "model": "opus[1m]", "env": { "API_TIMEOUT_MS": "3000000", "ANTHROPIC_AUTH_TOKEN": "sk-****…您的密钥…****", "ANTHROPIC_BASE_URL": "https://www.vibeapi.cn", "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5-20251001", "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5[1m]", "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-8[1m]", "ANTHROPIC_MODEL": "claude-opus-4-8[1m]" } } # 另有少量体验优化项（如关闭非必要流量）随模板一并写入； # 顶层 "model": "opus[1m]" 表示默认用 Opus 档 + 1M 上下文，可在 Claude Code 里随时 /model 切换

Codex 写 ~/.codex/config.toml（供应商 + 模型）和 ~/.codex/auth.json（密钥）：

~/.codex/config.toml（写入后）真实输出
model = "gpt-5.6-sol" model_provider = "custom" model_reasoning_effort = "xhigh" [model_providers.custom] name = "custom" wire_api = "responses" requires_openai_auth = true base_url = "https://www.vibeapi.cn/v1"

幂等合并：两个文件里您自己添加过的其他配置（别的供应商、个人偏好项）都会原样保留，vibecli 只增改与 VibeAPI 接入相关的字段；「移除配置」时也只删这些字段。

05 · 启动使用（实测验证）

配置写入后无需任何额外操作，直接启动工具。以下是我们用刚写好的配置做的真实端到端验证：

codex · 端到端验证真实输出
codex exec "只回复两个字母：OK" user 只回复两个字母：OK codex OK tokens used 1,983
claude · 端到端验证真实输出
claude -p "只回复两个字母：OK" OK

日常使用就是 claude / codex 两条命令；退出 vibecli 菜单时，它也会按您实际配好的工具给出提示： 「再见! 终端输入 claude / codex 即可开始编码！也可以在 VSCode 安装 Claude 插件使用 Claude Code。」

06 · 状态巡检：status / doctor / bench

vibecli status 一屏看全当前 Key（只显示指纹，不显示明文）、接入点、模型与各工具状态：

vibecli status真实输出
vibecli status 当前状态 API Key: sk-fp-221cc8f671f1 # Key 指纹，非明文 API 地址: https://www.vibeapi.cn (default) 语言: zh_CN Profile: default (default, work) 模型: Haiku: claude-haiku-4-5-20251001 Sonnet: claude-sonnet-5[1m] Opus: claude-opus-4-8[1m] Reasoning: claude-opus-4-8[1m] 工具: ✓ Claude Code (已应用配置) ✓ Codex ✗ OpenClaw ✗ Hermes ✗ AtomCode ✗ Grok Build ✗ Claude Desktop

怀疑哪里不对时先跑 vibecli doctor，它会检查 PATH、Key 有效性与网络、工具安装情况：

vibecli doctor真实输出
vibecli doctor - 正在进行健康检查... 健康检查结果: ✓ PATH: PASS ✓ API Key & Network: PASS ✓ Installed Tools: PASS Claude Code 所有检查通过!

想量化接入点的响应速度，用 vibecli bench：

vibecli bench真实输出
vibecli bench --samples 2 正在执行基准测试... 基准测试结果 样本: 2 中位数: 1577ms 平均值: 1577ms 最小值: 1516ms 最大值: 1637ms 错误: 0

07 · 更换模型

三条路径，按习惯任选：

  • 向导里改：vibecli config codex 进入该工具菜单 → 应用配置 → 重新选模型；
  • 命令行直改：vibecli config tool-model set 给单个工具指定模型；
  • Claude Code 内切换：会话中随时用 /model 命令，无需动配置。
换模型 = 设置 + 重新应用（两步一起复制执行，以 Codex 为例）真实输出
vibecli config tool-model set codex gpt-5.6-terra 已设置 codex 的 opus 模型为 gpt-5.6-terra vibecli config codex --non-interactive Codex 配置已加载 # 重新应用后新模型才写进 Codex
查看 / 撤销覆盖（按需单条执行）真实输出
vibecli config tool-model list 按工具的模型覆盖 codex opus=gpt-5.6-terra vibecli config tool-model clear codex # 清除覆盖回到默认 gpt-5.6-sol；同样需要再执行一次上面的 # vibecli config codex --non-interactive 才会写回 Codex

Claude Code 换模型最省事的方式：会话里直接输入 /model 随时切换档位，不用动任何配置；要持久指定也可以 vibecli config tool-model set claude-code opus <模型ID> 后重新应用。

默认模型一览：Claude Code = Claude 官方组合（Haiku 4.5 / Sonnet 5 · 1M / Opus 4.8 · 1M，ANTHROPIC_MODEL 跟随 Opus）；Codex = gpt-5.6-sol（GPT-5.6 系列 Sol / Terra / Luna 怎么选，见这篇指南）；Grok Build = grok-4.6（Responses 协议，见Grok Build 配置）；Claude Desktop = 该 Key 可用的全部 Claude 模型（默认 Opus 4.8，见桌面端配置）；OpenClaw / Hermes / AtomCode = gpt-5.5。

注意：tool-model set 只是记下映射，要再执行一次 vibecli config <tool>（或加 --non-interactive 直接应用）才会写进工具配置。

08 · 多 Profile：工作 / 个人隔离

需要在两把 Key（比如公司项目与个人项目）之间切换时，不必反复重录——每个 Profile 独立保存自己的 Key、接入点与模型配置：

vibecli config profile真实输出
vibecli config profile create work Profile 已创建: work vibecli config profile use work 当前 Profile: work vibecli config profile list Profile 列表 ○ default ● work (当前)

切到新 Profile 后，用 vibecli auth <token> 给它录一把自己的 Key，再对需要的工具执行一次 vibecli config <tool> 应用即可。切回 default 同理。

09 · 备份与还原：任何改动都可撤销

vibecli 每次写工具配置前都会自动快照原文件（每个文件保留最近 10 份）。想回到上一次改动之前：

vibecli config codex restore真实输出
vibecli config codex restore ? 确认还原 Codex 到最近一次更改之前吗? Yes Codex 配置已还原 ~/.codex/config.toml ← config.toml.bak-2026-07-14T11-35-28-900Z ~/.codex/auth.json ← auth.json.bak-2026-07-14T11-35-28-902Z
vibecli config claude-code restore命令示意
vibecli config claude-code restore ? 确认还原 Claude Code 到最近一次更改之前吗? Yes Claude Code 配置已还原 ~/.claude/settings.json ← settings.json.bak-… ~/.claude.json ← .claude.json.bak-…
  • vibecli config <tool> backups —— 列出该工具每个文件现有的快照；
  • 还原前会把「当前状态」也先快照一份，因此还原本身可以再撤销，不存在误操作回不来的情况；
  • 另有 vibecli config backup create <名称> 可对 vibecli 自身配置做命名备份。

10 · 更换 / 撤销 API Key

Key 轮换（例如旧令牌到期）只需一条命令，校验通过即替换，各工具重新应用一次配置即可：

vibecli auth真实输出
vibecli auth sk-新的密钥**************** - 正在验证 API Key... √ API密钥已保存

换完 Key 后，对在用的工具重新应用一次：

重新应用到 Claude Code真实输出
vibecli config claude-code --non-interactive Claude Code 配置已加载
重新应用到 Codex真实输出
vibecli config codex --non-interactive Codex 配置已加载

彻底删除本机保存的 Key（例如设备交接前）：

vibecli auth revoke真实输出
vibecli auth revoke ? 确认要删除已保存的API密钥吗? Yes API密钥已删除 # 同时清掉加密存储与配置文件里的记录

11 · 环境变量自动清理

不少用户此前按其他教程在 shell 里手动 export 过 ANTHROPIC_BASE_URL / ANTHROPIC_API_KEY。这两个环境变量的优先级 高于配置文件——只要还留在环境里，Claude Code 就会优先用旧地址与旧 Key，出现「配置明明写进去了，工具却还连着旧接入点」的现象。这是配置不生效的头号原因（该问题只影响 Claude Code，Codex 不读这两个变量）。

vibecli 每次启动都会自动检测这两个变量，一旦发现立即处理并明确提示，绝不静默：

vibecli · 启动时检测到残留变量真实输出
vibecli status （随后正常显示状态页……）

清理是「外科手术式」的——只删目标行，您 shell 配置里的其他内容一概不动。真实对比：

~/.bashrc · 清理前 → 清理后真实输出
# 清理前： alias ll="ls -la" export PATH="$PATH:/opt/bin" # 清理后： alias ll="ls -la" export PATH="$PATH:/opt/bin" # 只删了两行 export 与标记注释，其余原样保留

清理后请重开一个终端窗口：shell 配置文件的改动只对新终端生效，旧终端里已加载的变量要重开才会彻底消失。

如果您曾在非默认位置（自定义脚本等）设置过这两个变量，请自行检查对应文件。

12 · 检查更新与卸载

检查新版本：

vibecli update真实输出
vibecli update 正在检查更新... 当前版本: 0.0.29 最新版本: 0.0.29 您已是最新版本 # 有新版时执行：npm update -g @vibeapi/cli

完整卸载的推荐顺序（先还工具一个干净配置，再卸 vibecli 本体）：

卸载流程命令示意
vibecli config claude-code # 菜单里选「移除配置」，从工具中删掉 VibeAPI 接入字段 vibecli config codex # 同上 vibecli auth revoke # 删除本机保存的密钥 npm uninstall -g @vibeapi/cli # 装的是 @vibeapi/api-helper 就卸它，二者等价 # 可选：rm -rf ~/.vibecli # 删除残留的配置/备份目录（含全部快照，删前想清楚）

13 · 常见问题

配置写入成功，但工具里模型 / 接入点还是旧的？

先完全退出工具再重新打开（配置只在启动时读取，最小化不算退出）；若仍不对，重开一个终端窗口——多半是残留环境变量在起作用，vibecli 启动时已自动清理（第 11 章），新终端即可生效。

settings.json 里那四个模型变量是什么意思？

ANTHROPIC_DEFAULT_HAIKU/SONNET/OPUS_MODEL 分别指定 Claude Code 三个档位实际调用的模型（默认 Haiku 4.5 / Sonnet 5 · 1M / Opus 4.8 · 1M），ANTHROPIC_MODEL 是当前会话默认档（跟随 Opus）。在向导里自定义模型或重新应用配置时，这四项会整体刷新，不会残留旧值。

想撤销 vibecli 的改动、回到工具原来的配置？

运行 vibecli config <tool> restore（第 09 章）。还原前会再做一次快照，因此还原本身也可以撤销，不必担心误操作。

API Key 存在哪里，安全吗？

Key 经 AES-256-GCM 加密后存放在本机 ~/.vibecli/secrets.enc，加密与当前用户名和主机名绑定，配置文件里不出现明文；vibecli status 也只显示指纹。所有数据仅保存在本地。

Claude Code 和 Codex 想用两把不同分组的令牌？

一条命令：vibecli setup --claudekey sk-Claude分组 --codexkey sk-GPT分组。两把令牌各自校验、加密存为对应工具的专属 Key，应用配置时专属 Key 优先于默认 Key；vibecli status 能看到每个工具各自的 Key 指纹。换令牌重复执行同一命令即可。

同时给 Claude Code 和 Codex 配置，要跑两遍向导吗？

Key 只录一次。之后 vibecli config claude-code 与 vibecli config codex 各执行一次即可，两个工具共用同一把 Key、模型互不影响。脚本化场景可加 --non-interactive 直接应用。

OpenCode 去哪了？

OpenCode 已暂时下架，不再出现在向导与菜单里；此前配置过的用户不受影响，vibecli config opencode 按名称调用仍然可用。

公司内网 / 自建网关，接入地址不是 vibeapi.cn 怎么办？

所有命令支持 --base 旗标临时指定接入点，例如 vibecli --base "https://您的网关地址" init。

在 CI / 自动化脚本里能用吗？

可以。全部命令支持 --non-interactive（禁用交互）、--yes（自动确认）、--json（机器可读输出）、--dry-run（只预览不落盘），例如 vibecli auth $TOKEN --non-interactive + vibecli config codex --non-interactive 即可无人值守完成配置。

14 · 命令速查表

命令作用
vibecli交互式主菜单（首次运行自动进入初始化向导）
vibecli init重新运行首次设置向导
vibecli setup --key sk-xxx一条命令直配：按 Key 能力自动选择工具（重复执行即换令牌）
vibecli setup --claudekey sk-a --codexkey sk-b双令牌各配各的，加密存为工具专属 Key（可只给其一）
vibecli status当前配置总览（Key 指纹 / 接入点 / 模型 / 工具状态）
vibecli doctor健康巡检：PATH、Key 有效性与网络、工具安装
vibecli bench --samples N实测接入点响应延迟
vibecli auth <token>录入 / 更换 API Key（自动校验）
vibecli auth revoke删除本机保存的 Key
vibecli config <tool>配置指定工具（应用 / 移除 / 还原菜单）
vibecli config <tool> restore还原该工具到上次更改之前
vibecli config <tool> backups列出该工具的配置快照
vibecli config tool-model set/list/clear按工具指定 / 查看 / 清除模型覆盖
vibecli config profile create/use/list多 Profile 管理
vibecli lang set zh_CN|en_US切换界面语言
vibecli update检查 npm 上的新版本
vibecli logs list|tail|path查看 vibecli 自身日志（排障用）
vibecli completion bash|zsh|fish生成 shell 补全脚本
全局旗标--base <url> / --non-interactive / --yes / --json / --dry-run / --no-color
vibecli 官方配置助手使用教程 · 全流程实测 · 2026-07-14