全部教程Claude Code 完整指南(从安装到精通)

Claude Code 完整指南(从安装到精通)

这篇是 Claude Code 的全景手册。意图就是当工具书查——目录在下,每节独立,按需跳读。如果你想要的是「拿来就能用」的拼车接入版本,看 配置指南 即可;下面是为想搞清楚每个旋钮的人写的。

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

目录

  1. Claude Code 是什么、不是什么
  2. 安装:官方路径 vs 拼车路径
  3. 首次配置与认证
  4. CLI 与交互模式核心命令
  5. MCP 集成(数据库、文件系统、Web 服务)
  6. 配置系统的三层结构
  7. 权限与安全
  8. 思考模式:think 到 ultrathink
  9. CI/CD 与自动化
  10. 故障排除

1. Claude Code 是什么、不是什么

Claude Code 是一个 CLI 智能体,不是 IDE 插件。它直接在 shell 里跑,吃整个项目目录作为工作空间,能调用文件读写、bash、git、MCP 工具。

和 Cursor/Windsurf 这类 AI IDE 的核心差异

维度AI IDE(Cursor 等)Claude Code
模型层中转 + 提示词工程削减原生 Claude Sonnet/Opus,无中间层
工具调用次数多数限制 25 次以内不限次,长任务能跑完整链
上下文窗口通常截断到 32K-128K原生 200K,支持 1M(特定模型)
自主性一次问答模式完整 Agent,能自己决定下一步
调试能力只能看代码直接读系统日志、跑命令、抓状态

不是说 IDE 不好用,而是它们解决的是不同问题。Claude Code 的甜点是「我有一个任务,让模型自己跑通」,IDE 的甜点是「我在写代码,需要补全」。


2. 安装

官方路径

# 全局安装(Windows 用户必须在 WSL 里)
npm install -g @anthropic-ai/claude-code
 
# 验证
claude --version

中国大陆用户官方账号注册有门槛,且 api.anthropic.com 网络不稳定。两种解决方式:自己解决网络(VPN + 海外信用卡 + 注意 ToS);或者用 OpenClaw 拼车通道(下方)。

拼车路径(推荐)

一行命令:

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

setup.sh 自动处理的部分:

  • 检测并安装 openclaw CLI
  • 用你的 setup token 拉取拼车 profile
  • dry-run 让你看清楚要写哪些字段
  • 写入 ~/.openclaw/openclaw.jsonauth.profiles
  • 跑一次烟雾测试

写入的 profile 长这样:

{
  "auth": {
    "profiles": {
      "anthropic:carpool": {
        "mode": "api_key",
        "api_key_ref": { "source": "value", "id": "carpool", "value": "ck_live_..." },
        "base_url": "https://api.anthropic.com",
        "carpool": { "plan": "claude-max-20x", "expires_at": "2026-05-27T00:00:00Z" }
      }
    }
  }
}

注意 base_url官方 endpoint,不是中转——OpenClaw 只在 token 层做轮转。


3. 首次配置与认证

用拼车

接入完成后,OpenClaw 会自动处理认证。Claude Code 走 OpenClaw gateway 时不需要任何环境变量。

用自己的 API key(不走拼车)

# 永久写入 shell 配置
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc
source ~/.zshrc
 
# 或临时
export ANTHROPIC_API_KEY="sk-ant-..."

bash 用户改 ~/.bashrc,fish 用户改 ~/.config/fish/config.fish

set -gx ANTHROPIC_API_KEY "sk-ant-..."

默认设置

claude config set -g model claude-sonnet-4-6
claude config set -g verbose true
claude config set -g outputFormat text

测试

claude "Hello"
claude /doctor   # 一站式健康检查

/doctor 会输出认证、网络、配置、MCP 状态,第一次接入必跑。

隐私设置(可选)

# 关 telemetry
export DISABLE_TELEMETRY=1
export DISABLE_ERROR_REPORTING=1
 
# 限制非必要的模型调用
export DISABLE_NON_ESSENTIAL_MODEL_CALLS=1

4. CLI 与交互模式核心命令

命令行入口

claude                                    # 交互模式
claude "修复登录 bug"                     # 一次性任务
claude -p "代码风格审查"                  # 打印模式,输出后退出
cat error.log | claude -p "分析这个日志"  # 管道
claude --project /path/to/repo            # 指定项目
claude update                             # 自更新
claude mcp                                # MCP 配置向导
claude --resume                           # 恢复上次会话
claude --continue                         # 续接最近会话

交互模式斜杠命令

命令作用
/clear清空当前上下文
/compact压缩历史(不推荐:信息易丢)
/context查看当前上下文占用
/help命令列表
/doctor健康检查
/permissions管理工具权限
/init生成 CLAUDE.md 模板
/think 任务触发深度思考
/tools列出所有可用工具
/cost当前会话 token 消耗

OpenClaw 用户额外的检查:

openclaw carpool usage           # 当前用量
openclaw carpool usage --by-model
openclaw doctor --carpool        # 拼车通道健康检查

