前言

Claude Code、Codex CLI 等命令行 AI 编程工具均依赖 Node.js（要求 18 及以上）和 Git。本文介绍 Windows / Mac / Linux 三系统的安装方法

安装方法

Windows

Node.js：访问 Node.js 官网 下载 LTS 版本的 .msi 安装包，双击运行，按向导默认设置完成

Git：访问 Git 官网，下载安装包

双击运行，按向导默认设置完成即可

Mac

推荐使用 Homebrew 一键安装，若未安装 Homebrew 先运行

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

然后一条命令同时安装 Node 和 Git

brew install node git

也可访问 Node.js 官网 下载 .pkg 安装包。macOS 通常已自带 Git，首次执行 git --version 若弹窗提示安装"命令行开发者工具"，点击安装即可

Linux

Node.js 推荐 nvm 安装（便于多版本切换，且部分发行版自带源 Node 版本过低）

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install --lts

Git 使用各发行版包管理器安装

# Ubuntu / Debian
sudo apt install -y git

# CentOS / RHEL / Fedora
sudo dnf install -y git

# Arch Linux
sudo pacman -S git

验证安装

三系统通用，在终端执行

node -v
npm -v
git --version

三条命令均显示版本号即为成功

前言

Codex CLI 是 OpenAI 官方的命令行 AI 编程工具。本文介绍 Windows / Mac / Linux 三系统的统一配置流程

前置 Node.js 与 Git 环境的安装请参考 《Node.js 与 Git 环境配置教程》，cc-switch 配置详见 《cc-switch 配置教程》

安装 Codex CLI

安装方法

三系统使用同一条 npm 命令

npm install -g @openai/codex

验证

codex --version

输出版本号即为安装成功

常见问题

Q：permission denied / EACCES 错误（Mac / Linux）

不要使用 sudo，把 npm 全局目录改到用户目录

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc   # zsh 用户改为 ~/.zshrc
source ~/.bashrc

Q：permission denied 错误（Windows）

以管理员身份运行 PowerShell

npm config set prefix "$env:APPDATA\npm"
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Q：command not found: codex

npm 全局 bin 目录未加入 PATH，执行 npm config get prefix 查看路径，将对应的 /bin 目录追加到系统 PATH

配置 API

cc-switch（推荐）

cc-switch 同时支持 Claude Code 和 Codex，无需手动编辑配置文件，可在多渠道间一键切换

详细安装与使用见 《cc-switch 配置教程》

注意：Codex 的 Base URL 必须带 /v1 后缀（与 Claude Code 不同）

手动编辑配置文件

Codex 不使用环境变量，而是读取两个配置文件：

编辑 config.toml

若文件不存在，先创建 .codex 目录再新建文件。Windows 在 %USERPROFILE%，Mac/Linux 直接 mkdir -p ~/.codex

model_provider = "custom"
model = "gpt-5.4"
model_reasoning_effort = "high"
disable_response_storage = true

[model_providers.custom]
name = "custom"
base_url = "https://你的请求地址/v1"
wire_api = "responses"
requires_openai_auth = true
model_context_window = 1000000
model_auto_compact_token_limit = 900000

编辑 auth.json

{
  "OPENAI_API_KEY": "sk-xxx"
}

保存后重启终端，codex 启动时会自动读取上述配置

配置参数速查

开始使用

在任意项目目录打开终端，输入 codex 启动

cd 你的项目目录
codex

看到输入框出现提示符后，直接用中文或英文描述需求即可，例如

帮我用 Python 实现一个二叉搜索树，包含插入、删除、查找方法

前言

汇总 Claude Code、Codex CLI、OpenClaw、外接配置及相关工具使用过程中的高频问题与报错处理方案，覆盖安装、认证、网络、请求错误、权限、缓存计费、插件、外接兼容、Codex CLI、OpenClaw、等场景

配置教程请参考 《cc-switch 配置教程》、《Node.js 与 Git 环境配置教程》、《Claude Code 配置教程》、《Codex 配置教程》

有问题先看看群里炸没炸，如果没有大面积反馈，就是个人情况了

安装与启动类问题

Q1：首次启动即报 Unable to connect to Anthropic services

现象：Claude Code 安装后第一次执行 claude，终端打印以下错误并退出

Unable to connect to Anthropic services
Failed to connect to api.anthropic.com: ERR_BAD_REQUEST
Please check your internet connection and network settings.

修复：用文本编辑器打开 ~/.claude.json（Windows 为 C:\Users\用户名\.claude.json），在最外层 JSON 对象中添加

"hasCompletedOnboarding": true

完整写法参考

{
  "installMethod": "unknown",
  "autoUpdates": true,
  "firstStartTime": "2025-07-14T06:11:03.877Z",
  "userID": "...",
  "projects": { ... },
  "hasCompletedOnboarding": true
}

注意 projects 字段末尾的 } 后面要加英文逗号 ,，否则 JSON 格式非法。保存后可用以下命令验证格式

