Claude Code 完全上手指南：从入门配置到高级自动化工作流

Claude Code：终端中的智能开发代理

Antrópica 推出的命令行工具 Claude Code 并非又一个聊天窗口或 IDE 插件，而是一个原生集成在终端环境的开发代理。它能理解项目结构，读写文件，执行命令，甚至协调多个子代理 (Sub-Agents) 完成复杂任务，旨在将 AI 深度融入开发者的核心工作流。

对于习惯在终端中操作的开发者而言，Claude Code 提供了一种与 GitHub Copilot 等工具不同的交互模式。Copilot 的优势在于其无缝的 IDE 集成和行级代码的快速补全，它更像一个“结对程序员”，优化的是“写”的环节。而 Claude Code 则更像一个“项目主管”，它的阵地在 Shell 中，关注的是更高层级的任务规划与执行，擅长处理需要跨文件理解和重构的复杂问题。

Principais recursos

• 原生终端集成: 无需离开终端即可完成代码生成、调试、命令执行等操作。这种设计哲学对于依赖脚本和命令行自动化工作流的开发者极具吸引力。
• Comandos de barra personalizados: 将常用的工作流封装成一键式命令，实现高度自动化。
• Sub-Agents 协作: 支持创建具备不同职责和权限的专用子代理，由主代理统一协调，适合处理代码审查、测试生成等多阶段任务。
• 强大的项目控制力: 通过命令白名单、代理配置 (Proxy)、钩子 (Hooks) 插件机制和模型上下文协议 (MCP) 扩展，提供了精细的控制粒度。
• SDK 与系统集成: Fornecido TypeScript responder cantando Python SDK，支持非交互式调用和深度定制。

在国内环境使用

começar a usar Claude Code 前，需确保环境中已安装 Node.js 18 或更高版本，随后通过 npm Instalação global:

npm install -g @anthropic-ai/claude-code

安装后，在终端输入 claude 即可启动。首次运行时，系统会提示用户通过 /login 命令进行登录和订阅。

devido a Claude 的注册和支付流程在国内存在障碍，用户可以考虑以下两种替代方案来配置和使用 Claude Code.

1. 使用 Kimi (月之暗面) API

O lado escuro da lua (Moonshot AI) 提供的 API 兼容 Claude Code 的输入输出格式。用户可以在其开放平台申请 API Key，并通过配置环境变量来指定 API 端点和认证令牌：

export ANTHROPIC_BASE_URL="https://api.moonshot.cn/anthropic" && export ANTHROPIC_AUTH_TOKEN="sk-******"

配置完成后，Claude Code 即可正常使用。

2. 搭建本地代理服务

claude-code-proxy 是一个开源的 Python 项目，它能将任何与 OpenAI 兼容的 API 转换为 Claude Code 可用的接口。

本地运行与配置步骤::

1. 下载项目并安装依赖：uv sync
2. 创建并修改配置文件：cp .env.example .env. Em .env Preencher o arquivo OpenAI 兼容的 API Key responder cantando Base URL，并指定不同任务复杂度下对应的模型。

   OPENAI_API_KEY="sk-your-openai-key"
   OPENAI_BASE_URL="https://api.openai.com/v1"
   BIG_MODEL="gpt-4o"          # 对应 'claude-3-opus'
   MIDDLE_MODEL="gpt-4o"       # 对应 'claude-sonnet-4'
   SMALL_MODEL="gpt-4o-mini"   # 对应 'claude-3.5-haiku'
   

3. 启动本地服务：uv run claude-code-proxy，服务默认运行在 8082 端口。
4. 配置环境变量，将 Claude Code 的请求指向本地代理。AUTH_TOKEN 可设置为任意字符，以绕过登录提示。

   export ANTHROPIC_BASE_URL="http://localhost:8082" 
   export ANTHROPIC_AUTH_TOKEN="anything"
   

5. Execute-o em um terminal claude Pronto para começar.

Funções principais em detalhes

Claude Code 作为一个 Agent，具备自主规划任务、调用工具和协调 Sub-Agent 的能力。它会根据任务需要，在获得用户授权后，读取相关文件，构建完成任务所需的上下文。

权限配置与安全考量

权限配置的目标是在自动化效率与系统安全之间取得平衡。Claude Code 允许执行任意 Shell 命令，这意味着失控的 AI 可能会导致数据丢失、系统损坏甚至数据泄露。

一个显著的风险是提示注入攻击 (Prompt Injection)。攻击者可以将恶意指令隐藏在代码注释、文档甚至网页内容中。当 Claude Code 读取这些外部信息时，恶意指令就可能被执行，诱使其泄露敏感信息或执行危险操作。

