Claude Code 常见问题(FAQ)：高级特性

Claude Code 常见问题导航

本文是 Claude Code 常见问题系列的高级特性篇，专注于解答用户在使用 Claude Code 高级功能时遇到的常见问题。

Agents / Subagents

在 Claude Code 常见问题中，关于 Agent 和 Subagent 的配置与使用是最受关注的高级功能之一。以下是用户最常遇到的问题和解答：

claude code 的 Agent 与 Subagent 是什么？

Agent（或 Subagent）是 Claude Code 中的定制化 AI 助手，用于处理特定类型的任务[75]。您可以为常见或专业任务创建专属"智能代理"，每个代理都有独立的系统提示、权限范围和上下文窗口[76]。例如，可以创建"代码审查员"代理专门负责代码审查任务，或"文档写作"代理专门生成文档内容。使用 Subagent 能让解决问题更高效，因为 Claude 会将符合某个子代理专业领域的任务委派给它来处理[77]。Subagent 有自己的上下文，避免污染主会话，使得多任务处理更加有序。

如何在 claude code 新建一个 Agent？

在会话中输入 /agents 命令，会打开 Subagents 管理界面[78]。按照提示选择 "Create New Agent"，然后指定是项目级还是用户级代理[79]。接下来填写代理的名称、描述和系统提示，以及配置它能使用的工具（可选择授权或拒绝特定工具）[80]。保存后，新代理就可用。您也可以手动编辑项目目录下的 .claude/agents/（项目级）或用户目录下的 ~/.claude/agents/（用户级）中的 Markdown 文件来定义 Subagent。参考界面说明即可完成。创建完成后，该代理将出现在 /agents 列表中。

如何在 claude code 会话中调用或切换 Agent？

一旦 Subagent 创建成功，Claude 会在对话中自动识别何时使用哪个代理。您可以直接输入类似 "Use the <subagent-name> agent to handle X" 的自然语言指令，Claude 会调用对应代理[81]。例如，"Use the code-reviewer subagent to check my recent changes"[82]。您也可以通过 /agents 列表界面直接选择切换代理。当前会话切换到某个 Subagent 后，Claude 将在该代理的上下文中执行任务，并在完成后返回结果。请注意，只有当代理的触发条件匹配时 Claude 才会使用它，否则保持在主线程。

为什么 claude code 没有使用我的 Agent？

如果您发现 Claude Code 没调用预期的 Subagent，可能有几个原因：一是当前交互可能不符合该代理的触发条件或描述，Claude 因而没有检测到需要使用该代理；二是该代理所在的项目目录与会话目录不一致，导致 Claude 没有加载它；三是权限设置限制了该代理可使用的工具。建议检查 Subagent 的描述和工具权限是否正确，并确保在项目根目录启动会话。另外，可以明确地在对话中提到该代理（如上一问所述）来强制切换；如果仍有问题，尝试重启会话并确认 /agents list 中能看到您的子代理配置。

如何在 claude code 评估与改进 Agent 效果？

评估 Subagent 效果通常和人工审查相似：您可以给代理分配一些典型的任务或问题，让 Claude 返回结果并检查其质量。根据输出，决定是否调整代理的系统提示或权限设置。Anthropic 建议："Recommended: Generate with Claude first, then customize"[80]。即您可以让 Claude 聊天模式尝试执行该专业任务，观察其回答，然后将优秀的回答用作子代理的初始系统提示。保持迭代：如果代理没有按预期工作，尝试修改其提示语或允许的工具，直到效果满意。由于 Subagent 是以文本文件形式存在，您可以随时编辑并重载它们，逐步优化其专业性。

如何从外部系统触发 claude code 的某个 Agent？

当前 Claude Code 的 Subagent 功能主要通过交互式终端和 /agents 命令使用，没有直接开放给外部系统的单点触发接口。但您可以通过编写脚本或 API 调用来间接触发：例如使用 Claude Code SDK（待发布）或 CLI 在外部脚本中运行 claude -p "Use the <agent> subagent to do X" 来调用特定子代理。此外，如果您有 GitHub Actions、Webhook 等自动化流水线，可以在其中运行 claude CLI 并传入指令，模拟用户交互来启动代理任务。将来的 SDK 可能提供更直接的触发方式。目前的做法基本上还是通过编程方式在支持的环境中运行 Claude Code CLI 并在提示中指定要使用的子代理。