cat ~/.claude.json | python3 -m json.tool

无报错即格式正确，重新执行 claude 进入交互界面

Q2：command not found: claude

npm 全局 bin 目录未加入 PATH。执行 npm config get prefix 查看路径，将对应的 /bin 目录追加到系统 PATH

Q3：permission denied / EACCES 错误（Mac / Linux 安装时）

不要使用 sudo，把 npm 全局目录改到用户目录

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc   # zsh 用户改为 ~/.zshrc
source ~/.bashrc

Q4：permission denied 错误（Windows 安装时）

以管理员身份运行 PowerShell

npm config set prefix "$env:APPDATA\npm"
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Q5：旧版 npm 安装的 Claude Code 如何清理？

当前官方推荐使用原生安装脚本，不再推荐 npm 安装。先备份 ~/.claude，再清理旧包

# Mac / Linux
if [ -d ~/.claude ]; then cp -r ~/.claude ~/.claude.backup; fi
npm list -g --depth=0
npm uninstall -g @anthropic-ai/claude-code

# Windows PowerShell
if (Test-Path "$env:USERPROFILE\.claude") { Copy-Item "$env:USERPROFILE\.claude" "$env:USERPROFILE\.claude.backup" -Recurse }
npm list -g --depth=0
npm uninstall -g @anthropic-ai/claude-code

清理后使用原生安装脚本重新安装

# Mac / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

也可使用包管理器：macOS 用 brew install --cask claude-code，Windows 用 winget install Anthropic.ClaudeCode

认证与 API Key 类问题

Q6：401 Invalid API Key / 无效令牌

现象：终端返回 401 invalid x-api-key

原因：ANTHROPIC_BASE_URL 未配置或配置错误，请求打到了官方端点

修复：确认 ~/.claude/settings.json 中正确配置了 Base URL 和 API Key

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://你的请求地址",
    "ANTHROPIC_API_KEY": "sk-***"
  }
}

注意：Claude Code 的 Base URL 不需要 /v1 后缀

Q7：401 无效令牌 — IDE 或 MCP 覆盖了配置

现象：API Key 填写正确，但持续 401。常见于安装了 Cursor、Continue 等 IDE 插件后

原因：IDE 插件或 MCP 服务器覆盖了 settings.json 中的 apiKey / baseURL 字段

修复方案（三选一）：

• 推荐：用 CC Switch 重新配置，一键覆盖被修改的配置
• 手动修复：检查并修正 ~/.claude/settings.json 中被覆盖的字段
• 环境变量：通过系统环境变量设置 API Key 和 Base URL（优先级高于配置文件，不易被覆盖）

预防：安装新 IDE 插件或 MCP 后，重新验证 Claude Code 连通性

Q8：切换服务后 401 无效令牌

现象：曾使用其他中转服务，切换后新配置已填写正确但仍报 401

原因：旧服务遗留了系统环境变量（ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY、ANTHROPIC_API_TOKEN），环境变量优先级高于配置文件

Windows 修复：按 Win + R → 输入 sysdm.cpl → 高级 → 环境变量，在「用户变量」和「系统变量」中分别删除 ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY、ANTHROPIC_API_TOKEN。保存后重新打开终端。如仍报错，删除以下配置文件后用 CC Switch 重新配置

C:\Users\用户名\.claude\claude.json
C:\Users\用户名\.claude\claude.json.backup

Mac / Linux 修复：编辑 ~/.zshrc 或 ~/.bashrc，找到并删除以 export ANTHROPIC_ 开头的旧行，执行 source ~/.zshrc 后重启终端

Q9：OAuth 登录冲突导致 API Key 失效

现象：曾在终端通过 claude 完成官网 OAuth 登录，切换到中转 API 后，配置被忽略，请求直连 api.anthropic.com，在服务器环境（CentOS / Ubuntu）尤为常见

原因：~/.claude.json 中写入了 OAuth 令牌（primaryApiKey / oauthToken），优先级高于 settings.json 中的 API Key

修复步骤

# 第一步：退出 OAuth 登录
claude auth logout

# 第二步：写入中转 API 配置
cat > ~/.claude/settings.json << 'EOF'
{
  "env": {
    "ANTHROPIC_API_KEY": "sk-你的API密钥",
    "ANTHROPIC_BASE_URL": "https://你的请求地址"
  }
}
EOF

# 第三步：验证配置写入成功
cat ~/.claude/settings.json

# 第四步：重新启动
claude

预防：服务器环境初次运行 claude 前先写好 settings.json，避免触发 OAuth 流程

Q10：401 Invalid API Key format — Key 含不可见字符

现象：Key 目视正确但仍报 401 或 Invalid format

原因：从 PDF / 网页 / 截图复制 Key 时混入零宽空格、不换行空格、\r 等不可见字符，或 OCR 将相似字符误读（0/O、1/l/I）

检测方法

echo "$ANTHROPIC_API_KEY" | cat -A
# 正常：行尾只有 $
# 异常：出现 ^M$ 或其他多余字符

