CLI 配置教程

大约 4 分钟

CLI 配置教程

本章节是“手动配置路线”的完整说明。它不是简单目录，而是用来帮你判断该配什么、先看什么、出错后从哪里开始查。

如果你已经能在网页里完成注册、创建令牌，但还没有把 Claude Code、Codex 或 Gemini 稳定接入本地环境，这一章就是你的主入口。

这章适合谁

你不使用 CC-Switch，想直接维护本地配置文件
你需要明确每个配置项写在哪个文件
你要做多设备同步或团队标准化
你已经配过一次，但换电脑、换账号或换令牌后想重新走一遍稳妥流程
你能启动 CLI，但调用时报错，想先排除环境和配置问题

与快速开始的关系

快速开始讲的是最短路径：/docs/register/5-cli.html
本章节讲的是完整细节：环境检查、配置命令、验证与排障

如果你只想“先跑通一次”，先看快速开始；如果你想“换机器还能复现、出了问题能自己查”，请继续看本章节。

建议怎么读

你不需要把所有页面从头到尾读完，按自己的目标选路径即可。

路线 A：第一次接入

先看环境检查，确认命令、终端、网络和系统前置条件。
再进入你实际使用的工具页，按文档完成配置。
配好后立刻执行一次最小验证，确认不是“看起来写好了，实际没生效”。
如果验证失败，再回到对应 FAQ 按症状排查。

路线 B：已经能用，但想长期稳定

先检查当前机器的旧配置、环境变量和历史令牌是否互相覆盖。
按工具页梳理配置文件位置，统一命名和保存方式。
把验证命令固定下来，后续换令牌、换模型、换电脑时都先跑这一组检查。
有团队协作需求时，再补充多设备同步和标准化约定。

推荐阅读顺序

环境检查（必须先做）
按你使用的工具进入专页
配置后马上执行验证命令
出问题直接看对应 FAQ

常见使用场景

你的场景	建议先看
新电脑首次配置 CLI	环境检查
Claude Code 接不通或不认令牌	Claude Code 教程
Codex 已安装，但请求认证失败或模型报错	Codex 教程
Gemini CLI 需要手动指定配置文件或环境变量	Gemini 教程
不确定是环境问题还是令牌问题	先看环境检查，再去常见问题
已经配过一次，现在要迁移到另一台机器	先按本章重走，再补看对应 FAQ

配置前先确认这 5 件事

你手里的令牌分组和目标工具是匹配的。
你知道当前工具优先读取环境变量、配置文件还是两者同时生效。
旧机器或旧 shell 中没有残留过期的 API Key、Base URL 或代理配置。
你能在终端里确认 CLI 本体已安装且版本可输出。
你已经准备好一条最小验证命令，配置完成后立即测试。

排障建议

不要一上来就怀疑平台故障，先排掉本地旧配置覆盖。
不要手输模型名，优先通过接口查询或从文档示例复制，减少拼写错误。
每次改完配置后都重新开一个终端窗口，避免当前 shell 继续使用旧环境变量。
如果同一令牌在一台机器可用、另一台不可用，优先排查本地环境，而不是重新创建令牌。
如果你连“命令能不能调用”都不确定，先不要看 FAQ 细节，先回到环境检查。

目标结果

完成本章节后，你应当能做到：

独立完成 CLI 的文件级配置
快速判断错误属于“令牌问题”还是“环境问题”
在新电脑 10 分钟内恢复可用环境
知道遇到报错时应该回看哪一页，而不是在多个工具文档之间来回试错