Claude Code 入门

Claude Code 入门

基础概念

Claude Code 是 Anthropic 官方出品的 agentic 编码工具，常驻在你的终端里，直接读你的代码、改你的文件、跑你的命令、和你的开发工具链协同。它不是一个聊天机器人，也不是一个传统的命令行工具，而是一个会自己「拿主意」的 Agent——你给它一个目标，它会自己决定要看哪些文件、跑哪些命令、改哪些代码，遇到错误自己调整方向，直到任务做完。

要理解 Claude Code 跟 Claude Desktop、Claude API 的差别，先看清楚它的定位：

• Claude Desktop / claude.ai：是「聊天界面」，给 Claude 一个友好的窗口让你和它对话。它看不到你电脑上的文件，也不能直接帮你改代码。
• Claude API / Anthropic SDK：是「模型接口」，给开发者写代码用，原生只暴露大模型的 chat completion 能力，工具调用、上下文管理、安全控制都得你自己写。
• Claude Code：是 agentic harness（Agent 外壳），把 Claude 模型 + 一整套工具 + 上下文管理 + 权限沙箱 + 会话持久化打包成「可以在你电脑上自主工作的 Agent」。它是一个完整的可执行程序（claude 命令），开箱即用。

官方对自己的描述是「an agentic coding tool that reads your codebase, edits files, runs commands, and integrates with your development tools」。它的核心循环非常清楚：拿到任务 → 收集上下文 → 执行动作 → 验证结果 → 不行就再循环，直到任务完成。

命名澄清：本卡涉及的官方名称统一是 Claude Code（不是 "Claude CLI"、"claude-code-cli"、"Anthropic CLI"，这些都是社区里的口语叫法）。它的可执行命令是 claude，配置目录是 ~/.claude/。

核心能力一览

Agentic 循环示意

下面这张图说明了 Claude Code 拿到一个任务之后内部到底在做什么——循环不是一根直线，而是反复调工具、反复验证的闭环：

同源不同形：CLI / IDE / Desktop / SDK 的关系

下面这张图说明了为什么本卡反复强调「Claude Code 是 harness、不是模型」——Anthropic 的所有 Claude 形态其实是同一个内核的不同外壳：

注意右下两个虚线：Claude API 和 Claude Desktop（聊天版）是直接套在模型上的，不经过 harness——这就是为什么它们没有文件读写、没有 Bash 执行、没有 agentic 循环。Claude Code、IDE 插件、Desktop App、Web、Agent SDK 都共享同一套 harness，所以你的 CLAUDE.md、settings、MCP server、Skills 在它们之间无缝复用。

它和"传统 CLI 工具"差在哪

绝大多数命令行工具（grep、make、docker 等）都是确定性程序——你输入什么参数，它就执行什么动作。Claude Code 不是这样：你给它一个自然语言目标，它自己决定调用哪些工具、调用顺序、什么时候停下来。这是它被叫做 "Agent" 的本质区别。它更像是一个会用 shell 的实习生，而不是一个 shell 命令。

它和"IDE 插件版"差在哪

Anthropic 同时还出了 VS Code、JetBrains、Desktop App 几个版本的 Claude Code。底层 agent 引擎是同一个——共享 CLAUDE.md、settings、MCP server 配置——只是 UI 外壳不同：

• CLI：纯终端，适合 SSH 远程开发、写 shell 脚本管道、跑在 CI 里
• IDE 插件：可视化 diff 审查、行内 @-mention、对话历史侧栏
• Desktop App：跨会话并行、视觉 diff 审查、定时任务调度

CLI 是最原始、最灵活的形态。本 wiki 的所有卡片默认讨论的是 CLI 形态。

基础用法

安装

官方推荐使用 native installer（2026 年起 npm 版已被标记为 deprecated，但仍可用）：

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

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

# macOS 用 Homebrew 也可以
brew install --cask claude-code        # 稳定通道
brew install --cask claude-code@latest # 最新通道

native installer 装好之后会自动后台更新，省去手动升级的烦恼。Homebrew、WinGet 安装的不会自动更新，需要定期 brew upgrade claude-code 或 winget upgrade Anthropic.ClaudeCode。

历史 npm 安装方式 npm install -g @anthropic-ai/claude-code 仍然可用，但官方文档已经不再推荐，主要保留给企业内 npm 镜像场景。