MCP（Model Context Protocol）

MCP 协议是 Claude Code 常见问题中另一个重要的高级功能话题。许多用户在配置和使用 MCP 服务器时遇到各种问题，以下是详细的解答：

claude code 的 MCP 是什么，适用哪些场景？

Model Context Protocol (MCP) 是一个开源标准，旨在让 AI 模型与外部工具和数据源对接[83]。在 Claude Code 中，MCP 服务器就像"桥接器"，能让 Claude 访问公司私有数据或云服务。通过连接 MCP，您可以让 Claude Code 执行诸如查询内部数据库、读取设计文档、管理项目任务等操作。例如，它可以"自动实现 Jira 任务所述功能并创建 GitHub PR"、"分析 Sentry 日志数据"、"从 Figma 读取设计文件"或"更新 Linear/Notion 事项"[60]。简而言之，MCP 让 Claude Code 超越本地文件，直接操作您的各种开发和业务平台，适用于自动化工作流、跨系统报告和协同场景。

如何为 claude code 添加一个 MCP 服务器？

使用 claude mcp 命令可以添加 MCP 服务器。在终端运行：claude mcp add --transport <http|sse> <name> <url>，其中 <name> 是您为该服务器起的识别名，<url> 是 MCP 服务器的地址[84][85]。例如，要添加一个 Sentry MCP，示例命令为：claude mcp add --transport http sentry https://mcp.sentry.dev/mcp[84]。有些服务器需要环境变量（如 API 密钥），可以使用 --env KEY=VALUE 参数或相关方式配置[86][87]。添加后，Claude Code 即可通过 /mcp 交互式命令调用该服务器。确保 MCP 服务器是可信任来源，因为它可以获取您的代码和数据[88]。

如何在 claude code 配置项目级与全局级 MCP？

MCP 服务器可以分为项目级（仅此仓库）和全局级（所有项目共享）两种配置。默认情况下，使用 claude mcp add 将 MCP 配置保存在用户级配置中，适用于当前用户所有项目。如果想为当前项目单独配置，可以在命令中添加 --config project 选项（若支持），或将配置文件放在项目目录下的 .claude/mcp 文件夹中。反之，将其放在 ~/.claude/mcp（用户目录）下则是全局配置。可以通过 claude mcp list 查看当前加载的 MCP 服务器和它们的作用域[89]。项目级配置优先于全局配置：若项目文件夹下存在同名 MCP 文件，将使用项目级版本。

claude code 的 MCP 配置文件通常位于哪里？

MCP 的配置存储在用户目录下的 ~/.claude/mcp.json（或 .claude 子目录）中，或者在项目目录下的 .claude/mcp.json（若存在项目级配置）。使用 claude mcp add 时，默认写入用户级配置（在 ~/.claude/ 目录）。如果指定项目配置（例如使用 --config project），则配置会存到当前工程的 .claude 文件夹中。您可以手动查看或编辑这些 JSON 文件来管理已添加的服务器。使用 claude mcp list 可以列出所有已安装的 MCP 及其配置来源[89]。

如何在 claude code 列出已安装的 MCP？

运行命令：claude mcp list[90]。此命令会列出所有已添加的 MCP 服务器，包括其名称、地址和当前状态。您还可以使用 claude mcp get <name> 获取某个特定服务器的详细信息。通过这些命令，您可以确认哪些 MCP 已经配置并可用。

如何在 claude code 禁用或移除 MCP？

要移除不再需要的 MCP 服务器，可以使用 claude mcp remove <name> 命令[91]。例如：claude mcp remove linear 会删除名为 "linear" 的 MCP 服务器配置。此操作会更新配置文件并禁止 Claude 访问该服务。若想临时禁用而不删除，可以直接在 /mcp 命令中选择禁用选项或编辑配置文件将其停用。移除后，若此前会话中使用了该 MCP，相关功能将不可用。

如何在 WSL/Docker/远程环境接入 claude code 的 MCP？

