Moment

Claude Code 终极上手指南：从零安装到 everything-claude-code 最佳实践配置

Claude Code 终极上手指南：从零安装到 everything-claude-code 最佳实践配置

本文更新时间：2026年4月 | 基于 Claude Code 官方文档 + 16万星仓库实战经验

前言

Claude Code 是 Anthropic 官方推出的终端编程工具，能让 Claude 直接读写代码、运行命令、调试程序、帮你完成从需求到实现的完整开发流程。它不是简单的"问答机器人"，而是一个真正的 Agentic Coding Tool——能主动执行任务、记住上下文、跨会话保持记忆。

everything-claude-code（https://github.com/affaan-m/everything-claude-code）是目前最大的 AI 编程最佳实践仓库，16万星、2.1万 Fork、170+ 贡献者，是一个历经 10 个月每日深度使用打磨出来的完整系统，涵盖技能、工作流、记忆优化、安全扫描和研究驱动的开发方法论。

本文覆盖：

  • ✅ Claude Code 最新安装方式（2026年4月更新，含 Desktop/VS Code/JetBrains 多端）
  • ✅ 认证配置与多层次权限系统
  • ✅ 自定义模型配置（Anthropic / AWS Bedrock / Google Vertex / Azure Foundry）
  • ✅ 插件系统详解
  • ✅ everything-claude-code 完整接入指南
  • ✅ OpenClaw 对比与适用场景分析

一、Claude Code 是什么？

Claude Code 是一个运行在终端里的 AI 编程 Agent，它能够：

  • 📖 阅读代码库：理解项目结构、依赖关系、代码风格
  • ✏️ 编辑文件：直接修改代码、添加功能、修复 bug
  • 🔧 执行命令：运行测试、构建、部署、Git 操作
  • 🔍 调试排查：分析错误信息、定位问题根因
  • 🤖 自动化工作流：通过 /plan 分解任务、/tdd 驱动开发、/code-review 审查代码

Claude Code 支持多种使用界面：

界面 说明 适用场景
终端（Terminal） 核心 CLI 工具，所有平台通用 深度开发、服务器环境
桌面应用 macOS/Windows 原生 App 需要 GUI 的日常开发
VS Code 插件 集成在 VS Code 里 喜欢 VS Code 的开发者
JetBrains 插件 集成在 IntelliJ/PyCharm 等 JetBrains 全家桶用户
浏览器 Web 版（需配合 Desktop） 快速查看和协作

二、安装 Claude Code

2.1 系统要求

项目 要求
macOS 版本 13 (Ventura) 或更高
Linux Ubuntu 20.04+、Debian 10+
Windows Windows 10+（推荐 WSL2）
网络 能访问 Anthropic API（国内需代理）

2.2 终端安装（推荐 macOS/Linux）

方式一：官方安装脚本（最推荐）

curl -fsSL https://claude.ai/install.sh | bash

方式二：Homebrew（macOS/Linux）

brew install --cask claude-code

方式三：NPM（已弃用，不推荐）

npm install -g @anthropic-ai/claude-code
# npm 方式已标记为 deprecated，建议迁移到上述方式

2.3 Windows 安装

PowerShell（推荐）：

irm https://claude.ai/install.ps1 | iex

WinGet：

winget install Anthropic.ClaudeCode

命令提示符（CMD）：

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

2.4 桌面应用安装

直接从 https://claude.com/download 下载 macOS 或 Windows 原生桌面应用，功能与终端版完全一致。

2.5 VS Code 插件安装

在 VS Code 中搜索 “Claude Code” 或运行：

code --install-extension anthropic.claude-code

安装后在 VS Code 侧边栏即可使用，支持查看 Diff、管理上下文、聊天等。

2.6 JetBrains 插件安装

在 IntelliJ IDEA、Pycharm、WebStorm 等 JetBrains IDE 的插件市场搜索 “Claude Code Beta” 安装，或访问：

https://plugins.jetbrains.com/plugin/27310-claude-code-beta-

2.7 验证安装

claude --version
# 或进入交互模式
claude

三、认证与初始配置

3.1 登录认证

首次运行 Claude Code 会自动打开浏览器进行 OAuth 授权：

claude
# 浏览器会自动打开授权页面，用 Anthropic 账号登录即可