登录

第一次跑 claude 时会要求登录。账号体系有三种：

1. Claude Pro / Max / Team / Enterprise 订阅账号（推荐，最简单）
2. Anthropic Console 账号 + 预付费 credits（按 token 计费）
3. Amazon Bedrock / Google Vertex AI / Microsoft Foundry（企业云接入）

claude          # 第一次启动会自动弹出登录流程
/login          # 已登录后想切账号用这个 slash 命令

凭证会缓存在系统 keychain 里，下次不用再登。

第一次会话

走一个最小可运行示例：进项目目录、起会话、让它写一个文件并验证。

cd ~/playground/my-app
claude

进入交互界面之后，直接用自然语言下指令：

你：在项目根目录创建一个 hello.py，里面定义一个函数 say_hi()，
    打印 "Hello from Claude Code"，然后跑一下确认能输出。

Claude：[调用 Write 工具：写入 hello.py]
Claude：[调用 Bash 工具：python hello.py]
Claude：已经创建 hello.py 并验证输出：
        Hello from Claude Code
        需要我帮你加测试或者写 README 吗？

注意几个细节：

• 写文件前 Claude 会先弹出 diff 让你确认（除非你切到 Auto-accept edits 模式）
• 跑 Bash 前会先问你是否允许（除非你预先在 settings.json 里 allow 过这条）
• 每次文件修改都会自动快照，按 Esc 双击就能回滚到上一个状态——这是 git 之外的另一道安全网

常用命令速查

配置一个最小的 settings.json

settings 分四层（Managed → 命令行 → Local → Project → User，前者覆盖后者）。最常用的是 user 级（~/.claude/settings.json）和 project 级（.claude/settings.json，可以提交到 git）。

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Read(./src/**)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Bash(curl *)"
    ]
  },
  "hooks": {
    "on-session-start": { "command": "~/.claude/hooks/welcome.sh" }
  }
}

这段配置做了三件事：固定模型、给常用命令开绿灯（避免每次问你）、阻断对 .env 的读取以防泄密、会话开始时跑一个钩子脚本（典型场景：拉一下当天的 PR 列表打印到终端）。

同类工具对比

「同类」这里指的是 Anthropic 自家的几种使用 Claude 的方式——它们后端用的可能是同一批模型，但形态完全不同，选哪个取决于你的使用场景。

核心区别一句话

• Claude Code = 给你一个开箱即用的 Agent，跑在你电脑的终端里
• Claude Desktop = 给你一个聊天界面，对话场景为主
• Claude API = 给你模型接口，工具/循环/安全你自己造
• Claude Agent SDK = 给你 Claude Code 同款引擎的编程接口，让你把 Agent 嵌进自己的程序里

很多人会把 Claude Code 和 Claude Agent SDK 搞混。它们其实是同一套底座的两副面孔：Claude Code 是直接交付给最终用户用的 CLI，Claude Agent SDK 是把同一套 agentic harness（工具集、上下文管理、权限模型、子 Agent 调度）暴露成 API 让开发者重新组合。如果你只是想用，装 Claude Code；如果你想造一个属于自己的 Agent 产品，用 Claude Agent SDK。

常见误区

优劣势分析

思考题

参考资料

1. Claude Code 官方主页与 Overview：https://code.claude.com/docs/en/overview（查询日期 2026-04-22）
2. Claude Code Quickstart：https://code.claude.com/docs/en/quickstart（查询日期 2026-04-22）
3. How Claude Code Works（agentic 循环、内置工具分类）：https://code.claude.com/docs/en/how-claude-code-works（查询日期 2026-04-22）
4. Settings 配置参考（含 permissions / hooks / mcp）：https://code.claude.com/docs/en/settings（查询日期 2026-04-22）
5. Claude Code GitHub 仓库（issue / release / 117k+ star）：https://github.com/anthropics/claude-code（查询日期 2026-04-22）
6. Claude Code Changelog（官方）：https://code.claude.com/docs/en/changelog（查询日期 2026-04-22）
7. Claude Agent SDK Overview（与 Claude Code 同根的编程接口）：https://code.claude.com/docs/en/agent-sdk/overview（查询日期 2026-04-22）
8. Model Context Protocol 官方站（与 Claude Code 互链）：https://modelcontextprotocol.io/（查询日期 2026-04-22）