zebbern/claude-code-guide · 上手攻略

• 仓库：zebbern/claude-code-guide
• 链接：https://github.com/zebbern/claude-code-guide
• 分类：ai-agent-tools
• 作者：Tom
• 更新：2026-08-09

这是什么

zebbern/claude-code-guide 是一个社区维护的 Claude Code 超级百科（GitHub 4.5k+ ★），覆盖从安装配置到高级用法的全链路指南，由用户 zebbern 维护，独立于 Anthropic 官方文档。它既是新手的「一键上手地图」，也是高级用户的命令速查手册，涵盖了 Claude Code 的几乎所有功能特性——包括 MCP、Sub-Agents、Skills、Hooks、Plugin System、Worktree 隔离等。

本质上是把 官方 Claude Code 文档 结构化重组，并补充了大量社区实践与命令碎片。

解决什么问题

• 官方文档分散在不同页面，查找成本高；该仓库将所有功能聚合成一个可导航的 Markdown 大全。
• 环境变量、配置文件、多平台安装命令散落各处，该仓库提供了跨平台（macOS / Linux / Windows / WSL / Docker）的完整安装与配置代码块。
• 对于 Sub-Agents、Skills、Hooks、MCP 等高级特性缺乏实战示例，该仓库提供了具体用法说明。

快速安装

方式一：原生安装程序（推荐，无需 Node.js）

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

# Windows (PowerShell)
irm https://claude.ai/install.ps1 | iex

# Arch Linux
yay -S claude-code

方式二：npm 安装（需要 Node.js 18+）

# 全局安装
npm install -g @anthropic-ai/claude-code

# 验证安装
claude --version

方式三：Docker

# Linux/macOS
docker run -it --rm \
  -v "$PWD:/workspace" \
  -e ANTHROPIC_API_KEY="sk-your-key" \
  node:20-slim \
  bash -lc 'npm i -g @anthropic-ai/claude-code && cd /workspace && claude'

# Windows (CMD)
docker run -it --rm -v "%cd%:/workspace" -e ANTHROPIC_API_KEY="sk-your-key" node:20-slim bash -lc "npm i -g @anthropic-ai/claude-code && cd /workspace && claude"

认证

# 通过 Anthropic 账号登录（弹出浏览器认证）
claude auth login

# 通过 API Key 直接认证
claude auth login --console

# 设置 API Key（Linux/macOS）
export ANTHROPIC_API_KEY="sk-your-key-here"

# 设置 API Key（Windows CMD）
set ANTHROPIC_API_KEY=sk-your-key-here

