Claude Code 完整指南(从安装到精通)
这篇是 Claude Code 的全景手册。意图就是当工具书查——目录在下,每节独立,按需跳读。如果你想要的是「拿来就能用」的拼车接入版本,看 配置指南 即可;下面是为想搞清楚每个旋钮的人写的。
curl -fsSL https://cp.bizq.net/setup.sh | bash -s -- claude-max-20x目录
- Claude Code 是什么、不是什么
- 安装:官方路径 vs 拼车路径
- 首次配置与认证
- CLI 与交互模式核心命令
- MCP 集成(数据库、文件系统、Web 服务)
- 配置系统的三层结构
- 权限与安全
- 思考模式:think 到 ultrathink
- CI/CD 与自动化
- 故障排除
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-20xsetup.sh 自动处理的部分:
- 检测并安装
openclawCLI - 用你的 setup token 拉取拼车 profile
- dry-run 让你看清楚要写哪些字段
- 写入
~/.openclaw/openclaw.json的auth.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=14. 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 一个根目录它就能 ls、cat、find。
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 /cost9. 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.mdCI 里建议用一个专门的 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.txtpre-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
done10. 故障排除
安装类
# 权限问题
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:carpoolSlack / 飞书 集成
把 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 /performanceprompt 缓存对拼车用户特别重要——重复使用的 CLAUDE.md 会被缓存,省下来的 token 直接进你的拼车配额。一个 13KB 的 CLAUDE.md 缓存命中后单次会话能省 5-10K token。
总结
Claude Code 的能力曲线:
- 日 1:装上、改
CLAUDE.md、跑第一个任务 - 周 1:用熟
/clear、/permissions、plan mode - 月 1:MCP 接业务数据、TDD 工作流、
-p写脚本 - 月 3:多 worktree 并行、CI/CD 集成、Hooks 强约束
- 月 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 都可以)。
相关文章
- OpenClaw Claude Code 拼车配置指南 — 一键接入完整流程
- Claude Code 最佳实践 — 实战工作流模式
- Claude Code 深度指南 — Hooks、Skills、SDK 的进阶玩法
- Claude Code MCP Server 指南 — MCP 生态完整索引