3.2 API Key 配置（无浏览器环境）

在没有浏览器的环境（如服务器）里，用 API Key 认证：

export ANTHROPIC_API_KEY="sk-ant-xxxxx"

建议写入 Shell 配置文件永久生效：

# macOS (默认使用 zsh)
echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxx"' >> ~/.zshrc
source ~/.zshrc

# Linux (通常用 bash)
echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxx"' >> ~/.bashrc
source ~/.bashrc

3.3 多层次配置系统（Scope）

Claude Code 使用 四层配置作用域，优先级从高到低：

优先级 作用域 配置文件位置 影响范围 团队共享
1（最高） Managed 服务端/系统级 机器上所有用户 ✅ 由 IT 部署
2 Local .claude/settings.local.json 仅当前项目、本人 ❌ gitignore
3 Project .claude/settings.json 项目所有协作者 ✅ 提交到 git
4（最低） User ~/.claude/settings.json 本人所有项目 ❌

覆盖规则： 更高优先级的配置会覆盖更低优先级的同名配置。

配置文件路径汇总：

功能 User Project Local
设置 ~/.claude/settings.json .claude/settings.json .claude/settings.local.json
子 Agent ~/.claude/agents/ .claude/agents/ —
MCP 服务器 ~/.claude.json .mcp.json ~/.claude.json（按项目）
插件 ~/.claude/settings.json .claude/settings.json .claude/settings.local.json
CLAUDE.md ~/.claude/CLAUDE.md CLAUDE.md CLAUDE.local.md

四、自定义模型配置

Claude Code 默认使用 Anthropic 官方模型，但你也可以接入 AWS Bedrock、Google Vertex AI、Azure Foundry 等企业级平台，以及 OpenRouter 等第三方聚合 API。

4.1 Anthropic 官方模型（默认）

Claude Code 支持以下模型：

模型 特点
Claude Opus 4 最强推理能力，适合复杂任务
Claude Sonnet 4 平衡性能和速度，性价比高
Claude Haiku 轻量快速，适合简单任务

在 settings.json 中配置：

{
  "model": "claude-sonnet-4-20250514"
}

4.2 AWS Bedrock（企业级）

需要在 AWS Console 启用 Bedrock 并配置 IAM 凭证后，在 settings.json 中配置：

{
  "provider": "bedrock",
  "awsRegion": "us-east-1",
  "awsProfile": "default"
}

前置条件：

  1. AWS Console 中启用 Bedrock 模型访问
  2. 配置 AWS IAM 凭证（aws configure 或环境变量）
  3. 确保所选 region 支持对应模型

4.3 Google Vertex AI

{
  "provider": "vertex",
  "vertexProject": "your-gcp-project-id",
  "vertexLocation": "us-central1"
}

前置条件：

  1. GCP 中启用 Vertex AI API
  2. 创建有权限的服务账号
  3. 下载并配置服务账号密钥

4.4 Microsoft Azure Foundry

{
  "provider": "foundry",
  "foundryUrl": "https://your-resource.azurefoundry.ai",
  "foundryApiKey": "your-api-key"
}

前置条件：

  1. 订阅 Azure Foundry 服务
  2. 部署模型到 Foundry
  3. 获取 API 端点和密钥

4.5 OpenRouter（接入第三方模型）

OpenRouter 聚合了大量模型（包括免费模型），Claude Code 通过其 API 兼容模式接入：

步骤 1：获取 OpenRouter API Key

访问 https://openrouter.ai/keys 注册并生成 Key。

步骤 2：配置 OpenRouter Provider

Claude Code 官方尚未原生支持 OpenRouter，但可以通过配置 自定义 API 端点 接入。在 settings.json 中：

{
  "model": "openrouter/minimax/minimax-m2.5:free",
  "openRouterApiKey": "sk-or-v1-xxxxx",
  "apiKey": "sk-or-v1-xxxxx",
  "baseURL": "https://openrouter.ai/api/v1"
}

注意：OpenRouter API Key 同时作为 apiKey 和 openRouterApiKey 字段传递，确保模型路由正确。

步骤 3：常用 OpenRouter 模型

{
  "model": "openrouter/qwen/qwen3.6-plus:free",
  "model": "openrouter/openai/gpt-4o",
  "model": "openrouter/anthropic/claude-sonnet-4"
}

