通俗版 Claude Code 文档

结构照原 docs，内容改成真能照着做的人话版。
查看原始文档 目录顺序与官方保持一致

Agent SDK

快速上手

快速上手 这一页讲的，就是 快速上手 这件事在 Claude Code 里到底怎么用。

页面信息

对应原页

Quickstart

页面性质

第三方中文解释页

使用建议

先看人话解释，再对照原页命令和代码

这页不是官方原文，而是顺着官方文档结构做的中文解释版。命令、参数、配置名这些硬东西尽量保留，解释部分则尽量讲成人能照着做的话。

如果你碰到特别敏感的配置、权限或企业环境差异，最好顺手点上面的“查看原始文档”再核一遍。

这一页先讲明白

这页主要讲 Quickstart：Get started with the Python or TypeScript Agent SDK to build AI agents that work autonomously

你可以把它当成"Agent SDK"这块里专门管这一摊事的说明书。

你可以把"Quickstart"理解成 Agent SDK 这一栏里的一把专门工具。这页不是让你背书，而是教你什么时候该把这把工具拿出来。

原文这页大多会按 Prerequisites、Setup、Create a buggy file、Build an agent that finds and fixes bugs 这些环节往下讲。

翻成人话，大概就是：Create a buggy file

第一，先别一上来全开全配。先按最小一步试通，确认没跑偏，再继续往下加。

第二，命令、配置名、参数名这些硬东西尽量保留原样。人话解释是帮你听懂，不是帮你改关键字。

第三，照着原文这几个环节挨个过：Prerequisites -> Setup -> Create a buggy file -> Build an agent that finds and fixes bugs。像下地先看水路、再试机器、再正式开干，一步一步最稳。

终端里敲

原页关键片段：Setup 1

看到这里，别光点头，下面这条命令先跑起来再说。

mkdir my-agent && cd my-agent
终端里敲

原页关键片段：Setup 2

看到这里，别光点头，下面这条命令先跑起来再说。

npm install @anthropic-ai/claude-agent-sdk
终端里敲

原页关键片段：Setup 3

看到这里，别光点头，下面这条命令先跑起来再说。

uv init && uv add claude-agent-sdk
关键片段

原页关键片段：Create a buggy file

先看下面这块原始片段，等会儿再回头看解释会顺得多。

def calculate_average(numbers):
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)


def get_user_name(user):
    return user["name"].upper()
关键片段

原页关键片段：Build an agent that finds and fixes bugs

下面这块是这一段最值钱的原文样板，先对着看一眼。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage


async def main():
    # Agentic loop: streams messages as Claude works
    async for message in query(
        prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],  # Tools Claude can use
            permission_mode="acceptEdits",  # Auto-approve file edits
        ),
    ):
        # Print human-readable output
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)  # Claude's reasoning
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")  # Tool being called
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")  # Final result


asyncio.run(main())
关键片段

原页关键片段：Run your agent 1

先看下面这块原始片段，等会儿再回头看解释会顺得多。

python3 agent.py
终端里敲

原页关键片段：Run your agent 2

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

npx tsx agent.ts
关键片段

原页关键片段：Customize your agent 1

"Customize your agent"这一段里最要紧的原始写法在下面，先看它怎么落地。

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "WebSearch"], permission_mode="acceptEdits"
)
关键片段

原页关键片段：Customize your agent 2

"Customize your agent"这一段里最要紧的原始写法在下面，先看它怎么落地。

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob"],
    permission_mode="acceptEdits",
    system_prompt="You are a senior Python developer. Always follow PEP 8 style guidelines.",
)
关键片段

原页关键片段：Customize your agent 3

"Customize your agent"这一段里最要紧的原始写法在下面，先看它怎么落地。

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "Bash"], permission_mode="acceptEdits"
)
关键片段

原页关键片段：API error thinking.type.enabled is not supported for this model

这一段要真抓重点，通常就抓下面这块原文。

API Error: 400 {"type":"invalid_request_error","message":"\"thinking.type.enabled\" is not supported for this model. Use \"thinking.type.adaptive\" and \"output_config.effort\" to control thinking behavior."}

预留广告位

正文中段响应式广告 等你后面真接 AdSense，这里再放正式广告。

Documentation Index

这里不是让你背"Documentation Index"这个词，而是让你看它真干活时怎么使。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

Prerequisites

这一块主要是在说"Prerequisites"真到手上该怎么用，哪里最容易踩坑。

Setup

这一段是在教你把 a project folder 真正建出来。文件放哪儿、字段怎么写、建完怎么验，都得跟着看。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

终端里敲

Setup 1

看到这里，别光点头，下面这条命令先跑起来再说。

mkdir my-agent && cd my-agent
终端里敲

Setup 2

看到这里，别光点头，下面这条命令先跑起来再说。

npm install @anthropic-ai/claude-agent-sdk
终端里敲