修复：从控制台的「复制」按钮重新获取 Key，不要手动输入或经由 PDF / 截图中转。环境变量赋值不加引号

export ANTHROPIC_API_KEY=sk-ant-api03-你的key

Q11：403 Missing API Key / 配置冲突

原因：配置文件被意外修改或多处配置冲突

修复：推荐用 CC Switch 重新写入配置，覆盖被修改的文件

Q12：启动时要求认证 / 弹出登录提示

确保已配置 ANTHROPIC_BASE_URL 和 ANTHROPIC_API_KEY，并重启终端（关闭整个终端窗口重新打开，不是新建标签页）

Q13：环境变量优先级说明

优先级从高到低：系统环境变量 > ~/.claude.json（OAuth 令牌）> ~/.claude/settings.json（CC Switch 写入）

排障时如果修改 settings.json 不生效，优先检查是否存在更高优先级的环境变量或 OAuth 残留

网络与连接类问题

Q14：API Error (Connection error.)

现象：请求未到达服务器即失败，重试无效

原因：本地到服务器链路不通（TCP 连接阶段失败），常见原因为代理节点失效、Wi-Fi 路由异常或防火墙拦截出站请求

排查步骤：

1. 执行 ping 你的请求地址 检查连通性
2. 有回包 → 排查代理配置；超时 → 切换网络（换 Wi-Fi / 关闭代理 / 切换代理节点 / 手机热点）
3. 确认代理软件已开启「系统代理」或「TUN 模式」，Claude Code 作为 CLI 工具不走浏览器代理通道
4. 网络恢复后重新执行 claude

Q15：API Error (Request timed out.)

现象：请求等待一段时间后超时

原因分两种情况：

• 情况 A — 网络延迟：本地到服务器延迟过高，参考 Q14 的网络排查步骤
• 情况 B — 上下文过长：当前会话积累 token 过多，模型处理时间超过超时阈值

情况 B 修复：

• 在 Claude Code 中输入 /clear 清空对话
• 或输入 /compact 压缩上下文保留摘要
• 或退出后重新执行 claude 进入新会话

IDE 用户注意：IDE 插件内置大量系统 Prompt，叠加 Claude Code 自身 Prompt 后，可用的有效对话轮数会明显减少，出现超时优先检查上下文长度

Q16：WebFetch 联网功能失效

现象：调用 WebFetch 工具抓取网页时报错，目标网站手动用浏览器访问完全正常，代理已开启全局模式

原因：Claude Code 在抓取目标页面前会先向 https://claude.ai/api/web/domain_info 发预检请求，国内网络 / 企业防火墙拦截 claude.ai 导致预检失败，WebFetch 整体报错

修复：在 ~/.claude/settings.json（Windows 为 C:\Users\用户名\.claude\settings.json）中添加

"skipWebFetchPreflight": true

若已有其他配置，合并写入

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://你的请求地址",
    "ANTHROPIC_API_KEY": "sk-***"
  },
  "skipWebFetchPreflight": true
}

保存后重启 Claude Code 即可跳过预检直接请求目标页面

请求错误类问题

Q17：请求返回 400，与内容无关

现象：使用 AWS 分组时返回 400，日志含 invalid beta flag，新建对话后依然复现

原因：Claude Code 自动附加实验性 Beta 请求头（anthropic-beta），部分 AWS 分组上游不支持该请求头

修复：先用环境变量确认问题

# Mac / Linux
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
claude

# Windows PowerShell
$env:CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS = "1"
claude

确认有效后写入全局配置文件 ~/.claude/settings.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://你的请求地址",
    "ANTHROPIC_API_KEY": "sk-***",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

保存后彻底关闭终端窗口再重新打开

Q18：API Error 400（非内容原因）

原因：Claude Code 本身 bug 导致请求体格式异常

修复：重发请求或执行 /compact 后通常恢复

Q19：413 请求体过大

现象：API Error: 413 Request Entity Too Large

原因：当前会话上下文 token 过多，请求体超过服务端最大体积限制

修复：执行 /clear（清空对话）或 /compact（压缩上下文保留摘要），或退出后重新打开新会话

预防：长任务中定期执行 /compact

Q20：400 Invalid model name

现象：API Error: 400 Invalid model name，使用 Opus 模型时出现

原因：Opus 并发配额不足，服务端降级拒绝

修复：无需修改配置，稍等片刻后重试即可。不要反复修改配置浪费排查时间

Q21：429 Rate Limit / 额度耗尽

429 有两种子类型，处理方式完全不同：

• rate_limit_error：短时间请求过于频繁，等待后自动恢复
• insufficient_quota：当月额度已耗尽，必须充值或等下月重置

判断方法：前往 https://你的请求地址 查看余额

• 用量未耗尽 → 频率限制，等待或降低并发
• 用量已归零 → 额度耗尽，前往充值

Q22：Overloaded / 500 错误

原因：官方服务过载或故障