4.6 模型动态切换

在 Claude Code 会话中随时切换：

/model claude-sonnet-4-20250514

或在项目根目录创建 .claude/settings.json 指定项目级默认模型：

{
  "model": "claude-opus-4-20250514"
}

五、Claude Code 插件系统详解

5.1 什么是插件？

Claude Code 插件是扩展其功能的标准化包，可以包含：

组件 说明
Skills 工作流定义和领域知识
Agents 专业化的子 Agent
Commands 自定义斜杠命令
Hooks 事件触发器（工具执行前后、会话停止等）
MCP Servers 外部工具集成配置

5.2 插件目录结构

my-plugin/
├── .claude-plugin/
│   └── plugin.json       # 插件元数据
├── skills/               # 技能文件夹
│   └── my-skill/
│       └── SKILL.md
├── agents/               # 子 Agent
│   └── my-agent.md
├── commands/             # 斜杠命令
│   └── my-command.md
├── hooks/                # 事件钩子
│   └── hooks.json
├── .mcp.json             # MCP 服务器配置
└── README.md

5.3 插件 manifest 示例

{
  "name": "my-plugin",
  "description": "我的第一个 Claude Code 插件",
  "version": "1.0.0",
  "author": {
    "name": "你的名字"
  }
}

5.4 官方插件一览（内置）

Claude Code 官方仓库（https://github.com/anthropics/claude-code）自带以下插件：

插件名 功能
agent-sdk-dev Agent SDK 开发工具包
code-review 多 Agent 并行代码审查
commit-commands Git 提交/推送/PR 工作流
feature-dev 7 阶段特性开发工作流
frontend-design 生成式前端设计规范
hookify 创建自定义 Hook 防止不良行为
plugin-dev 插件开发完整工具包
pr-review-toolkit PR 审查代理工具包
security-guidance 安全提醒 Hook

5.5 安装社区插件

通过 /plugin 命令安装：

# 添加 marketplace
/plugin marketplace add https://github.com/affaan-m/everything-claude-code

# 安装插件
/plugin install everything-claude-code@everything-claude-code

5.6 插件 vs 独立配置的选择

场景 推荐方式
单项目个性化 独立配置 .claude/
快速实验 独立配置
团队共享 插件
多项目复用 插件
开源分发 插件（带版本控制）

六、everything-claude-code 完整指南

6.1 这个仓库是什么？

everything-claude-code 是 Anthropic Hackathon 冠军作品，是一个完整的 AI 编程 Agent 性能优化系统，核心包括：

  • 38 个专业子 Agent：代码审查、架构设计、TDD 指导、安全分析等
  • 156 个技能：涵盖 12+ 语言生态（TypeScript/Python/Go/Java/Swift/C++/Rust 等）
  • 72 个命令别名：与新技能系统共存的传统斜杠命令
  • 完整的 Hook 系统：会话记忆持久化、战略压缩、预工具安全检查
  • 规则引擎：安全规则、代码风格规则、测试规则
  • ECC Dashboard：Tkinter 桌面 GUI，可视化管理所有组件

6.2 核心组件详解

38 个专业子 Agent

Agent 用途
planner 特性实现规划
architect 系统设计决策
tdd-guide TDD 方法论指导
code-reviewer 质量和安全审查
security-reviewer 漏洞分析
build-error-resolver 构建错误修复（支持 10+ 语言）
e2e-runner Playwright E2E 测试
refactor-cleaner 死代码清理
database-reviewer 数据库/Supabase 审查
pytorch-build-resolver PyTorch/CUDA 训练错误
cpp-reviewer / cpp-build-resolver C++ 专用
java-reviewer / java-build-resolver Java/Spring Boot 专用
kotlin-reviewer / kotlin-build-resolver Kotlin/Android/KMP 专用
rust-reviewer / rust-build-resolver Rust 专用
typescript-reviewer TypeScript/JavaScript 专用
python-reviewer Python 专用
go-reviewer / go-build-resolver Go 专用

156 个技能（按功能分类）