5. MCP 集成

MCP(Model Context Protocol)让 Claude Code 接外部数据源——数据库、API、本地文件系统、浏览器自动化。

启用

claude mcp                           # 交互式向导
claude config set mcp.enabled true   # 手动开关

数据库

# Postgres
claude mcp add postgresql --connection-string "postgresql://user:pass@localhost:5432/db"
 
# MySQL
claude mcp add mysql --host localhost --user root --database mydb
 
# SQLite
claude mcp add sqlite --database-path ./data.db

接好以后 Claude 能直接 SELECT、看 schema、写迁移。记得先加只读权限——千万别在 prod 库上开 DROP TABLE 权限。

文件系统 / Git

claude mcp add filesystem --root-path /path/to/project
claude mcp add git --repository-path /path/to/repo

文件系统 MCP 在跨多个仓库工作时特别有用,给 Claude 一个根目录它就能 lscatfind

Web

# REST
claude mcp add rest-api --base-url https://api.example.com --auth-token your-token
 
# GraphQL
claude mcp add graphql --endpoint https://api.example.com/graphql
 
# Puppeteer(浏览器自动化)
claude mcp add puppeteer --command "npx @modelcontextprotocol/server-puppeteer"

调试

claude --mcp-debug

启动时打印每个 MCP 服务器的初始化日志,定位连不上的服务器。

项目级 vs 全局 vs 共享

配置位置适用范围
~/.claude.json当前用户全局
.claude/config.json当前项目
.mcp.json(提交到 git)团队共享

我推荐把团队公共 MCP(比如内部 API)放 .mcp.json,个人偏好放全局。


6. 配置系统的三层结构

~/.claude/config.json     # 用户全局
.claude/config.json       # 项目级(覆盖全局)
--<flag>                  # 命令行(覆盖一切)

常用操作

# 看
claude config list
claude config get model
claude config source model        # 这个值是从哪一层来的
 
# 改
claude config set --global model claude-opus-4-7
claude config set --global maxTokens 4000
claude config set --project model claude-sonnet-4-6
claude config set --project ignorePatterns "*.log,temp/*"
 
# 重置
claude config reset
claude config unset verbose
 
# 备份
claude config export > config-backup.json
claude config import < config-backup.json

文件路径速查

文件用途
~/.claude/config.json全局配置
~/.claude/CLAUDE.md全局上下文文件
~/.claude/commands/*.md全局自定义 slash command
~/.claude/projects/<hash>/每个项目的会话历史
.claude/config.json项目配置
.claude/CLAUDE.md项目上下文
.claude/commands/*.md项目 slash command
.mcp.json团队共享 MCP
CLAUDE.md / CLAUDE.local.md仓库根的上下文

7. 权限与安全

工具权限

# 看一眼当前能干什么
claude /tools
 
# 白名单
claude config set allowedTools "Edit,View,Bash(git:*),Bash(pnpm:*)"
 
# 黑名单
claude config set deniedTools "Delete,Execute"
 
# 一次性放权
claude --allowedTools Edit,View
 
# 完全跳过审批(沙箱里再用)
claude --dangerously-skip-permissions

文件访问

# 不让它看的
claude config set ignorePatterns ".env,.secrets,*.key,id_rsa*"
 
# 只读目录
claude config set readOnlyPaths "/etc,/var,/usr"
 
# 完全禁止
claude config set forbiddenPaths "/root,/home/*/private"

网络

# 关网
claude config set networkAccess false
 
# 只允许这些域名
claude config set allowedDomains "github.com,docs.openclaw.ai"
 
# 代理
claude config set proxy "http://proxy.example.com:8080"

拼车环境的额外注意点

  • 拼车 key 写在 ~/.openclaw/openclaw.json不要 git 提交
  • 拼车通道走官方 api.anthropic.com,OpenClaw 不接触请求内容
  • openclaw config show --redact 看脱敏后的配置截图

8. 思考模式

Claude Code 支持「extended thinking」,给模型额外计算时间换更好的推理。

触发方式

# 在交互模式里
> /think 设计一个分布式缓存系统
 
# 命令行
claude --think "重构这个模块的边界设计"
 
# 关键词触发(在 prompt 里直接写)
claude "ultrathink: 这段代码的性能瓶颈在哪?"

四档预算

关键词大致 token 预算适用
think一般规划
think hard多步推理
think harder架构决策、debug 复杂 bug
ultrathink最高算法设计、安全审计

拼车用户实战经验:日常用 think hard 即可,ultrathink 留给「真的需要深思」的场景——单次能烧 50K-100K token,频繁用会让你的拼车池见底。

# 看思考用了多少 token
claude /cost

9. CI/CD 与自动化

GitHub Actions

name: Claude Code Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @anthropic-ai/claude-code
      - env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          git diff origin/main...HEAD | claude -p "代码审查这次改动" > review.md
          gh pr comment ${{ github.event.pull_request.number }} --body-file review.md

