常见问题 FAQ

新手常问的问题和详细解答

常见问题（FAQ）¶

本文档解答 Claude Code 使用中的常见问题。

安装与设置 ¶

Q: 如何安装 Claude Code？¶

A: Claude Code 通过 npm 全局安装：

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

安装后，在任意项目目录运行 claude 即可启动。

Q: 安装后提示找不到 claude 命令？¶

A: 这通常是因为 npm 全局目录不在系统 PATH 中。解决方法：

# 查看 npm 全局目录
npm config get prefix

# 将该目录的 bin 子目录添加到 PATH
# macOS/Linux（添加到 ~/.zshrc 或 ~/.bashrc）
export PATH="$(npm config get prefix)/bin:$PATH"

Q: 如何配置 QCode.cc 代理？¶

A: 设置以下环境变量：

# 国内用户推荐深圳直连（最低延迟）
export ANTHROPIC_BASE_URL="http://103.236.53.153/api"
# 海外用户使用国际入口
# export ANTHROPIC_BASE_URL="https://api.qcode.cc/"
export ANTHROPIC_AUTH_TOKEN="cr_your_api_key"

建议将这些变量添加到 shell 配置文件（如 ~/.zshrc）中。

API Key 与认证 ¶

Q: API Key 在哪里获取？¶

A: 登录 QCode.cc 控制台，在 API Key 管理页面创建或查看你的 API Key。

Q: API Key 以什么开头？¶

A: QCode.cc 的 API Key 以 cr_ 开头，如 cr_xxxxxxxxxxxxxx。

Q: 为什么我的 API Key 无法使用？¶

A: 可能的原因：

复制错误：检查是否有多余空格或缺少字符
订阅过期：检查账户订阅状态
环境变量未生效：重新打开终端或运行 source ~/.zshrc
API 端点错误：确认 ANTHROPIC_BASE_URL 设置正确

用量与费用 ¶

Q: 如何查看当前会话的用量？¶

A: 有两种方式查看用量：

方式一：Dashboard 查看（推荐）

模型调用次数：各模型的调用频率统计
费用开销：精确的费用消耗明细
套餐消耗情况：当前套餐的配额使用进度

Dashboard 的数据相对实时更新，且计费更加准确。我们采用业界公认的 LiteLLM 计费规则，并定期同步更新，确保费用统计的准确性。

方式二：CLI 内快速查看

使用 /cost 命令可以快速查看当前会话的概况：

/cost

输出示例：

Total cost:            $0.55
Total duration (API):  6m 19.7s
Total code changes:    10 lines added, 5 lines removed

注意：/cost 显示的费用仅供参考，适合快速了解模型调用分布和大致用量。由于 Anthropic 官方未公开各模型的详细计费规则，CLI 内置的计费可能与实际有出入，建议以 Dashboard 统计为准。

Q: 如何减少 token 消耗？¶

A: 几种有效方法：

压缩上下文：使用 /compact 命令
清除历史：使用 /clear 重置上下文
精确提问：避免模糊问题导致不必要的代码扫描
分解任务：将大任务拆分为小任务

Q: 什么时候会自动压缩上下文？¶

A: Claude Code 默认在上下文达到 95% 容量时自动压缩。你也可以：

手动运行 /compact 主动压缩
在 /compact 后添加自定义指令来控制压缩重点

Q: 尊享版和企业团队版的 Max x20 账号资源有使用上限吗？¶

A: 有的。尊享版和企业团队版套餐底层使用 Anthropic Claude Max x20 账号资源，每个账号存在月度使用额度上限。根据我们的运营经验，一个 Max x20 账号在一个月（30天）内的实际消耗通常在 $4,500 ~ $4,800 范围。

我们通过账号资源池的方式进行管理和调度，可以保证每个账号在 30 天周期内享有 $5,000 的额度上限。由于绝大部分用户的实际使用量远低于该上限，因此对日常使用基本不会产生影响。如有特殊高用量需求，请联系客服沟通。

Q: 每个套餐的并发限制和时间窗口限制是怎样的？¶

A: 关于并发和时间窗口限制，各套餐的具体情况如下：

并发限制：

个人套餐（基础版/进阶版/尊享版）：每个 API Key 并发数为 5。一般来说，一个 Claude Code 会话连接会产生一定的并发请求，但根据我们的观察，并发 5 足以覆盖个人使用场景，目前暂无用户反馈不够用的情况。
企业团队版：每个账号资源的并发数为 35，足够支持一个账号 3~5 人左右同时使用。

4 小时时间窗口限制：

个人套餐（基础版/进阶版/尊享版）：均有 4 小时时间窗口限制，在窗口期内有一定的请求量限制。
企业团队版：没有 4 小时时间窗口限制，可以满足团队持续开发的需求，不会因为窗口期限制而中断工作流。

Q: 是否支持退款？¶

A: 我们销售的是网络数字商品，开通后即占用账号资源并开始计费使用，因此 不支持退款。

余额转账替代方案：

考虑到部分用户有转出余额的需求，我们支持 QCode 会员之间的余额转账服务：

出售余额：您可以在闲鱼、转转等第三方平台出售您的 QCode 账户余额
申请转账：找到买家后，发送邮件至 hi@qcode.cc
邮件内容：
转出金额
接收方的 QCode 账户邮箱（必须是已注册会员）
处理时效：我们将在 1 个工作日内完成转账

重要限制：

⚠️ 余额转账仅限 QCode 注册会员之间进行
⚠️ 不支持转账到非会员账户
⚠️ 不支持提现到支付宝、银行卡等第三方支付平台