修复：访问 status.anthropic.com 确认服务状态，等待恢复即可

Q23：API Error: response exceeded the 32000

原因：单次回复超出默认输出 token 上限

修复：在 ~/.claude/settings.json 的 env 中设置

"CLAUDE_CODE_MAX_OUTPUT_TOKENS": "32000"

Q24：503 model_not_found

原因：所选模型在当前渠道下线或不可用

修复：使用 /model 命令切换到其他可用模型，或联系服务提供方确认模型可用性

Q25：context window 超限，对话被截断

原因：单次会话积累 token 过多，未及时 /compact 或新开会话

修复：及时执行 /compact 压缩上下文，或 /clear 开始新会话

Q26：Command timed out after 2m 0.0s

原因：Claude Code 等待 shell 命令返回超时，与 API 请求无关

修复：手动在终端执行对应命令查看卡在哪里

权限类问题

Q27：Permission denied — 文件读写被拒绝

三种独立原因，需分别判断：

• 原因 A — 系统层权限不足：执行 ls -la /path/to/file 查看权限位，用 chmod 644（文件）或 chmod 755（目录）修复
• 原因 B — Claude Code 权限设置：用户曾选择「总是拒绝」该类操作，按 Cmd+Shift+P（macOS）或 Ctrl+Shift+P（Windows/Linux）搜索 Claude: Manage Permissions，将对应规则改为「询问」或「允许」
• 原因 C — .claudeignore 规则误匹配：执行 cat .claudeignore 检查是否有 glob 规则误匹配到目标文件，删除或精确化有问题的规则

预防：.claudeignore 使用精确路径而非宽泛通配符，定期检查 Permission 设置中的「总是拒绝」规则，项目目录权限保持 644（文件）/ 755（目录）

Q28：skipAutoPermissionPrompt 导致 Plan 模式失效

现象：在 settings.json 中加入 "skipAutoPermissionPrompt": true 后 Plan 模式无法执行，移除该字段后恢复

修复：打开 ~/.claude/settings.json，删除 skipAutoPermissionPrompt 整行，保存后重启终端

预防：仅添加文档中明确标注用途的配置项，调整权限相关配置后先做一次基础功能验证

Q29：如何理解 Claude Code 的 Permission 机制？

Claude Code 对文件操作、shell 命令执行等动作有权限确认机制。首次触发时会弹出询问，可选择「允许一次」「总是允许」「总是拒绝」。如果误选了「总是拒绝」，后续该类操作会直接被阻断，需要到 Permission 管理界面手动修改

缓存与计费类问题

Q30：重复创建缓存导致单场重复收费

现象：同一场请求过程中出现重复创建缓存，被重复计费。首字时间超过 30 秒可优先怀疑此问题

原因：备用负载切号后二次转发携带相关请求头，导致请求被误路由并重复创建缓存

修复步骤：

1. 确认现象是否匹配：回看请求链路，确认是否存在同一场请求重复创建缓存以及首字时间明显超过 30 秒
2. 取消 ccs 代理，避免请求经过会触发备用负载切号的中间层
3. 如需保留转发链路，逐项检查二次转发时透传的请求头，去掉导致误路由的请求头
4. 重新发起一场独立请求验证

预防：保持请求链路单一稳定，二次转发时只保留必需请求头

Q31：如何启用 1 小时上下文缓存？

适用于支持长缓存的专用分组，在 ~/.claude/settings.json 的 env 中添加

"ENABLE_PROMPT_CACHING_1H": "1"

注意取舍：1 小时缓存的重建成本更高，高频使用场景通常建议保持默认短缓存。只有长链路任务才建议开启

Q32：如何查看当前令牌用量？

在 Claude Code 交互界面输入 /cost 查看当前会话的令牌用量。

claude-mem 插件问题

Q33：知识库无产出，pending_messages 大量堆积

现象：observations 表为 0 条（使用多天没有提取出任何知识点），pending_messages 大量堆积状态全为 pending，sdk_sessions 无任何 completed 记录，worker_port 全为 None

原因：worker 使用的模型通道下线（如 claude-sonnet-4-5 返回 503），SDK 子进程持续崩溃，积压数据被误判为「消息队列垃圾」后一键清空，导致知识原材料永久丢失

修复步骤：

1. 确认管道状态（清理前必查）：observations 为 0 说明管道坏了，不是「该清理了」的信号；pending 全堆积是异常信号，先查 worker 状态而非删除
2. 修改模型配置：编辑 ~/.claude-mem/settings.json，将模型改为当前可用的稳定版本

{
  "CLAUDE_MEM_MODEL": "claude-haiku-4-5-20251001"
}

3. 重启 worker：删除旧 PID 文件 rm ~/.claude-mem/worker.pid，下次 hook 触发自动用新配置重启
4. 安全清理：只删已完成/已失败的消息，绝不删除 pending 状态的消息

# Python 安全清理示例
cur.execute("DELETE FROM pending_messages WHERE status IN ('completed', 'failed')")
conn.commit()