MCP 本质上需要网络访问到外部服务器。在 WSL 或 Docker 中使用 MCP，需要确保容器/环境能访问 MCP 服务器的地址（注意主机名和网络模式）。可以通过设置代理环境变量或使用 --transport 参数指定使用 HTTP 或 SSE。WSL 用户需确认 WSL 的网络可达服务器（可尝试 curl URL 测试）。在 Docker 容器中，通常需要开放相应网络端口。总之，只要在环境内部运行 claude mcp add 并且地址可访问，MCP 即可使用。对于 AWS Bedrock/Vertex 等远程部署，还需根据平台要求配置网络许可。

如何为 claude code 的 MCP 配置代理或网络？

如果您的环境需要使用 HTTP 代理访问外网，可以通过设置环境变量来影响 MCP 连接。例如在启动终端前设置 HTTP_PROXY 和 HTTPS_PROXY 环境变量，Claude Code 会使用它们进行 MCP 服务器通信。另外，claude mcp add 提供了 --transport http 或 --transport sse 选项，根据服务器类型选择正确协议。如需特殊 HTTP header（如内部 API Key），可以使用 --header "Key: Value" 来添加[92]。对于需要翻墙或通过私有网络连接的场景，可在 Docker/WSL 网络配置中启用代理或 VPN。具体配置取决于您的网络架构，但 Claude Code 本身支持使用环境代理和命令行参数控制网络连接。

常用 MCP（Playwright/Puppeteer/Figma/GitHub/Supabase）如何安全接入 claude code？

对于常见工具，社区和 Anthropic 已提供多种 MCP 服务器实现：

Playwright/Puppeteer：这类 MCP 通常通过一个本地或云端的 Node.js 服务器运行 Chrome 实例，支持网站自动化脚本。安装时通常运行 npx @anthropic/claude-code-browser（示例）并指定 claude mcp add --transport http browser http://localhost:port。请确保相关 MCP 来自可信源，且本地浏览器环境已隔离。
Figma：有专门的 Figma MCP 服务器（如 figma-dev-mode-mcp-server[93]），用于访问 Figma Dev Mode 接口。使用时需准备 Figma API Key 和配置好相关端点。对外部设计数据要严格控制访问权限。
GitHub/GitHub Actions：可以使用官方提供的 GitHub/MCP 服务来读写仓库。典型命令为 claude mcp add github https://api.github.com/mcp，并配置好 GitHub App 或令牌（CLI 参数或 env）。搭配合规策略，授权仅限必要的 repo/PR 权限。
Supabase：Supabase 也有 MCP 实现，通常需要在命令中提供 API URL 和键，如 --env SUPABASE_API_KEY=...[94]。确保将这些凭据安全保存在环境变量中。

出现 -32000 等错误时如何在 claude code 排查？

JSON-RPC 错误码 -32000 通常表示 MCP 服务器连接失败或返回无效数据。遇到此类错误时，可按步骤排查：

检查网络可达性：在终端尝试 curl <MCP URL>，确认地址正确且网络畅通。
验证服务器状态：使用 claude mcp get <name> 查看服务器状态，或登录对应 MCP 服务的管理界面检查运行日志。
审查认证信息：确认传递给 claude mcp add 的 API 密钥、令牌、额外 header 等信息是否正确无误[92][94]。错误的头部可能导致 401 或无响应。
代理/防火墙：如果网络需要代理或防火墙规则，请确保环境变量设置正确，并且将 MCP URL 列入白名单。
查看详细日志：在 Claude 会话中开启详细日志（使用 /verbose 模式或启动时加 --verbose）可以获取更多错误上下文。
更新版本：确保 Claude Code 和 MCP 服务器均为最新版；版本不兼容也可能导致协议错误。

通过以上步骤，您通常可以定位是网络、配置还是服务器本身的问题，并作相应修复。

图像 / 文件 / 上下文

关于文件处理、图像输入和上下文管理是 Claude Code 常见问题中的重要组成部分。以下是用户在使用这些功能时最常遇到的问题：

如何向 claude code 提供图片或截图？

Claude Code 目前主要面向文本和代码交互，不原生支持在 CLI 中直接粘贴或上传图片文件。您可以将图片上传到一个可访问的 URL，然后在对话中提供该链接（Claude 可以通过浏览器 MCP 或外部工具读取图像），但这需要额外配置（例如使用图像相关的 MCP 插件）。在纯终端环境下，通常的做法是 以文本形式描述 图片内容或寻找替代的图像分析方案。总之，目前未提供像 Chat 界面那样直接粘贴图像到命令行的方法。