Q: 什么情况下可以申请退款？¶

A: 仅在以下特殊情况下，我们可能酌情考虑退款（需提供详细说明和证据）：

由于平台技术故障导致的服务中断超过 24 小时
平台单方面终止服务且用户账户有剩余余额
误充值情况下，用户在充值后 24 小时内申请且未使用任何服务（未创建 API Key、未产生任何调用）

平台保留最终决定权。建议购买前仔细阅读套餐说明，确认符合需求后再购买。

权限系统 ¶

Q: Claude Code 的权限模式有哪些？¶

A: 四种权限模式：

模式	说明
`default`	首次使用工具时询问权限
`acceptEdits`	自动批准文件编辑
`plan`	只分析不修改（Plan Mode）
`bypassPermissions`	跳过所有权限提示（需安全环境）

Q: 如何配置默认权限模式？¶

A: 在 .claude/settings.json 中配置：

{
  "permissions": {
    "defaultMode": "plan"
  }
}

Q: 如何阻止 Claude Code 读取敏感文件？¶

A: 在 .claude/settings.json 中配置 deny 规则：

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

Q: 如何预先批准常用命令？¶

A: 在 .claude/settings.json 中配置 allow 规则：

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Bash(git status)"
    ]
  }
}

CLAUDE.md 配置 ¶

Q: CLAUDE.md 是什么？¶

A: CLAUDE.md 是项目级配置文件，用于向 Claude 提供项目上下文，如：

项目架构说明
编码规范
常用命令
特殊约定

Q: CLAUDE.md 放在哪里？¶

A: 放在项目根目录。Claude Code 启动时会自动读取。

Q: 如何创建 CLAUDE.md？¶

A: 使用 /init 命令自动生成：

/init

或手动创建，基本结构：

# 项目名称

## 概述
简要描述项目...

## 技术栈

- 前端：React
- 后端：FastAPI

## 常用命令

- 启动开发服务器：`npm run dev`
- 运行测试：`npm test`

## 编码规范

- 使用 TypeScript
- 函数优先于类

上下文管理 ¶

Q: 如何清除会话历史？¶

A: 使用 /clear 命令：

/clear

这会清除所有对话历史，开始全新会话。

Q: 如何只压缩而不清除历史？¶

A: 使用 /compact 命令：

/compact

可以添加指令控制压缩重点：

/compact 保留所有代码示例

Q: 如何查看当前上下文状态？¶

A: 使用 /context 命令：

/context

Q: @ 符号引用文件的用法？¶

A: 使用 @ 直接引用文件添加到上下文：

@src/main.ts 解释这个文件的功能
@package.json 检查依赖版本

MCP 服务器 ¶

Q: 什么是 MCP？¶

A: MCP（Model Context Protocol）是一种协议，允许 Claude Code 连接外部工具和数据源，扩展其能力。

Q: 如何配置 MCP 服务器？¶

A: 在 ~/.claude/settings.json 中配置：

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@context7/mcp-server"]
    }
  }
}

Q: 为什么 MCP 服务器连接失败？¶

A: 检查以下几点：

服务器命令是否正确
必需的依赖是否已安装
环境变量是否正确设置
使用 /mcp 命令查看状态

常见操作 ¶

Q: 如何进入 Plan Mode？¶

A: 按 Shift+Tab 两次，或在配置中设置默认模式。Plan Mode 下 Claude 只分析不执行。

Q: 如何切换模型？¶

A: 使用 /model 命令：

/model opus
/model sonnet

Q: 如何查看可用命令？¶

A: 使用 /help 命令查看所有内置命令。

Q: 如何中断正在运行的操作？¶

A: 按 Escape 键中断当前操作。

Q: 如何让 Claude 记住某些信息？¶

A: 使用 /memory 命令添加到会话记忆：

/memory 这个项目使用 pnpm 而不是 npm

Git 操作 ¶

Q: 如何让 Claude 帮我提交代码？¶

A: 使用 /commit 命令：

/commit

Claude 会分析变更并生成提交信息。

Q: 如何让 Claude 帮我审查代码？¶

A: 使用 /review 命令：

/review

可以指定审查范围：

/review src/auth/

故障排除 ¶

Q: 如何诊断 Claude Code 配置问题？¶

A: 使用 /doctor 命令进行自动诊断：

/doctor

它会检查环境变量、API 连接、MCP 服务器状态等常见配置问题。

Q: Claude Code 支持多大的上下文窗口？¶

A: Claude Code 默认使用 20 万 token 上下文窗口。Opus 4.6 和 Sonnet 4.6 模型支持扩展至 100 万 token（1M context）。如果遇到性能问题，可以通过设置环境变量禁用：

export CLAUDE_CODE_DISABLE_1M_CONTEXT=1

Q: Claude 响应很慢怎么办？¶

A: 尝试以下方法：

检查网络连接
使用 /compact 压缩上下文
切换到更快的模型（如 Sonnet）：/model sonnet
避开高峰时段
检查是否有大文件在上下文中
运行 /doctor 诊断配置问题

Q: 出现 "Rate limit exceeded" 怎么办？¶

A: 这是 429 错误，表示请求过于频繁：

等待 30-60 秒后重试
减少请求频率
查看错误码参考了解详情

Q: Claude 无法读取文件怎么办？¶

A: 检查以下几点：

文件是否存在
文件权限是否正确
文件是否在 deny 规则中
路径是否正确

Q: 如何报告 Bug？¶

访问 GitHub Issues
提供详细的复现步骤
附上相关错误信息