表结构速查：

• pending_messages：知识提取输入队列（原材料），别当垃圾删
• observations：提取出的知识点（输出），为 0 说明管道坏了
• sdk_sessions：子进程会话状态，worker_port 全 None 即异常

Windows 上运行 Python 记得加 sys.stdout.reconfigure(encoding='utf-8')，否则中文报 GBK 错误

Q34：Claude Code 命令卡死不返回 — Worker 假死

现象：输入命令后终端不报错但长时间无返回，Claude Code 响应越来越慢。curl http://127.0.0.1:37777/api/health TCP 可连但 HTTP 永不返回，端口在监听但对应 PID 进程已不存在

原因：升级 claude-mem 后旧 worker 挂死，端口 37777 残留占用但进程已死，新 worker 启动误判「端口被占」反复失败，hook 每次工具调用都尝试连接超时拖慢整个 CLI

检测方法

curl -m 8 -sv http://127.0.0.1:37777/api/health
# TCP 能连但 HTTP 不返回 = 假活

修复步骤：

1. 清理残留进程和端口

# PowerShell 查看占用端口的 PID
Get-NetTCPConnection -LocalPort 37777 | Select-Object OwningProcess
# 结束进程
Stop-Process -Id <PID> -Force

如果 Stop-Process 提示进程不存在，直接在任务管理器结束所有 node.exe 和 python.exe 残留进程

2. 进正确目录重启 worker

# 正确：marketplaces 目录
cd ~/.claude/plugins/marketplaces/thedotmack
npm run worker:status
npm run worker:restart

# 错误：不要进 cache/ 目录，那里没有 worker 脚本

3. 验证修复

curl -m 5 -sv http://127.0.0.1:37777/api/health
# 正常返回：{"status":"ok","initialized":true,"mcpReady":true}

两个目录区分：

• ~/.claude/plugins/marketplaces/thedotmack：插件主目录，有 worker 脚本
• ~/.claude/plugins/cache/thedotmack/claude-mem/版本号/：运行时依赖缓存，没有 worker 脚本

预防：Claude Code 变慢先查 worker，不要先怀疑 API 或模型；升级 claude-mem 后主动验证 health 接口

外接与兼容类问题

Q35：外接调用返回 403 block / 403 Forbidden

按顺序排查：

1. 确认令牌分组是否匹配当前模型类型
2. 确认 Base URL 是否带错 /v1（Claude 类不带，Codex 需要带）
3. 确认请求头中 User-Agent 是否缺失或填成了别的模型类型（不能把 Claude 的 UA 复用到 Codex）
4. 确认客户端是否真正将 Header 发出去了（部分客户端 UI 填了但实际没传）
5. 确认 Authorization 仍是 Bearer sk-*** 格式

Q36：User-Agent 怎么填？各场景示例

Claude 外接

"User-Agent": "claude-cli/2.0.76 (external, cli)"

Codex 外接

"User-Agent": "codex_cli_rs/0.77.0 (Windows 10.0.26100; x86_64) WindowsTerminal"

国产模型外接（使用浏览器型 UA）

"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:149.0) Gecko/20100101 Firefox/149.0"

Q37：Base URL 到底要不要加 /v1？

• Claude 类接入（Anthropic Messages 协议）：https://你的请求地址（不带 /v1）
• Codex 类接入（OpenAI Responses 协议）：https://你的请求地址/v1（带 /v1）

最常见错误就是把 Claude 的地址误写成带 /v1，或把 Codex 的地址误写成不带 /v1

Q38：外接前需要确认哪 5 项？

开始配置前必须对应好以下 5 项，任何一项对不上都可能导致 403 / 401 / 模型不可用

• 分组：Key 属于哪个模型哪个分组
• 协议：客户端走 Anthropic Messages 还是 OpenAI Responses
• Base URL：Claude 类不带 /v1，Codex  类带 /v1
• 请求头：外接场景需要补对应 User-Agent
• 模型：有些分组允许留空，有些必须填写准确模型 ID

Q39：JetBrains IDE 里能看到插件，但调用报 401

优先检查：

1. IDE 是否读取到了旧的本地认证状态（OAuth 残留）
2. Key 是否已切到正确分组
3. 插件是否覆盖了本机 settings.json 配置

推荐做法：先用 CC Switch 在本机配好 Claude Code 或 Codex，确认 CLI 可用后，再在 IDE 中复用本机已有环境

Q40：JetBrains / Trae 本机 CLI 可用但 IDE 不可用

问题不在 Key，在 IDE 侧配置。优先排查 IDE 是否读取了错误配置文件、没有带出请求头、或对本地代理/证书有额外限制

Q41：Trae 中改了 Base URL 还是连不上

优先检查：

1. Claude / Codex 的 Base URL 是否写反（Claude 不带 /v1，Codex 带 /v1）
2. 插件是否允许保存完整自定义地址
3. 当前插件版本是否真的支持外接
4. 如果 Claude 正常 Codex 不正常，大概率是 Codex 的 /v1 没带上，或 model 仍填成了 Claude 模型名

