疑难解答

CCTQ 发布于 阅读：27

前言

汇总 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"
}
  1. 重启 worker：删除旧 PID 文件 rm ~/.claude-mem/worker.pid，下次 hook 触发自动用新配置重启
  2. 安全清理：只删已完成/已失败的消息，绝不删除 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 残留进程

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

# 错误：不要进 cache/ 目录，那里没有 worker 脚本
  1. 验证修复
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"
  1. 在飞书开放平台进入事件配置页面，添加「接收消息」事件
  2. 重新创建一个版本并发布（否则订阅事件不生效）
  3. 在飞书工作台找到机器人发送消息，获取配对码后执行
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、请求头、模型）

扫描二维码，在手机上阅读