为控制风险，Claude Code 提供了精细的权限管理机制。用户可以手动编辑项目级 .claude/settings.json 或用户级 ~/.claude.json 文件来配置权限：

{
"skipPermissions": false,
"allowedTools": ["read", "write"],
"allowCommands": ["node ./scripts/setup.js"],
"denyCommands": ["rm -rf /", "curl http://*"]
}

• skipPermissions: 是否跳过每一步的人工确认。
• allowedTools: 允许 Claude 使用的工具白名单。
• allowCommands/denyCommands: 更精细的命令级白名单和黑名单。

对于修复 lint 错误这类低风险批量任务，可以使用 --dangerously-skip-permissions 标志跳过所有权限检查。但强烈建议在没有网络访问的容器环境（如 Docker Dev Containers）中使用此模式，以隔离潜在风险。

此外，还可以在交互界面中使用 /permissions 命令动态调整当前会话的权限。

Gerenciamento de memória

通过名为 CLAUDE.md 的记忆文件，Claude Code 可以在不同会话间保持对项目背景、编码规范、个人偏好等信息的记忆。记忆文件分为企业级、用户级和项目级，加载时层层叠加，形成完整的上下文。

在交互窗口中输入 # 即可触发记忆创建。使用 /init comando.Claude Code 能自动扫描代码库并生成一个包含项目概述的 CLAUDE.md 文件。通过 /memory 命令则可以对记忆进行编辑和查看。

CLAUDE.md 文件支持使用 @path/to/file 语法导入其他文件的内容，方便引用 README 或配置文件等已有信息。

Comandos de barra personalizados

斜杠命令是将常用的提示语 (Prompt) 工程化的快捷方式。用户可以将任务指令写成 Markdown 文件，存放在特定目录，Claude Code 会自动将其识别为可调用的命令。

• 存放位置:
  • 项目级: .claude/commands/ (调用: /project:命令名)
  • 用户级: ~/.claude/commands/ (调用: /user:命令名)
• 参数传入:
  • fazer uso de $ARGUMENTS 占位符接收命令后的所有参数。

一个创建 Hugo 文章的命令示例 (.claude/commands/posts/new.md):

---
description: 创建一篇新的 Hugo 文章
argument-hint: [title]
model: haiku
---
创建一篇文章，标题为 $ARGUMENTS：
# 文章要求
1.  生成 kebab-case 格式的文件名 (格式: YYYY-MM-DD-标题.md)。
2.  使用 Hugo 命令创建新文件: `hugo new content`。
3.  更新文件的 Front Matter，包含标题、日期和描述。
4.  告诉我预览网站的命令。
# 偏好设置：
文章风格需风趣幽默、通俗易懂。

在终端调用 /project:posts:new 介绍 GPT-5(matemática) gênero介绍 GPT-5 这部分内容就会替换掉 $ARGUMENTS，驱动 Claude 执行定义好的任务流。

自定义 Sub-Agents

Sub-Agents 是专用的子代理，每个都有独立的系统提示、上下文窗口和工具权限，用于处理特定领域的任务。这种设计可以将复杂任务分解，让主对话聚焦于高层目标，而将具体执行细节委托给专家子代理。

Sub-Agents 的配置文件同样是 Markdown 格式，存放在 .claude/agents/ (项目级) 或 ~/.claude/agents/ (用户级) 目录下。用户可以通过 /agents 命令引导式地创建子代理，定义其名称、描述、可用工具和模型。

生成的子代理配置文件 (.claude/agents/product-prd-expert.md) 示例：

---
name: product-prd-expert
description: 当需要根据用户规格创建专业的产品需求文档 (PRD) 时使用此代理。
tools: Grep, LS, Edit, Write
model: sonnet
color: red
---
You are a senior product manager with 10+ years of experience...

当用户的需求与 description 字段匹配时，Claude Code 会自动调用该子代理。用户也可以通过 使用 product-prd-expert 来生成产品需求 这样的指令来显式调用。

comando básico

Claude Code 提供了一系列命令来简化日常操作：

自定义钩子 (Hooks)

钩子是用户定义的 Shell 命令，它们在 Claude Code 生命周期的特定事件点执行，提供了一种对 Claude 行为进行确定性控制的方式。

• cenário do aplicativo:
  • notificações: Em Claude 等待输入或请求权限时，通过系统通知提醒用户。
  • reformatar: 每次文件编辑后自动运行 Prettier talvez gofmt.
  • 日志与审计: 记录所有执行的命令以供合规性检查。