开发流程类：

  • tdd-workflow — TDD 测试驱动开发
  • verification-loop — 持续验证循环
  • eval-harness — 评估框架
  • iterative-retrieval — 渐进式上下文优化
  • strategic-compact — 手动上下文压缩建议
  • continuous-learning-v2 — 基于 Instinct 的持续学习

前端类：

  • frontend-patterns — React/Next.js 模式
  • frontend-design — 生成式 UI 设计规范
  • frontend-slides — HTML 幻灯片构建
  • liquid-glass-design — iOS 26 Liquid Glass 设计系统
  • design-system — 设计系统最佳实践

后端类：

  • backend-patterns — API、数据库、缓存模式
  • api-design — REST API 设计（分页、错误响应）
  • database-migrations — Prisma/Drizzle/Django/Go 迁移
  • postgres-patterns — PostgreSQL 优化
  • database-reviewer — 数据库审查

框架专项：

  • django-patterns / django-security / django-tdd / django-verification
  • laravel-patterns / laravel-security / laravel-tdd / laravel-verification
  • springboot-patterns / springboot-security / springboot-tdd / springboot-verification
  • nestjs-patterns
  • nextjs-turbopack
  • bun-runtime

语言专项：

  • golang-patterns / golang-testing
  • python-patterns / python-testing
  • java-coding-standards / jpa-patterns
  • kotlin-coroutines-flows / kotlin-ktor-patterns
  • cpp-coding-standards / cpp-testing
  • rust-patterns / rust-testing
  • swift-actor-persistence / swift-protocol-di-testing / swift-concurrency-6-2
  • dart-flutter-patterns
  • perl-patterns / perl-security / perl-testing

运营/平台类：

  • deployment-patterns — CI/CD、Docker、健康检查、回滚
  • docker-patterns — Docker Compose、网络、卷、安全
  • e2e-testing — Playwright E2E 和 Page Object Model
  • jira-integration — JIRA 集成
  • github-ops — GitHub 操作自动化

LLM/AI 类：

  • search-first — 研究优先的工作流
  • cost-aware-llm-pipeline — LLM 成本优化、模型路由
  • continuous-agent-loop — 自主 Agent 循环模式
  • mcp-server-patterns — MCP 服务器集成模式

内容/媒体类：

  • article-writing — 品牌声音一致的长文写作
  • content-engine — 多平台社交内容复用工作流
  • market-research — 市场/竞品/投资研究
  • investor-materials — 路演 Deck、备忘录、财务模型
  • investor-outreach — 个性化融资外联
  • manim-video — 数学动画视频生成
  • remotion-video-creation — React 式视频创作
  • videodb — 视频/音频摄取、搜索、编辑、生成

安全类：

  • security-review — 安全检查清单
  • security-scan — AgentShield 安全审计集成
  • defi-amm-security — DeFi AMM 安全
  • hipaa-compliance — 医疗 PHI 合规
  • customs-trade-compliance — 贸易合规
  • agent-payment-x402 — x402 支付协议

6.3 安装 everything-claude-code

方式一：通过插件安装（推荐）

# 添加 marketplace
/plugin marketplace add https://github.com/affaan-m/everything-claude-code

# 安装插件
/plugin install everything-claude-code@everything-claude-code

注意：ECC 有三个公开标识符，它们不可互换：

  • GitHub 仓库：affaan-m/everything-claude-code
  • Claude marketplace/plugin 标识符：everything-claude-code@everything-claude-code
  • npm 包：ecc-universal

方式二：通过 OSS 安装脚本（最可靠）

# 克隆仓库
git clone https://github.com/affaan-m/everything-claude-code.git ~/everything-claude-code
cd ~/everything-claude-code

# macOS/Linux：安装所有（完整模式）
./install.sh --profile full

# macOS/Linux：只安装特定语言
./install.sh typescript
./install.sh python golang swift php

# 指定目标 harness
./install.sh --target cursor typescript
./install.sh --target gemini --profile full

# Windows PowerShell
.\install.ps1 --profile full
.\install.ps1 typescript python golang swift php

方式三：通过 npm（ECC Tools）

# 安装 ECC 命令行工具
npm install -g ecc-universal

# 初始化
npx ecc-install typescript

# 检查已安装组件
npx ecc list-installed

# 诊断问题
npx ecc doctor
npx ecc repair

6.4 安装后验证