# 设置持久化 Key（Windows PowerShell）
[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY","sk-your-key-here","User")

核心用法

启动与基本交互

# 在当前目录启动 Claude Code 交互界面
claude

# 或者用 npx（不需要全局安装时）
npx claude

# 常用管理命令
claude config set --global preferredNotifChannel terminal_bell  # 开启完成提示音
claude mcp list                                        # 列出已配置的 MCP 服务器
claude mcp add <name> <command>                        # 添加 MCP 服务器
claude agents                                          # 打开 Agent/会话仪表盘
claude update                                          # 手动检查更新

MCP（Model Context Protocol）集成

MCP 是 Claude Code 连接外部工具的桥梁，该仓库详细记录了配置方式：

# 查看当前 MCP 服务器列表
claude mcp list

# 添加一个 MCP 服务器（如 GitHub）
claude mcp add github -- npx -y @modelcontextprotocol/server-github

# 移除 MCP 服务器
claude mcp remove github

# 设置 MCP 超时（默认 120000ms）
export MCP_TIMEOUT=120000
export MCP_TOOL_TIMEOUT=60000

MCP 服务器让 Claude Code 可以直接与 GitHub、文件系统、数据库等外部系统交互，实现真正的工作流自动化。

Sub-Agents（子代理）

Sub-Agent 是 Claude Code 的多智能体核心能力——在独立上下文窗口中运行专注任务，不污染主会话上下文：

# 在 Claude Code 对话中直接召唤子代理
# （通过 @subagent 指令或 skills 触发）
/subagent <任务描述>

# 常用场景：
# - 代码审查（独立上下文，不干扰主会话）
# - 文档生成
# - 批量数据处理

Sub-Agent 与 Skills 的核心区别在于：Sub-Agent 有自己的隔离上下文窗口，适合长时间运行任务；Skills 则是按需注入到主上下文的知识/程序集。

Skills（技能）

Skills 是 Claude Code 按需加载的专业知识与程序包，在需要时自动注入上下文：

# 内置命令/技能
/help          # 获取帮助
/bug           # 报告 bug（可用 DISABLE_BUG_COMMAND=1 禁用）
/claude        # 显示当前会话信息

# 自定义 Skill 存放路径
# ~/.claude/skills/  目录下放 SKILL.md 文件即可被自动加载

一个 Skill 的基本结构（SKILL.md 示例）：

---
name: my-skill
description: 做某事的技能
version: 1.0.0
---

# My Skill

这里是技能的指令内容...

Hooks（钩子）

Hooks 是在主模型决策之前/之后运行的确定性策略，强制执行安全或规范要求：

# 在项目根目录创建 .claude/hooks/ 目录
mkdir -p .claude/hooks

# 钩子文件示例：pre-tool-use 钩子在工具调用前执行
# 用于强制代码审查、安全扫描等

Worktree 隔离

避免多任务相互干扰，使用 Git Worktree 隔离每个任务的工作目录：

# 在项目目录中创建新的 worktree
git worktree add ../feature-xyz my-feature-branch

# 然后在新目录中运行 claude
cd ../feature-xyz && claude

Auto Mode 与 Plan Mode

# Plan Mode：让 Claude 先规划再执行
/plan <任务描述>

# Auto Mode：Claude 自动执行完整任务流
/auto <任务描述>

# 切换不同 Effort Level
/effort low    # 快速修复
/effort medium  # 标准实现
/effort high    # 深度重构或复杂任务

键盘快捷键

Ctrl+C        # 中断当前操作
Ctrl+L        # 清屏
Ctrl+Shift+R  # 重启当前会话
Tab           # 自动补全
↑ / ↓         # 历史命令导航

环境变量完整参考（关键）

# 认证
export ANTHROPIC_API_KEY="sk-..."           # 必需：API Key

# 模型配置
export ANTHROPIC_MODEL="sonnet"              # 默认模型
export ANTHROPIC_DEFAULT_SONNET_MODEL="sonnet"
export ANTHROPIC_DEFAULT_OPUS_MODEL="opus"

# 云服务（AWS Bedrock / Google Vertex）
export CLAUDE_CODE_USE_BEDROCK=1             # 使用 Bedrock
export CLAUDE_CODE_USE_VERTEX=0              # 使用 Vertex AI
export AWS_BEARER_TOKEN_BEDROCK="bedrock_..."

# Bash 超时控制
export BASH_DEFAULT_TIMEOUT_MS=60000          # 默认 60s
export BASH_MAX_TIMEOUT_MS=300000             # 最长 5 分钟

# MCP
export MCP_TIMEOUT=120000                    # MCP 服务器启动超时
export MCP_TOOL_TIMEOUT=60000                # MCP 工具执行超时

# 实验性功能
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1  # 启用 Agent Teams 实验预览

# 精简模式（禁用 MCP/Skills/Hooks 等）
export CLAUDE_CODE_SIMPLE=1

# 代理
export HTTP_PROXY="http://proxy:8080"
export HTTPS_PROXY="https://proxy:8443"

# 遥测（可禁用）
export DISABLE_TELEMETRY=1
export DISABLE_ERROR_REPORTING=1

典型适用场景

1. 新用户首次上手：按照仓库的 Quick Start 5 分钟完成安装到第一个任务。
2. 多平台开发者：macOS/Linux/Windows 各自的安装与环境变量配置一站查齐。
3. 高级用户速查：MCP 服务器配置、Sub-Agent 使用、Hooks 编写等高级功能按需检索。
4. 团队技能共享：将 Skill/SHKILL.md 打包成分发格式，实现团队规范强制执行。
5. 自动化流水线：结合 GitHub Actions、Webhook、cron 实现 CI/CD 中的 AI 代码审查。

坑与注意

与同类对比

一句话推荐结论

Claude Code 上手必读的社区百科，无论你是刚装好 CLI 的新手，还是想精通 MCP/Sub-Agents/Skills 高级用法的老手，这个 4.5k+ ★ 的仓库都是最完整的参考资料——配合官方文档使用效果最佳。

最小可跑命令

# 环境：macOS/Linux，Node.js 18+ 或使用原生安装程序，Claude Code 最新版
# 模型：默认 Sonnet 4（可用 ANTHROPIC_MODEL 环境变量切换）

# 1. 安装（原生方式，无需 Node.js）
curl -fsSL https://claude.ai/install.sh | bash

# 2. 认证
export ANTHROPIC_API_KEY="sk-ant-api03-..."   # 替换为你的 Key
claude auth login --console

# 3. 在项目目录启动
cd /your/project
claude

# 4. 尝试 MCP（需先有 MCP 服务器）
claude mcp list

# 5. 启用完成提示音
claude config set --global preferredNotifChannel terminal_bell

⚠️ 版本说明：以上基于 README.md（2025 年中维护），Claude Code 版本号需运行 claude --version 确认；部分实验性功能（如 Agent Teams）需 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 环境变量开启。

原始仓库：https://github.com/zebbern/claude-code-guide 最后更新参考：README.md @ main 分支（2026-08 约 4,519 ★）