aprovar (um projeto de lei ou inspeção etc.) /hooks 命令可以为不同的事件（如 PreToolUseePostToolUseeNotification）注册钩子。例如，为 Notification 事件创建一个 macOS 弹窗通知：

1. estar em movimento /hooks e selecione Notification 事件。
2. 输入 Shell 命令: msg=$(jq -r '.message'); osascript -e "display alert \"Claude Code 通知\" message \"$msg\""。这里使用 jq 工具从 Claude 传递的 JSON 标准输入中提取 message Campos.
3. 选择钩子的作用域（如 local），配置会保存在 .claude/settings.local.json Médio.
4. reabrir Claude Code 使钩子生效。

Hook MCP 工具

Claude Code 的钩子可以与模型上下文协议 (MCP) 工具无缝协作。MCP 工具遵循 mcp__<server>__<tool> 的命名模式，可以在钩子中通过 matcher 字段进行匹配。

Exemplo de configuração:

{
"hooks": {
"PreToolUse": [
{
"matcher": "mcp__memory__.*",
"hooks": [
{
"type": "command",
"command": "echo 'Memory operation initiated' >> ~/mcp-operations.log"
}
]
},
{
"matcher": "mcp__.*__write.*",
"hooks": [
{
"type": "command",
"command": "/home/user/scripts/validate-mcp-write.py"
}
]
}
]
}
}

使用 MCP 工具

通过模型上下文协议 (Modelo de protocolo de contexto, MCP)，Claude Code 可以连接到外部工具和数据源，如 AirtableeNotioneGitHub etc.

添加本地 stdio 服务器

# 基本语法
claude mcp add <name> <command> [args...]
# 实际示例：添加 Airtable 服务器
claude mcp add airtable --env AIRTABLE_API_KEY=YOUR_KEY \
-- npx -y airtable-mcp-server

-- (双破折号) 用于分隔 Claude 自身的标志和传递给 MCP 服务器的命令。

添加远程 SSE 服务器

# 基本语法
claude mcp add --transport sse <name> <url>
# 实际示例：连接到 Linear
claude mcp add --transport sse linear https://mcp.linear.app/sse

添加远程 HTTP 服务器

# 基本语法
claude mcp add --transport http <name> <url>
# 实际示例：连接到 Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

管理 MCP 服务

# 列出所有配置的服务器
claude mcp list
# 获取特定服务器的详细信息
claude mcp get github
# 删除服务器
claude mcp remove github

安装范围

fazer uso de --scope 标志可以指定配置的存储位置：local (默认，仅当前项目)、project (por meio de .mcp.json 与团队共享)、user (跨所有项目可用)。

Claude Code SDK 集成

对于非交互式场景，Claude Code ofertas TypeScript responder cantando Python SDK。SDK 本质上是对其命令行功能的封装，允许开发者在自己的应用程序中调用 Claude Code A capacidade do

seguintes Python SDK 的基本使用示例：

import asyncio
from claude_code_sdk import (
AssistantMessage,
ClaudeCodeOptions,
ClaudeSDKClient,
UserMessage,
)
async def interact_with_claude():
# 配置客户端选项
options = ClaudeCodeOptions(
model="claude-3-5-sonnet-20241022",
system_prompt="你是一个专业的软件开发助手",
allowed_tools=["Bash", "Read", "Edit"],
permission_mode="acceptEdits" # 自动接受文件编辑权限
)
# 创建客户端实例
async with ClaudeSDKClient(options=options) as client:
# 发送消息
await client.query("帮我检查项目中的潜在 bug")
# 接收和处理响应
async for message in client.receive_messages():
if isinstance(message, AssistantMessage):
print(f"Claude: {message.content}")
if __name__ == "__main__":
asyncio.run(interact_with_claude())

consulta

1. Claude Code官方文档 – https://docs.anthropic.com/en/docs/claude-code/
2. Siddharth Bharath的Claude Code完全指南 – https://www.siddharthbharath.com/claude-code-the-complete-guide/
3. Fuszti的Claude Code设置指南 – https://fuszti.com/claude-code-setup-guide-2025/
4. Claude Code常见工作流程 – https://docs.anthropic.com/en/docs/claude-code/common-workflows
5. Claude Code SDK文档 – https://docs.anthropic.com/en/docs/claude-code/sdk
6. 企业代理设置 – https://docs.anthropic.com/en/docs/claude-code/corporate-proxy