Claude Code 使用问题 FAQ（启动 / 配置 / 报错排查）

我是 Quentin，OpenClaw 作者。这篇是 OpenClaw 拼车技术群里真实出现过的 Claude Code 使用问题集合 —— 启动卡住、Auth 报错、Rate limit、Context window 溢出、MCP 配错……配上验证过有效的解法。

排查不动想换条路？直接接拼车回血：
curl -fsSL https://cp.bizq.net/setup.sh | bash -s -- claude-max-20x

启动与连接

Q: Claude Code 启动后一直 “Connecting…”？

可能原因：网络不通 / API endpoint 被劫 / 认证过期。

# 1. 验证官方 endpoint 通不通
curl -I https://api.anthropic.com
 
# 2. 检查代理变量是不是把请求劫到奇怪的地方
echo $HTTP_PROXY $HTTPS_PROXY $ANTHROPIC_BASE_URL
 
# 3. 重新登录
claude logout && claude login

如果 ANTHROPIC_BASE_URL 指向某个第三方网关，那台网关挂了你就连不上 —— 走 OpenClaw 拼车的好处是 base URL 永远是官方 endpoint。

Q: “Authentication failed” 怎么办？

按这个顺序：

# 1. 看看现在的 auth 配置
openclaw models auth list
 
# 2. 验证 key 还有效
openclaw infer --prompt "ping" --model anthropic/claude-haiku
 
# 3. 实在不行就重置
claude logout
claude login

如果是 OpenClaw 拼车 profile，重新跑一次 setup.sh 就回到工作状态。

Q: 连接超时？

# 拉长超时
export ANTHROPIC_TIMEOUT=120000
 
# 国内网络如果需要走代理
export HTTPS_PROXY=http://your-proxy:port

国内网络环境配置见 npm 国内加速配置和如何修改 hosts 文件。

配置问题

Q: 怎么查看当前配置？

# Claude Code 自身配置
claude config list
claude config path
 
# OpenClaw 这一层（推荐）
openclaw config show
openclaw models auth list

Q: 怎么换默认模型？

# Claude Code 端
claude config set model claude-sonnet-4-6
 
# OpenClaw 端：按模型路由不同 profile
openclaw config set "models.fallbacks.anthropic:claude-opus-4-7.profile=anthropic:carpool"

可选模型常见的有：claude-sonnet-4-6、claude-opus-4-7、claude-haiku。

Q: CLAUDE.md 不生效？

排查清单：

文件在项目根目录（不是子目录）
文件名严格 CLAUDE.md，大小写敏感
启动时看 claude 是不是真的从这个目录起的
内容写法见 CLAUDE.md 约束提示词指南

Q: 如何设置自定义 API endpoint？

强烈建议不要直接改 ANTHROPIC_BASE_URL，那是全局变量，会污染所有 Claude 项目。

正确姿势是用 OpenClaw 的 auth profile 隔离：

openclaw config set --batch '{
  "auth.profiles.anthropic:custom.base_url": "https://your-endpoint.com",
  "auth.profiles.anthropic:custom.api_key_ref.value": "sk-..."
}'

详细见 OpenClaw Claude Code 拼车配置指南。

命令使用

Q: 常用斜杠命令？

命令	作用
`/help`	帮助
`/clear`	清空当前对话
`/compact`	压缩上下文
`/config`	打开配置
`/cost`	当前会话成本
`/doctor`	自动诊断
`/init`	初始化项目（生成 CLAUDE.md）
`/login` `/logout`	登录 / 退出
`/memory`	管理项目记忆
`/model`	切换模型
`/permissions`	管理工具权限
`/review`	代码审查
`/status`	状态
`/terminal-setup`	终端配置

Q: Plan 模式怎么用？

# 启动直接进 plan
claude --plan
 
# 或者会话里切
/plan

Plan 模式下 Claude Code 先写计划再执行，适合多步任务、跨文件改动。

Q: 怎么让 Claude Code 只读不写？

最稳的办法是用 /permissions 把 Edit/Write 设成需要确认，或者直接：

claude --permission-mode plan

Q: 怎么批量处理文件？

直接在 prompt 里点名 glob：

