第 3 章：配置选项详解

上一章我们学会了理解 Claude 的消息系统。这一章，我们来搞清楚怎么"调教" Claude —— 通过配置选项，让它按你的要求来干活。

ClaudeAgentOptions — Claude 的遥控器面板

想象一下，你买了一台新空调。拆开遥控器一看，上面有温度、风速、模式、定时……一堆按钮。但你平时用的时候，大部分按钮都不需要碰，按一下开机、调调温度就够了。

ClaudeAgentOptions 就是 Claude 的"遥控器"。它有二十多个"按钮"（配置项），但你完全不需要全部设置。事实上，什么都不设置也能用：

from claude_agent_sdk import query, ClaudeAgentOptions

# 不传任何配置，全部用默认值 —— 完全没问题
async for msg in query(prompt="你好"):
    print(msg)

# 等价于传一个空的配置
options = ClaudeAgentOptions()
async for msg in query(prompt="你好", options=options):
    print(msg)

核心原则：用到哪个设哪个，不需要的别碰。

接下来，我把这些配置项分成五组来讲，从最常用的开始。

第一组：基础配置 — 最常用的三个

这三个配置项你几乎每个项目都会用到。

system_prompt — 告诉 Claude 它是谁

系统提示词就像给 Claude 一份"岗位说明书"。不设置的话，Claude 会用默认的行为。设置了，Claude 就会按你的要求来表现。

options = ClaudeAgentOptions(
    # 简单的字符串提示词
    system_prompt="你是一个 Python 专家，所有回答都用中文，代码注释也用中文。"
)

你也可以用预设值，在默认提示词后面追加内容：

options = ClaudeAgentOptions(
    # 使用预设，再追加自定义内容
    system_prompt={
        "type": "preset",
        "preset": "claude_code",
        "append": "所有回答必须包含代码示例。"
    }
)

model — 选择用哪个模型

Claude 有好几个模型，能力和价格不同。不设置的话用 CLI 的默认模型。

options = ClaudeAgentOptions(
    model="claude-sonnet-4-5"  # 性价比之王，速度快、够聪明
)

常用模型：

cwd — 工作目录

告诉 Claude 在哪个目录下干活。Claude 读文件、写文件、执行命令都以这个目录为根目录。

options = ClaudeAgentOptions(
    cwd="/home/user/my-project"  # Claude 会在这个目录下操作
)

不设置的话，默认用当前进程的工作目录。

三个基础配置组合起来：

from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    system_prompt="你是一个严格的代码审查员，用中文指出所有问题。",
    model="claude-sonnet-4-5",
    cwd="/home/user/my-project",
)

async for msg in query(prompt="审查 src/ 目录下的所有 Python 文件", options=options):
    print(msg)

第二组：工具配置 — 决定 Claude 能用什么工具

Claude 之所以强大，是因为它不只会说话，还能动手——读文件、写文件、执行命令。这些能力叫做"工具"。工具配置就是控制 Claude 能用哪些工具。

allowed_tools — 工具白名单

只允许 Claude 使用你指定的工具。没在列表里的，Claude 用不了。

options = ClaudeAgentOptions(
    # 只给 Claude 读和搜索的权限，不能写文件、不能执行命令
    allowed_tools=["Read", "Glob", "Grep"]
)

disallowed_tools — 工具黑名单

禁止 Claude 使用某些工具。没在列表里的，Claude 都能用。

options = ClaudeAgentOptions(
    # 不允许执行命令和访问网络，其他都可以
    disallowed_tools=["Bash", "WebFetch", "WebSearch"]
)

内置工具一览

Claude Code 自带的工具有这些：

白名单 vs 黑名单怎么选？

# 场景 1：只做代码审查（只读），用白名单
# 思路："只允许这几个"
review_options = ClaudeAgentOptions(
    allowed_tools=["Read", "Glob", "Grep"]
)

# 场景 2：正常开发，但不要碰网络，用黑名单
# 思路："除了这几个都行"
dev_options = ClaudeAgentOptions(
    disallowed_tools=["WebFetch", "WebSearch"]
)

经验法则： 如果你想限制到很少几个工具，用白名单。如果你想开放大部分工具、只禁几个，用黑名单。

第三组：行为限制 — 防止失控

Claude 非常勤奋，有时候你让它做一件事，它可能会连续执行几十轮操作。这两个配置项就像给 Claude 套上"安全绳"。

max_turns — 最多执行几轮

一"轮"就是 Claude 执行一次工具调用或回复一次消息。设置上限，防止 Claude 陷入无限循环。