Codex CLI 专项问题

Q42：Codex CLI 的 Base URL 格式是什么？

Codex 的 Base URL 需要 /v1 后缀，与 Claude Code 不同

Claude Code：https://你的请求地址     （不带 /v1）
Codex CLI ：https://你的请求地址/v1  （带 /v1）

Q43：Codex CLI 配置文件在哪？怎么手动配置？

两个配置文件：

• ~/.codex/config.toml（Windows 为 C:\Users\用户名\.codex\config.toml）
• ~/.codex/auth.json（Windows 为 C:\Users\用户名\.codex\auth.json）

config.toml 参考

model_provider = "custom"
model = "gpt-5.4"
model_reasoning_effort = "high"
disable_response_storage = true

[model_providers.custom]
name = "custom"
base_url = "https://你的请求地址/v1"
wire_api = "responses"
requires_openai_auth = true
model_context_window = 1000000
model_auto_compact_token_limit = 900000

auth.json 参考

{
  "OPENAI_API_KEY": "sk-***"
}

Q44：Codex CLI 如何启用 1M 上下文？

在 ~/.codex/config.toml 中确认以下两项

model_context_window = 1000000
model_auto_compact_token_limit = 900000

• model_context_window：可用上下文窗口设为 1,000,000
• model_auto_compact_token_limit：接近上限前提前触发压缩，避免撞满

Q45：Codex CLI 推理速度慢怎么办？

将 config.toml 中的 model_reasoning_effort 从 high 改为 medium 或 low

• low：快，适合简单代码生成、快速问答
• medium：中，日常开发任务（推荐）
• high：慢，适合复杂算法、架构设计

Q46：Codex CLI API Key 无效？

1. 检查 ~/.codex/auth.json 中的 Key 是否正确
2. 确认中转站余额充足、Token 未过期

Q47：同时使用 Claude Code 和 Codex CLI 会冲突吗？

不会。两者配置文件独立，互不冲突。使用 CC Switch 可统一管理

• Claude Code → ~/.claude/settings.json
• Codex CLI → ~/.codex/config.toml + ~/.codex/auth.json

OpenClaw 专项问题

Q48：OpenClaw 是什么？怎么安装？

OpenClaw Gateway 是 AI 代理网关，支持通过飞书、Telegram、Discord 等渠道接入 AI 模型。启动后默认 Web UI 地址 http://127.0.0.1:18789/

# 安装
npm install -g openclaw@latest

# 初始化引导
openclaw onboard --install-daemon

引导过程中选择 QuickStart → 跳过供应商选择 → 选择全模型 → 保持默认模型 → 选择通知渠道（飞书/TG/Discord）→ 配置 Skills 和 Hooks（推荐勾选 session-memory）

Q49：OpenClaw 配置 provider 时报 403 block

OpenClaw 作为外接客户端，不同 provider 必须分别配置对应的分组和 User-Agent

Claude provider

API 端点：https://你的请求地址
API 协议：Anthropic Messages
Headers：
  "Authorization": "Bearer sk-***"
  "User-Agent": "claude-cli/2.0.76 (external, cli)"

Codex provider

API 端点：https://你的请求地址/v1
API 协议：OpenAI Responses
Headers：
  "Authorization": "Bearer sk-***"
  "User-Agent": "codex_cli_rs/0.77.0 (Windows 10.0.26100; x86_64) WindowsTerminal"

国产模型 provider

Headers：
  "Authorization": "Bearer sk-***"
  "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:149.0) Gecko/20100101 Firefox/149.0"

关键提醒：不能把 Claude 的 UA 直接复用到 Codex provider，国产模型 provider 也不建议省略浏览器型 UA

Q50：OpenClaw 同一实例能同时接多种模型吗？

可以。同一个 OpenClaw 可以同时接 Claude 和 Codex，也可以接国产模型。但不同 provider 要分别选择对应分组，分别填写对应 User-Agent，不能混用

Q51：OpenClaw 飞书渠道配置要点

1. 前往 open.feishu.cn 创建企业自建应用，添加机器人能力
2. 在权限管理中筛选 im，全选相关权限
3. 创建版本并发布，记录 App ID 和 App Secret
4. 将 App ID 和 App Secret 填入 OpenClaw 引导界面，或通过命令行写入

openclaw config set -- channels.feishu.appId "你的AppID"
openclaw config set -- channels.feishu.appSecret "你的AppSecret"

5. 在飞书开放平台进入事件配置页面，添加「接收消息」事件
6. 重新创建一个版本并发布（否则订阅事件不生效）
7. 在飞书工作台找到机器人发送消息，获取配对码后执行

openclaw pairing approve feishu 你的配对码

注意：配置飞书订阅事件时 OpenClaw 必须处于运行状态，可通过 openclaw gateway 手动启动

Q52：OpenClaw 群组消息响应策略怎么选？