# 查看已安装的组件
npx ecc list-installed

安装完成后，你拥有：

  • 38 个 Agent
  • 156 个 Skill
  • 72 个命令别名

6.5 ECC Dashboard GUI

ECC 带有一个 Tkinter 桌面应用，可视化管理所有组件：

npm run dashboard
# 或
python3 ./ecc_dashboard.py

功能：

  • Tab 化界面：Agents、Skills、Commands、Rules、Settings
  • 暗黑/明亮主题切换
  • 字体自定义
  • 全文搜索和过滤

6.6 规则安装（必须手动）

⚠️ 重要： Claude Code 插件无法自动分发 rules，必须手动安装。

# 复制语言无关规则
cp -r rules/common ~/.claude/rules/

# 复制特定语言规则
cp -r rules/typescript ~/.claude/rules/
cp -r rules/python ~/.claude/rules/
cp -r rules/golang ~/.claude/rules/

注意： 复制整个目录而不是单独文件，这样相对引用才能正常工作。

6.7 使用技能和命令

ECC 主推的命名方式（插件安装后）：

/ecc:plan "Add user authentication"
/ecc:tdd "implement login feature"
/ecc:security-scan

传统斜杠命令（手动安装后）：

/plan "Add user authentication"
/tdd "implement login feature"

查看可用命令：

/plugin list everything-claude-code@everything-claude-code

6.8 多 Agent 编排命令（需额外设置）

multi-* 命令需要额外安装 ccg-workflow 运行时：

npx ccg-workflow

支持：

  • /multi-plan — 多 Agent 任务分解
  • /multi-execute — 编排多 Agent 工作流
  • /multi-backend — 后端多服务编排
  • /multi-frontend — 前端多服务编排
  • /multi-workflow — 通用多服务工作流

6.9 Hook 运行时控制

ECC 提供了可调节的 Hook 严格程度配置：

# 设置 Hook 严格程度（default: standard）
export ECC_HOOK_PROFILE=standard  # minimal | standard | strict

# 禁用特定 Hook
export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"

七、常用命令速查

7.1 核心开发命令

命令 功能
/plan <task> 分解任务为实现步骤
/tdd <feature> 测试驱动开发流程
/code-review 启动代码审查
/build-fix 修复构建错误
/refactor-clean 清理死代码
/e2e 生成并运行 E2E 测试

7.2 学习与记忆命令

命令 功能
/learn 从当前会话提取模式
/learn-eval 提取、评估、保存模式
/checkpoint 保存验证状态
/verify 运行验证循环
/instinct-status 查看已学习的 Instinct
/instinct-import 导入 Instinct
/instinct-export 导出 Instinct
/evolve 将 Instinct 聚合成 Skill

7.3 多 Agent 编排命令

命令 功能
/orchestrate 多 Agent 协调
/multi-plan 多 Agent 任务分解
/multi-execute 多 Agent 执行
/pm2 PM2 服务生命周期管理
/sessions 会话历史管理

7.4 工具与质量命令

命令 功能
/eval 按标准评估
/test-coverage 测试覆盖率分析
/update-docs 更新文档
/update-codemaps 更新代码地图
/security-scan 运行安全扫描（AgentShield）

7.5 开发与调试命令

命令 功能
/sessions 会话历史管理
/skill-create 从 Git 历史生成 Skill
/setup-pm 配置包管理器
/hookify 创建自定义 Hook
/hookify:list 列出所有 Hook
/hookify:configure 配置 Hook

八、包管理器自动检测

ECC 会自动检测你的首选包管理器，优先级如下：

  1. 环境变量：CLAUDE_PACKAGE_MANAGER
  2. 项目配置：.claude/package-manager.json
  3. package.json：packageManager 字段
  4. 锁文件：package-lock.json / yarn.lock / pnpm-lock.yaml / bun.lockb
  5. 全局配置：~/.claude/package-manager.json
  6. 回退：自动选择首个可用的包管理器

手动设置：

# 通过环境变量
export CLAUDE_PACKAGE_MANAGER=pnpm

# 通过全局配置
node scripts/setup-package-manager.js --global pnpm

# 通过项目配置
node scripts/setup-package-manager.js --project bun

# 查看当前设置
node scripts/setup-package-manager.js --detect