options = ClaudeAgentOptions(
    max_turns=10  # 最多 10 轮，到了就停
)

max_budget_usd — 最多花多少钱

直接限制这次调用的花费上限。超了就停。强烈建议在生产环境中始终设置此项。

options = ClaudeAgentOptions(
    max_budget_usd=0.50  # 最多花 5 毛钱（美元）
)

两者配合使用

在实际项目中，建议同时设置两个限制。双保险，哪个先到就停：

options = ClaudeAgentOptions(
    max_turns=20,         # 最多 20 轮
    max_budget_usd=1.00,  # 最多花 1 美元
)

实际应用场景参考：

第四组：认证与环境 — 连上 Claude 的钥匙

Claude SDK 支持两种认证方式。选哪种取决于你的使用场景。

方式一：API Key 模式

适合服务端部署、自动化脚本、CI/CD。你有一个 API Key，SDK 用它直接调用 Claude API。

import os

options = ClaudeAgentOptions(
    # 通过 env 参数传递 API Key
    env={
        "ANTHROPIC_API_KEY": os.environ["ANTHROPIC_API_KEY"]
    }
)

或者你也可以直接在环境变量里设好，SDK 会自动读取：

# 终端里设置
export ANTHROPIC_API_KEY="sk-ant-xxxxx"

# 代码里不需要额外配置，SDK 自动读取环境变量
options = ClaudeAgentOptions()

方式二：订阅模式

适合个人开发、本地使用。你有 Claude Pro/Max 订阅，先用 CLI 登录，SDK 就能用了。

# 先在终端登录一次
claude login

# 登录后直接用，不需要额外配置
options = ClaudeAgentOptions()

两种模式对比

env — 传递环境变量

除了 API Key，你还可以通过 env 传递其他环境变量给 Claude CLI 进程：

options = ClaudeAgentOptions(
    env={
        "ANTHROPIC_API_KEY": "sk-ant-xxxxx",
        "MY_CUSTOM_VAR": "some_value",      # 自定义变量
    }
)

cli_path — 指定 CLI 路径

如果你的 Claude CLI 不在系统 PATH 里，可以手动指定路径：

options = ClaudeAgentOptions(
    cli_path="/usr/local/bin/claude"  # 手动指定 claude 命令的位置
)

第五组：高级配置（预览）

这些配置项更进阶，这里先简单介绍一下概念，后续章节会详细展开。

thinking — 扩展思考

让 Claude 在回答之前"想一想"。就像考试时先在草稿纸上演算，再写答案。对复杂问题很有帮助。

# 自适应思考 —— 让 Claude 自己决定要不要思考
options = ClaudeAgentOptions(
    thinking={"type": "adaptive"}
)

# 指定思考预算 —— 最多用 10000 个 token 来思考
options = ClaudeAgentOptions(
    thinking={"type": "enabled", "budget_tokens": 10000}
)

# 关闭思考
options = ClaudeAgentOptions(
    thinking={"type": "disabled"}
)

effort — 思考深度

比 thinking 更简单的控制方式，直接告诉 Claude 用多大力气想：

options = ClaudeAgentOptions(
    effort="low"     # 快速回答，不深入思考
)

options = ClaudeAgentOptions(
    effort="high"    # 仔细思考，适合复杂问题
)

四个档位："low" / "medium" / "high" / "max"。

permission_mode — 权限模式

控制 Claude 使用工具时的权限级别：

options = ClaudeAgentOptions(
    permission_mode="default"  # 默认模式，危险操作会请求确认
)

权限控制的完整内容请看第 7 章。

hooks — 钩子系统

在 Claude 执行工具前后插入你自己的逻辑。比如：工具调用前检查是否安全，调用后记录日志。

# 简单示例，详细内容请看第 6 章
options = ClaudeAgentOptions(
    hooks={
        "PreToolUse": [
            HookMatcher(
                matcher="Bash",           # 监听 Bash 工具
                hooks=[my_check_function]  # 执行前调用我的检查函数
            )
        ]
    }
)

钩子系统的完整用法请看第 6 章。

output_format — 结构化输出

让 Claude 按照你指定的 JSON Schema 格式返回结果：

options = ClaudeAgentOptions(
    output_format={
        "type": "json_schema",
        "schema": {
            "type": "object",
            "properties": {
                "summary": {"type": "string"},
                "score": {"type": "integer", "minimum": 0, "maximum": 100}
            },
            "required": ["summary", "score"]
        }
    }
)

agents — 子 Agent 定义

创建专门执行特定任务的子 Agent：