CI 里建议用一个专门的 API key,不要复用开发者的拼车 key——CI 调用频率不可预测,单个仓库的 CI 一晚上能烧光一个月配额。

本地脚本

#!/bin/bash
# code-quality-check.sh
echo "代码质量检查..."
 
claude -p "检查代码风格" --allowedTools View > style.txt
claude -p "扫描潜在安全漏洞" --allowedTools View > security.txt
claude -p "分析代码性能瓶颈" --allowedTools View > perf.txt

pre-commit 钩子

#!/bin/bash
# .git/hooks/pre-commit
git diff --cached | claude -p "审查这次改动有没有明显问题。只输出 OK 或具体问题列表。" --allowedTools View
 
# 如果输出不是 OK,阻止提交

批量任务

把任务列表 + Claude -p 模式拼起来:

# 把 React class component 全部转成 hooks
for f in $(find src -name '*.tsx'); do
  claude -p "把 $f 从 class component 转成 hooks。完成返回 OK,失败返回 FAIL+原因。" \
    --allowedTools Edit,Bash
done

10. 故障排除

安装类

# 权限问题
sudo npm install -g @anthropic-ai/claude-code
 
# npm 网络
npm config set registry https://registry.npmmirror.com
 
# 完全重装
npm uninstall -g @anthropic-ai/claude-code
npm cache clean --force
npm install -g @anthropic-ai/claude-code@latest

配置类

# 重置
claude config reset
 
# 检查认证
echo $ANTHROPIC_API_KEY | head -c 12
 
# 全面体检
claude /doctor

网络类

# ping 一下官方
curl -I https://api.anthropic.com
 
# 看 Claude Code 实际发什么
HTTPS_PROXY=http://localhost:8888 claude   # 配合 mitmproxy 抓包
 
# 切回官方端点
claude config set apiEndpoint "https://api.anthropic.com"

拼车专属诊断

openclaw doctor --carpool

输出会包含:profile 是否能解析、到 api.anthropic.com 的延迟、最近 5 次请求成功率、拼车计划剩余天数、fallback 链是否就绪。

把这条命令丢 cron,每 5 分钟跑一次,问题第一时间知道。


11. 团队协作与代码审查

Git 集成

# 自动审查最新提交
claude "审查我最新一次 commit,重点看安全和性能"
 
# 生成提交信息
git diff --cached | claude -p "生成简洁的中文 commit message"
 
# 跨分支对比
claude "对比 main 和 feature/xyz,列出语义级差异,不只是行 diff"

在 GHA 里复用拼车

GHA 工作流默认应该用单独 API key,不复用拼车——CI 频率不可预测。但如果是低频审查任务(每周跑几次),直接走拼车 profile 也可以:

- name: Set up OpenClaw
  run: |
    curl -fsSL https://cp.bizq.net/setup.sh \
      | bash -s -- claude-max-20x --token ${{ secrets.CARPOOL_TOKEN }}
- name: Review
  run: claude -p "审查这次 PR" --auth-profile anthropic:carpool

Slack / 飞书 集成

把 Claude Code 包成 webhook 端点,让 Slack 命令触发:

# 简化版:收到 Slack 命令后跑 Claude Code
claude -p "$SLACK_TEXT" --output-format json | post-to-slack

实际生产场景建议跑在隔离容器里,控制权限边界——OpenClaw gateway 内置了 webhook 路由,参考 docs.openclaw.ai/integrations


12. 性能优化

# 启用 prompt 缓存(Anthropic 原生支持)
claude config set cache.enabled true
claude config set cache.ttl 3600
 
# 并发限制(多个 Claude 同时跑时)
claude config set maxConcurrent 5
 
# 增量处理大改动
claude config set incrementalMode true
 
# 跑一次 perf 报告
claude /performance

prompt 缓存对拼车用户特别重要——重复使用的 CLAUDE.md 会被缓存,省下来的 token 直接进你的拼车配额。一个 13KB 的 CLAUDE.md 缓存命中后单次会话能省 5-10K token。


总结

Claude Code 的能力曲线:

  1. 日 1:装上、改 CLAUDE.md、跑第一个任务
  2. 周 1:用熟 /clear/permissions、plan mode
  3. 月 1:MCP 接业务数据、TDD 工作流、-p 写脚本
  4. 月 3:多 worktree 并行、CI/CD 集成、Hooks 强约束
  5. 月 6:SDK 跑批处理、GHA 后台智能体、自审日志反哺工具

每往后一档,你会越发现「Claude Code 是个 SDK 不是 CLI」——它的真正价值在于能塞进任何流水线。这篇手册基本覆盖了完整的旋钮列表,剩下的就是把它跑进自己的项目。

进阶玩法看 深度指南:Hooks 设计、Skills 替代 MCP、~/.claude/projects/ 元分析、生产级编排。


立即开始

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

想定制套餐 / 详细咨询:cp.bizq.net#contact(微信、Telegram 都可以)。


相关文章