Setup 3

看到这里，别光点头，下面这条命令先跑起来再说。

uv init && uv add claude-agent-sdk
终端里敲

Setup 4

看到这里，别光点头，下面这条命令先跑起来再说。

python3 -m venv .venv && source .venv/bin/activate
pip3 install claude-agent-sdk
关键片段

Setup 5

"Setup"这一段里最要紧的原始写法在下面，先看它怎么落地。

ANTHROPIC_API_KEY=your-api-key

Create a buggy file

别把这段只当成标题看，它其实是在给"Create a buggy file"划边界。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

关键片段

Create a buggy file

先看下面这块原始片段，等会儿再回头看解释会顺得多。

def calculate_average(numbers):
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)


def get_user_name(user):
    return user["name"].upper()

Build an agent that finds and fixes bugs

这一段是在教你把 agent.py if you’re using the Python SDK, or agent.ts for TypeScript: 真正建出来。文件放哪儿、字段怎么写、建完怎么验，都得跟着看。

看这段时要特别盯工具和权限边界，别为了省事一把全开。

关键片段

Build an agent that finds and fixes bugs

下面这块是这一段最值钱的原文样板，先对着看一眼。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage


async def main():
    # Agentic loop: streams messages as Claude works
    async for message in query(
        prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],  # Tools Claude can use
            permission_mode="acceptEdits",  # Auto-approve file edits
        ),
    ):
        # Print human-readable output
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)  # Claude's reasoning
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")  # Tool being called
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")  # Final result


asyncio.run(main())

Run your agent

看到这里，就把"Run your agent"当成一件真要上手的活来看。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

终端里敲

Run your agent

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

npx tsx agent.ts

Try other prompts

这里不是让你背"Try other prompts"这个词，而是让你看它真干活时怎么使。

看这段时要特别盯工具和权限边界，别为了省事一把全开。

Customize your agent

这一块主要是在说"Customize your agent"真到手上该怎么用，哪里最容易踩坑。

看这段时要特别盯工具和权限边界，别为了省事一把全开。

关键片段

Customize your agent 1

"Customize your agent"这一段里最要紧的原始写法在下面，先看它怎么落地。

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "WebSearch"], permission_mode="acceptEdits"
)
关键片段

Customize your agent 2

"Customize your agent"这一段里最要紧的原始写法在下面，先看它怎么落地。

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob"],
    permission_mode="acceptEdits",
    system_prompt="You are a senior Python developer. Always follow PEP 8 style guidelines.",
)
关键片段

Customize your agent 3

"Customize your agent"这一段里最要紧的原始写法在下面，先看它怎么落地。

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "Bash"], permission_mode="acceptEdits"
)

Key concepts

这一段主要是在把"Key concepts"讲实，不是只摆个标题给你看。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

Troubleshooting

这里讲的是怎么找毛病，先查明白哪一步出错，再决定怎么修。

API error thinking.type.enabled is not supported for this model

这一段主要是在把"API error thinking.type.enabled is not supported for this model"讲实，不是只摆个标题给你看。

关键片段

API error thinking.type.enabled is not supported for this model

这一段要真抓重点，通常就抓下面这块原文。

API Error: 400 {"type":"invalid_request_error","message":"\"thinking.type.enabled\" is not supported for this model. Use \"thinking.type.adaptive\" and \"output_config.effort\" to control thinking behavior."}

Next steps

这里不是让你背"Next steps"这个词，而是让你看它真干活时怎么使。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

照着做一遍

如果你不想来回翻，就先照这几步顺着做。

每做完一步就看一下结果，再决定要不要继续往下。

终端里敲

第 1 步：Setup 1

看到这里，别光点头，下面这条命令先跑起来再说。

mkdir my-agent && cd my-agent
终端里敲

第 2 步：Setup 2

看到这里，别光点头，下面这条命令先跑起来再说。

npm install @anthropic-ai/claude-agent-sdk
终端里敲

第 3 步：Setup 3

看到这里，别光点头，下面这条命令先跑起来再说。

uv init && uv add claude-agent-sdk
关键片段

第 4 步：Create a buggy file

先看下面这块原始片段，等会儿再回头看解释会顺得多。

def calculate_average(numbers):
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)


def get_user_name(user):
    return user["name"].upper()

一眼看懂这一页

先把这页到底在讲什么看明白，再去碰具体命令和配置，最不容易绕晕。

Quickstart
   |
   v
这是 Agent SDK 里的一摊要紧活
   |
   v
先弄懂，再下手

文末提醒

这站会按官方 docs 的导航和内容变化继续重生成，原站加页、删页、改页时，这里会跟着更新。

人话解释会尽量顺着原页往下讲，但命令、参数名、配置名这些硬东西还是保留原样，免得你抄过去跑不起来。

预留广告位

文末横幅广告 适合放在文章读完以后，不抢首屏注意力。