from claude_agent_sdk.types import AgentDefinition

options = ClaudeAgentOptions(
    agents={
        "reviewer": AgentDefinition(
            description="代码审查专家",
            prompt="你是一个严格的代码审查员，专注于发现代码中的 bug 和安全问题。",
            model="sonnet",
        ),
    }
)

API Key vs 订阅 — 自动检测

在实际项目中，你可能希望代码能同时兼容两种认证模式。下面是一个实用的自动检测方案：

import os
import shutil

def detect_auth_mode() -> dict:
    """自动检测当前可用的认证模式。"""
    api_key = os.environ.get("ANTHROPIC_API_KEY")
    if api_key:
        return {"mode": "api_key", "key": api_key[:12] + "..."}

    # 检查 Claude CLI 是否可用（订阅模式）
    cli_path = shutil.which("claude")
    if cli_path:
        return {"mode": "subscription", "cli": cli_path}

    return {"mode": "none", "error": "未找到认证方式"}


def build_options_for_auth() -> "ClaudeAgentOptions":
    """根据检测到的认证模式构建配置。"""
    from claude_agent_sdk import ClaudeAgentOptions

    auth = detect_auth_mode()

    if auth["mode"] == "api_key":
        return ClaudeAgentOptions(
            env={"ANTHROPIC_API_KEY": os.environ["ANTHROPIC_API_KEY"]}
        )
    elif auth["mode"] == "subscription":
        # 订阅模式不需要额外配置
        return ClaudeAgentOptions()
    else:
        raise RuntimeError(
            "未找到认证方式！请设置 ANTHROPIC_API_KEY 环境变量，"
            "或运行 'claude login' 登录。"
        )

完整可运行的示例请看 examples/dual_mode_auth.py。

配置最佳实践

1. 最小化原则

只设置你需要的配置项。ClaudeAgentOptions 的每个参数都有合理的默认值，没必要把每个都填上。

# 好 —— 只设置需要的
options = ClaudeAgentOptions(
    system_prompt="你是 Python 专家。",
    max_turns=10,
)

# 没必要 —— 多余的默认值
options = ClaudeAgentOptions(
    system_prompt="你是 Python 专家。",
    max_turns=10,
    model=None,             # 本来就是 None
    cwd=None,               # 本来就是 None
    allowed_tools=[],       # 本来就是空列表
    disallowed_tools=[],    # 本来就是空列表
    env={},                 # 本来就是空字典
    permission_mode=None,   # 本来就是 None
)

2. 安全第一

生产环境中，绝对不要用 bypassPermissions。这个模式会跳过所有安全检查，Claude 可以随意执行任何操作。

# 开发测试时可以用（方便调试）
dev_options = ClaudeAgentOptions(
    permission_mode="bypassPermissions"
)

# 生产环境 —— 用 acceptEdits 或 default
prod_options = ClaudeAgentOptions(
    permission_mode="acceptEdits",  # 自动接受文件编辑，但其他操作仍需确认
    max_budget_usd=2.00,            # 一定要设预算上限
)

3. 始终设置预算保护

无论什么场景，都建议设置 max_budget_usd。Claude 很能干，但也很能花钱。

# 即使是简单任务，也设个上限
options = ClaudeAgentOptions(
    max_turns=5,
    max_budget_usd=0.10,  # 1 毛钱封顶
)

4. 工具权限要明确

如果你的程序只需要 Claude 分析代码（不需要改代码），就明确限制工具。别给 Claude 多余的权限。

# 只读模式 —— 分析但不修改
readonly_options = ClaudeAgentOptions(
    allowed_tools=["Read", "Glob", "Grep"],
    system_prompt="分析代码并给出建议，但不要修改任何文件。",
)

完整配置速查表

小结

这一章我们学了 ClaudeAgentOptions 的五组配置：

1. 基础配置：system_prompt、model、cwd —— 最常用，几乎每次都要设
2. 工具配置：allowed_tools、disallowed_tools —— 控制 Claude 能做什么
3. 行为限制：max_turns、max_budget_usd —— 防止失控和烧钱
4. 认证环境：env、cli_path —— 连上 Claude 的钥匙
5. 高级配置：thinking、hooks、permission_mode 等 —— 进阶功能

记住核心原则：用到哪个设哪个，安全第一，始终设预算。

下一章，我们进入进阶篇 —— 用 ClaudeSDKClient 实现多轮对话和流式交互。

动手试试： 运行 examples/config_playground.py 看看不同配置组合的效果。

下一章： 第 4 章 - 多轮对话与流式交互