处理 src/components/**/*.tsx，把 React.FC 改成函数声明
检查 **/*.ts 里的类型错误并修复

或者用 plan 模式让它先列出要改的文件再批准。

报错排查

Q: “Rate limit exceeded”？

含义：到本周用量上限。解法：

等下次重置（通常每周）
升级到更高档 Max
/compact 压缩上下文，减少单次 token
接 OpenClaw 拼车补量（按团队规模报价）

Q: “Context window exceeded”？

上下文超出模型窗口。解法：

/compact   # 压缩，保留关键信息
/clear     # 直接清空开新对话

如果你经常 hit window，用 Sonnet 4.6（200K+）替代 Haiku，或者把项目读 prompt 拆成多次。

Q: “Tool execution failed”？

通常是权限或路径问题：

/permissions          # 看现在哪些工具被允许
ls -la /path/to/file  # 验证路径

Q: Claude Code 卡住不动？

按 Ctrl+C 中断
/status 看现在在干啥
重启 Claude Code

如果是大型 plan 死循环，先 /clear 再重新写更明确的 prompt。

Q: 终端乱码？

export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8
/terminal-setup

Windows 上看 Claude Code Windows 环境变量设置。

文件操作

Q: 某些文件读不到？

可能命中了：

.gitignore 里的规则
.claudeignore 里的规则
文件权限不够
路径有特殊字符

ls -la filename
cat .gitignore | grep filename
claude "读取 /absolute/path/to/file"   # 用绝对路径

Q: 想让 Claude Code 忽略某些文件？

项目根创建 .claudeignore：

node_modules/
dist/
build/
.env
*.key
*.pem

格式跟 .gitignore 一样。

Q: 修改的文件没保存？

依次检查：

/permissions 看 Edit/Write 是不是被禁
磁盘空间（满了写不进）
文件是不是被其他进程锁住

Git 集成

Q: Claude Code 不识别 Git 仓库？

git status         # 确认在 git 仓库内
git init           # 没初始化先 init

Q: 自动提交怎么用？

直接说：

提交当前修改，commit message 用中文，参考 git log 风格

或者用 /commit 这种 custom slash command（自己写到 .claude/commands/）。

Q: 让 Claude Code 创建分支？

请创建分支 feature/xxx 并切过去

它会跑 git checkout -b feature/xxx。

性能优化

Q: 响应很慢？

/compact 压缩上下文，token 少了响应就快
减少不必要的文件引用
大任务拆小
简单任务用 Haiku 比 Sonnet 快很多

Q: 怎么减少 token 消耗？

四条铁律：

直接说需求，不要寒暄
定期 /compact，别让上下文无限膨胀
大任务分批，避免一次性塞所有文件
相关任务一个会话内做完，复用上下文

详细技巧见 Claude Code 34 条使用技巧。

Q: 上下文管理最佳实践？

/status    # 看当前用了多少
/compact   # 压缩
/clear     # 完全重开

我的习惯是每完成一个独立任务就 /clear 一次，不让上一个任务的上下文污染下一个。

高级使用

Q: MCP 服务器怎么用？

# 列出已装的
claude mcp list
 
# 加一个
claude mcp add server-name

详细配置见 Claude Code MCP 服务器完整指南和常用 MCP 服务器推荐。

Q: Subagents 怎么用？

让 Claude Code 启子任务并行干活：

请用 Task 工具并行做：
1. 搜所有含 "TODO" 的文件
2. 列所有测试文件
3. 列配置文件

详细见 Claude Code Subagents 功能详解。

Q: 怎么自定义快捷键？

~/.bashrc 或 ~/.zshrc 里加 alias：

alias cc="claude"
alias ccp="claude --plan"
alias ccr="claude --resume"

Q: CI/CD 里怎么用？

claude --non-interactive --yes "运行测试并修复失败的用例"
 
# 或环境变量
export CLAUDE_CODE_NON_INTERACTIVE=1

注意非交互模式默认 --yes 会跳过权限确认，生产环境慎用，建议在沙箱里跑。

其他

Q: Claude Code 和 Claude Pro 区别？

特性	Claude Pro	Claude Code
界面	Web/App	CLI 终端
用途	通用对话	编程专用
文件操作	有限	完整支持
Git 集成	无	有
代码执行	无	有（带权限管控）
MCP 支持	无	有

Q: 用量到顶了怎么办？

等每周重置
升级到更高档
接 OpenClaw 拼车补量

Q: 怎么查实时使用量？

# 当前会话
/cost
 
# 全量统计
ccusage
 
# OpenClaw 拼车额度
openclaw carpool usage

ccusage 工具用法见 ccusage 使用量统计神器。

立即开始

排查不动直接接拼车回血：

curl -fsSL https://cp.bizq.net/setup.sh | bash -s -- claude-max-20x

微信咨询，按团队规模报价 →

Claude Code 常见问题 FAQ —— 拼车 / 价格 / 安全 / 安装等业务问题
Claude Code 完整使用指南 —— 从入门到精通
Claude Code 最佳实践 —— 高效使用技巧
如何清理本地 Claude Code 缓存和配置 —— 出诡异 bug 时的核弹方案

Claude Code 集团号是什么 / 怎么加入 OpenClaw 拼车联系 OpenClaw 拼车团队（微信 / 邮件 / GitHub）