九、Claude Code 进阶技巧

9.1 项目级 CLAUDE.md

在项目根目录创建 CLAUDE.md，其中的内容会在每次会话自动加载：

# 项目说明

## 技术栈
- 前端：React 18 + TypeScript + Tailwind CSS
- 后端：Node.js + Express + PostgreSQL
- 构建：Vite + pnpm

## 代码规范
- 使用 ESLint + Prettier
- 所有 API 必须有 TypeScript 类型
- 测试覆盖率不低于 80%

## Git 工作流
- commit message 格式：`type: description`
- 合并前必须通过所有 CI 检查

9.2 安全 Hook 自动检查

ECC 的 security-guidance 插件会在编辑文件前自动检查：

  • 命令注入风险
  • XSS 漏洞
  • eval() 使用
  • 危险 HTML 生成
  • pickle 反序列化
  • os.system 调用

9.3 TTY 无头环境运行

Claude Code 依赖 TTY 交互，在无头服务器环境：

# 模拟 TTY
script -q -c "claude --print 'say hello'" /dev/null

对于真正的无头环境，建议使用 OpenClaw 这类 headless Agent 平台。

9.4 与 OpenClaw 的协同

Claude Code 适合：

  • 交互式 TTY 环境
  • 需要反复调试的复杂任务
  • IDE 深度集成场景

OpenClaw 适合：

  • 服务器/无头环境
  • 多工具链统一调度
  • 多 Agent 并行工作
  • 长时间自动化任务

两者可以协同使用：OpenClaw 做任务规划和调度，Claude Code 处理需要深度 TTY 交互的调试任务。

十、OpenClaw 对比 Claude Code

维度 OpenClaw Claude Code
运行环境 Headless 服务器友好 需要 TTY 交互
工具链 exec/browser/message/cron 统一 主要 Bash + 文件操作
多 Agent 原生支持子 Agent 和编排 通过插件支持
记忆系统 内置 daily memory + long-term 通过 Hook 手动配置
模型支持 OpenClaw provider + OpenRouter Anthropic/Bedrock/Vertex/Foundry
插件生态 技能系统（SKILL.md） 插件系统（plugin.json）
上下文窗口 按需加载，节省 token 自动压缩
学习系统 内置 self-improvement 技能 continuous-learning 插件
适用场景 服务器自动化、多工具集成 日常交互式开发

十一、常见问题

Q1: Claude Code 在无头环境无法启动？

Claude Code 需要 TTY，可以通过 script -q -c "claude" /dev/null 模拟。若需要纯 headless 能力，建议使用 OpenClaw。

Q2: API Key 应该写在哪里？

绝对不要写入 settings.json。正确做法：

export ANTHROPIC_API_KEY="sk-ant-xxxxx"  # 环境变量（推荐）

或 .env 文件 + .gitignore。

Q3: 插件安装后命令找不到？

确认安装正确：

/plugin list everything-claude-code@everything-claude-code

如果规则没生效，手动复制 rules 目录到 ~/.claude/rules/。

Q4: 模型切换不生效？

检查配置优先级：命令行参数 > Local > Project > User。确保没有更高优先级的配置覆盖。

Q5: 多语言项目应该安装哪些规则？

./install.sh typescript python golang

只安装你实际使用的语言规则，不要装全部。

Q6: ECC 安装后想要更新？

cd ~/everything-claude-code && git pull origin main
./install.sh --profile full  # 重新应用

ECC Tools 用户：npx ecc update。

十二、总结

Claude Code 配合 everything-claude-code 是目前最强的终端编程组合之一：

  • 🤖 Claude Code — 官方出品的 Agentic 编程工具，多端支持（Terminal/Desktop/VS Code/JetBrains）
  • 📦 everything-claude-code — 16万星最佳实践库，38个Agent + 156个Skill，开箱即用
  • 🔧 OpenClaw — Claude Code 的有力补充，适合服务器/无头场景和多工具链集成

两者结合使用，可以让 AI 编程能力覆盖从日常交互开发到服务器自动化部署的完整场景。

本文部分内容参考自 https://github.com/anthropics/claude-code 和 https://github.com/affaan-m/everything-claude-code，配置方式以 2026年4月官方最新文档为准。

site logo

Moment

© 2026 Moment