• 所有消息均回复：适合私人测试群
• 仅 @ 机器人时回复：适合多人工作群（推荐）
• 不在群组中回复：仅支持私聊

CC Switch 与配置管理

Q53：CC Switch 切换后不生效

1. 重启 Claude Code（关闭整个终端窗口重新打开）
2. 检查系统环境变量是否覆盖了 CC Switch 写入的配置（环境变量优先级高于配置文件）
3. 必要时删除 ~/.claude 目录后重新配置

Q54：如何切回官方渠道并重新 OAuth？

1. 先备份 ~/.claude 与 ~/.claude.json
2. 清理旧会话、历史与认证残留
3. 在 CC Switch 中切换到官方渠道，或直接清空中转配置后执行 claude 登录

进阶配置与效率优化

Q55：如何减少 Token 消耗与非必要流量？

在 ~/.claude/settings.json 中合并写入以下配置

{
  "ENABLE_TOOL_SEARCH": true,
  "skipWebFetchPreflight": true,
  "env": {
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

• ENABLE_TOOL_SEARCH：减少工具调用搜索的 Token 泄漏
• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC：关闭遥测和更新检查等非必要请求
• skipWebFetchPreflight：跳过 WebFetch 预检查（国内网络必加）

Q56：如何使用 CLAUDE.md 提升效率？

在项目根目录创建 CLAUDE.md 文件，写入项目技术栈、目录结构和开发规范，Claude Code 启动时自动加载作为上下文

# 项目名称

## 技术栈
- 前端：React + TypeScript
- 后端：Node.js + Express

## 项目结构
- src/ — 源代码
- tests/ — 测试文件

## 开发规范
- 使用 ESLint + Prettier
- 提交信息遵循 Conventional Commits

提供准确的项目上下文可显著减少 Token 消耗，避免 Claude Code 反复询问项目结构

Q57：MCP 扩展有哪些推荐？

• context7：技术文档实时查询
• deepwiki：知识库访问
• playwright：浏览器自动化
• exa：智能搜索

Q58：Hooks 钩子怎么用？

在 ~/.claude/hooks/ 或项目 .claude/hooks/ 下创建钩子脚本

• before-tool-use：工具调用前触发
• after-tool-use：工具调用后触发
• user-prompt-submit：用户提交消息时触发

Q59：自定义命令怎么创建？

在 ~/.claude/commands/ 或 .claude/commands/ 下创建 .md 文件。例如创建 ~/.claude/commands/review.md，之后在对话中输入 /review 即可触发

Q60：常用命令速查

• /model：切换模型（opus / sonnet / haiku）
• /model sonnet[1m]：切换 1M 超长上下文版本
• /cost：查看当前令牌用量
• /compact：压缩上下文，释放空间
• /resume：恢复历史对话
• /clear：清空当前对话
• /help：查看所有命令
• /exit 或连按两次 Ctrl + C：退出

Q61：排障前建议先检查什么？（通用排障清单）

1. 确认令牌分组、Base URL、User-Agent 三项是否匹配（参考 Q38）
2. 检查系统环境变量是否残留旧配置（Win + R → sysdm.cpl，或查看 ~/.zshrc）
3. 检查 ~/.claude.json 是否有 OAuth 令牌残留（claude auth logout 清除）
4. 用 CC Switch 重新写入一次配置，关闭终端窗口重新打开后再试
5. 如涉及外接场景，确认 5 项检查清单（分组、协议、Base URL、请求头、模型）

前言

开源工具，可方便地管理 API key、MCP、Skills，无需手动配置环境变量，并支持多渠道一键切换

下载地址：https://github.com/farion1231/cc-switch/releases

下载与安装

在 Release 页根据系统选择对应的安装包

Windows

下载 .exe 安装包，双击运行，按向导完成安装

Mac

下载 CC-Switch-vX.X.X-macOS.dmg（universal 通用包，Apple Silicon 和 Intel 均可使用），双击挂载后将图标拖入 Applications

如需免安装版可下载 macOS.tar.gz，解压后即可运行

首次打开若提示"无法验证开发者"，前往 系统设置 → 隐私与安全性，点击"仍要打开"

Linux

Linux 提供三种格式，每种都有 arm64 和 x86_64 两个架构（按你的 CPU 选择对应版本）

• .AppImage：通用免安装，所有发行版均可使用
• .deb：Ubuntu / Debian / Deepin 等
• .rpm：CentOS / RHEL / Fedora / openSUSE 等

AppImage（通用，免安装）

chmod +x CC-Switch-*-Linux-*.AppImage
./CC-Switch-*-Linux-*.AppImage

deb 包（Ubuntu / Debian）

sudo dpkg -i CC-Switch-*-Linux-*.deb
sudo apt install -f

rpm 包（CentOS / RHEL / Fedora）

sudo rpm -i CC-Switch-*-Linux-*.rpm

或使用 dnf / yum：

sudo dnf install ./CC-Switch-*-Linux-*.rpm

添加渠道

先从官网获取 API Key 与 请求地址，记录备用

Claude为例

顶部选择Claude图标后点击加号

自定义渠道

仅需填写 供应商名称、API Key、请求地址，点击 添加/保存 即可自动启用

Codex为例

仅需填写 供应商名称、API Key、请求地址（CodeX需要以/v1结尾），点击 添加/保存 即可自动启用

Gemini为例

设置与上述相同 换汤不换药

附加设置

建议开启以下两项：

• 应用到 ClaudeCode 插件：让 VSCode/JetBrains 等 IDE 内的 Claude Code 插件自动读取当前渠道
• 跳过 Claude Code 初次安装确认：第一次启动 claude 时不再弹出登录/授权确认

切换 / 管理渠道

在主界面点击任意渠道即可切换为当前生效渠道，无需重启 Claude Code（下次启动 claude 命令时即生效）

渠道支持 编辑 / 删除 / 排序，便于在 Anthropic 官方、第三方代理、本地代理之间快速切换

前言

Claude Code 是 Anthropic 官方的命令行 AI 编程工具。本文介绍 Windows / Mac / Linux 三系统的统一配置流程

前置 Node.js 与 Git 环境的安装请参考 《Node.js 与 Git 环境配置教程》，cc-switch 配置详见 《cc-switch 配置教程》

安装 Claude Code

安装方法

三系统使用同一条 npm 命令

npm install -g @anthropic-ai/claude-code

验证

claude -v

输出版本号即为安装成功

常见问题

Q：permission denied / EACCES 错误（Mac / Linux）

不要使用 sudo，把 npm 全局目录改到用户目录

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc   # zsh 用户改为 ~/.zshrc
source ~/.bashrc

Q：permission denied 错误（Windows）

以管理员身份运行 PowerShell

npm config set prefix "$env:APPDATA\npm"
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Q：command not found: claude

npm 全局 bin 目录未加入 PATH，执行 npm config get prefix 查看路径，将对应的 /bin 目录追加到系统 PATH

配置 API Key

cc-switch（推荐）

图形化工具，支持多渠道一键切换、自动写入 ClaudeCode 插件，无需手动改环境变量

详见独立文章 《cc-switch 配置教程》

手动配置环境变量

Windows

以管理员身份打开 PowerShell，运行

setx ANTHROPIC_BASE_URL "你的API地址"
setx ANTHROPIC_AUTH_TOKEN "你的Key"

关闭并重开终端后验证

# PowerShell
echo $env:ANTHROPIC_BASE_URL
echo $env:ANTHROPIC_AUTH_TOKEN

# cmd
echo %ANTHROPIC_BASE_URL%
echo %ANTHROPIC_AUTH_TOKEN%

Mac / Linux

编辑 shell 配置文件（zsh 用户编辑 ~/.zshrc，bash 用户编辑 ~/.bashrc，macOS 上的 bash 编辑 ~/.bash_profile）

vim ~/.zshrc

在文件末尾追加

export ANTHROPIC_BASE_URL="你的API地址"
export ANTHROPIC_AUTH_TOKEN="你的Key"

保存退出后让配置生效并验证

source ~/.zshrc
echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN

开始使用

在任意项目目录打开终端（Windows 可右键 "在终端中打开" 或 "Git Bash Here"），输入 claude 启动

cd 你的项目目录
claude

首次启动会依次提示：选择主题样式、信任当前目录、登录方式（cc-switch 已开启"跳过初次安装确认"则自动跳过）

看到输入框出现 > 提示符后，直接用中文或英文描述需求即可，例如

帮我在当前目录创建一个 hello.py 输出 Hello World

常用快捷指令：

• /help：查看所有命令
• /clear：清空当前会话
• /exit 或连按两次 Ctrl + C：退出

注册账号

访问官网：code.b886.top

当前支持：LinuxDo快捷登录 与 邮箱注册

开放注册邮箱：edu.cn gmail.com 163.com 126.com qq.com

点击注册

选择需要的注册方式

输入对应信息完成注册

开放注册邮箱： edu.cn gmail.com 163.com 126.com qq.com

API/URL 与 Key/令牌

API/URL

登录后右侧 API信息 板块即可查看最新的地址

Claude复制即可 Codex复制后需添加/v1

Key/令牌

登录后 左侧 令牌管理

点击 添加令牌

输入 令牌名称 并选择对应分组

百分之90的不可用错误都是因为此问题：务必选择分组后提交创建

百分之90的不可用错误都是因为此问题：务必选择分组后提交创建

百分之90的不可用错误都是因为此问题：务必选择分组后提交创建

推荐保持默认（如图）即可，点击 提交

点击 密钥 栏下的复制按钮即复制添加的令牌

充值 与 续费

可输入自定义充值数量（1元起），或选择 预设充值额度，选择可用支付方式即可，为避免充值不到账情况，付款后务必等待界面提示支付成功后关闭窗口

如遇充值未到账，联系站长解决即可