如何拖拽或粘贴图片到 claude code 会话？

由于终端环境不支持图形拖拽，您无法将本地图片直接粘贴到 Claude Code 会话中。如果需要让 Claude 分析图片，通常需要先将图片托管到网络（比如使用图像共享服务）并提供链接，或者使用 Claude 的 HTTP 传输能力通过 MCP 服务（比如浏览器 MCP）将图像内容传递给模型。目前在 CLI 交互中没有直接处理本地图片的功能。

如何把文件或目录加入 claude code 的上下文？

默认情况下，Claude Code 会话所在的当前工作目录及其子目录中的代码文件自动对 Claude 可见。您也可以显式地添加额外路径：使用命令行参数 claude --add-dir <路径>[58] 或在会话中运行 /add-dir <路径> 命令，将指定目录纳入上下文。这样，Claude 在检索信息和分析代码时，会包括这些路径中的文件。例如，claude --add-dir docs 会让 Claude 访问项目下的 docs/ 目录。请确保提供的路径是相对于当前目录或绝对路径，并且确实存在。

如何为 docs/ 等目录建立 claude code 索引？

Claude Code 会自动扫描被添加到上下文的目录并为文件建立索引。当您运行命令如 claude --add-dir docs/ 时，它会检查 docs/ 文件夹并将其中的文本纳入搜索范畴。对于项目中特定的知识，如架构文档或规范文件，建议将其内容合并到项目根的 CLAUDE.md 中（详见记忆管理[59]），或者在提问时引用文件路径（使用 VS Code/IDE 插件时，可以通过 @文件名#L范围 快速引用）。目前尚无人工触发的"索引"命令；Claude 基于上下文和工具自动处理文档内容。

为什么 claude code 的多页 Artifact 无法翻页或显示不完整？

当 Claude Code 生成较长的输出（如代码文件）时，会将其作为 "Artifact" 发送，并以多页形式显示在 UI 中。在某些终端或 IDE 集成中，翻页功能可能受限，导致无法直接翻到第二页。通常可以通过在终端界面手动滚动来查看完整内容，或者在 VS Code 集成中点击"在编辑器中打开 Diff"（见 IDE 集成部分[11]）将输出以文件形式查看。如果 Artifact 输出过多仍不完整，建议使用 claude -p 模式获取纯文本输出，或分步请求生成，以避免单次输出超过显示限制。

如何在 claude code 限制上传大小或分块提供大文件？

Claude Code 对输入大小有限制（取决于模型的上下文窗口）。对于非常大的文件，建议分段处理：可以使用命令行工具如 split 将大文件拆成多个小段，然后逐段发送给 Claude。例如，cat part1.txt | claude -p "继续分析..."。或者在交互中询问 Claude 逐部分加载文件。如需上传附件或使用其他工具（例如文件 API），需使用对应的 API 方式，并注意不要超过发送限制。目前 CLI 没有自动分块功能，需手动管理文件大小和拆分。

claude code 能否读取网页作为上下文？

Claude Code 本身没有内置的网页抓取功能。但您可以借助 MCP（Model Context Protocol）来实现这一点。例如，Anthropic 提供了可以访问网页内容的 MCP 服务器（如基于浏览器或 Puppeteer 的服务器）。添加后，您可以在对话中使用如 "从这个 URL 获取数据" 的方式让 Claude Code 通过 MCP 抓取网页并提取信息[60]。如果不使用 MCP，可手动将网页内容复制到文本文件或会话中供 Claude 阅读。

如何让 claude code 遵循项目规则或文档（如 claude.md）？

将项目的编码规范、风格指南等写入 CLAUDE.md 文件，可以让 Claude 在分析和生成代码时参考这些规则[59]。Claude Code 会自动读取当前目录及其上层目录的 CLAUDE.md（以及 CLAUDE.local.md 或通过导入的文档）作为对话的系统指令。这相当于为 AI 定义了项目特定的"记忆"。例如，在项目根目录创建一个 CLAUDE.md 包含"始终使用双引号"等说明，那么后续交互中 Claude 会优先遵守这些约定[61]。您也可以在会话中使用快捷符号（如输入 # 描述规则）将新信息追加到指定记忆文件[62]。总之，通过维护和完善 CLAUDE.md，可以让 Claude Code 更好地遵循您的项目规范。