Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Claude Code 内置能力

Claude Code 是 Anthropic 官方推出的终端 AI 编程工具，深度集成 Claude 模型。本章作为 Claude Code 的能力索引，指向各详细参考文件。

能力一览

Claude Code 的核心能力可以按以下维度组织：

维度简介详细参考
内置命令/init、/compact、/cost、/doctor 等 15+ 个斜杠命令命令参考
文件工具Read（文本+PDF）、Write、Edit（精确替换）—（见下方工具集）
执行工具Bash（命令执行，支持超时）—
搜索工具Grep（正则）、Glob（文件模式）—
网络工具WebFetch（URL 抓取）—
Agent 模式Plan Mode（只读分析）、Code Mode（默认读写）—（见下方 Agent（智能体） 模式）
项目指令CLAUDE.md 多级配置（全局/项目/目录）扩展机制参考
自定义命令.claude/commands/*.md 自动注册为 / 命令扩展机制参考
MCP Server通过 JSON-RPC 接入外部工具和数据源扩展机制参考
权限控制细粒度工具调用权限管理扩展机制参考
成本追踪/cost 查看 Token 使用统计命令参考
生态与社区Anthropic 生态、MCP（模型上下文协议） 协议、社区资源生态参考

工具集速览

Claude Code 内置工具集聚焦核心编码场景：Read（支持 PDF）、Write（覆盖写入）、Edit（oldString/newString 精确匹配替换）、Bash（Shell 执行）、Grep（正则搜索）、Glob（文件名匹配）、WebFetch（URL 抓取）。

Agent 模式

命令功能
/init初始化项目，生成 CLAUDE.md 文件
/clear清除当前对话上下文
/compact压缩上下文，减少 Token 消耗
/cost显示当前会话的 Token 使用统计
/doctor诊断环境问题，检查配置完整性
/help显示帮助信息
/login登录 Anthropic 账户
/logout登出当前账户
/memory编辑 CLAUDE.md 记忆文件
/model切换当前使用的模型
/permissions查看和管理工具调用权限
/review对代码变更进行审查
/status显示当前状态信息
/terminal-setup设置终端集成（Shell 集成、快捷键等）

→ 完整命令列表和详细用法见 Claude Code 命令参考。 → 扩展体系详解见 Claude Code 扩展机制参考，涵盖 CLAUDE.md、Skills、MCP、Subagent、Hook、Plugin 六层架构。 → Plugin 系统 详细介绍了 OpenCode 的 Plugin/Skill/MCP 三层扩展架构。

命令使用示例

/init                          # 首次进入项目时初始化
/compact                       # 上下文过长时压缩
/cost                          # 查看消耗了多少 Token
/doctor                        # 遇到问题时诊断环境
/model claude-sonnet-4-20250514   # 切换到 Sonnet 模型

工具集

Claude Code 内置的工具集相对精简，聚焦于核心编码场景。

文件操作

工具功能说明
Read读取文件内容支持文本和 PDF
Write写入文件覆盖写入
Edit精确文本替换基于 oldString/newString 匹配

命令执行

工具功能说明
Bash执行 shell 命令支持超时设置

搜索

工具功能说明
Grep正则内容搜索按正则表达式搜索文件内容
Glob文件模式匹配按 glob 模式搜索文件名

网络

工具功能说明
WebFetchURL 抓取获取网页内容

Agent 模式

Claude Code 支持 6 种权限模式，通过切换控制 AI 的操作范围。

6 种权限模式

模式说明
default每次执行敏感操作前询问用户确认
acceptEdits自动接受文件编辑（Write/Edit），执行命令时询问
plan只读分析，不能修改文件或执行命令。适合动手前先规划
auto自动批准所有操作，无交互确认
dontAsk不主动询问，静默拒绝权限外的操作
bypassPermissions绕过所有权限检查，完全信任 Agent

通过 --permission-mode 标志或 /permissions 命令切换。

自定义配置

Claude Code 的自定义主要通过文件配置实现。

CLAUDE.md 项目指令

CLAUDE.md 是 Claude Code 的项目级指令文件，放在项目根目录。它告诉 Claude 在这个项目中应该怎么工作，类似 OpenCode 的 AGENTS.md。

CLAUDE.md 通常包含：

  • 项目简介和技术栈说明
  • 代码风格和命名规范
  • 测试和构建命令
  • 常用路径和模块说明
  • 不能做的事（约束条件）

Claude Code 支持多级 CLAUDE.md：

  • ~/.claude/CLAUDE.md — 全局配置，所有项目生效
  • 项目根目录/CLAUDE.md — 项目级配置
  • 子目录/CLAUDE.md — 目录级配置，进入该目录时加载

.claude/ 目录结构

Claude Code 使用 .claude/ 目录管理项目配置：

.claude/
  settings.json    # 项目设置
  commands/        # 自定义命令

权限配置

Claude Code 对工具调用有细粒度的权限控制。每次调用 Bash、Write 等敏感工具时，会提示用户确认。可以通过配置文件预设权限规则，减少重复确认。

权限配置示例：

{
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Bash(npm run build)",
      "Write(src/**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Write(.env*)"
    ]
  }
}

与 OpenCode 的主要差异

了解两者的能力差异，有助于选择合适的工具。

维度OpenCodeClaude Code
模型支持多模型（Claude、GPT、Gemini、本地模型）仅 Claude 模型
扩展机制Plugin（插件） + Skill（技能） + MCP + 自定义 AgentCLAUDE.md + Skills + MCP + Subagents + Hooks + Plugins 六层
工具链完整（AST-grep、LSP、CodeGraph 等）基础（文件、命令、搜索）
Hook 系统20+ Hook Points，事件驱动无
成本控制内置 Token 追踪/cost 命令查看
会话管理压缩、导出、分享、撤销压缩、清除
开源状态开源闭源

扩展机制

Claude Code 的扩展方式相对收敛，主要依赖配置文件和外部协议。

CLAUDE.md 自定义指令

CLAUDE.md 是最核心的扩展手段。通过编写结构化的指令，你可以改变 Claude 在项目中的行为，无需编写任何代码。多级 CLAUDE.md 支持全局、项目、目录三个层次的配置叠加。

自定义命令

在 .claude/commands/ 目录下放置 Markdown 文件，每个文件自动注册为一个 / 命令。文件名即命令名，文件内容作为发送给 Claude 的 Prompt（提示词）。这相当于一种轻量级的 Skill 机制，适合封装重复性的项目操作。

.claude/commands/
  review.md       # → /review 命令
  fix-lint.md     # → /fix-lint 命令
  deploy.md       # → /deploy 命令

MCP Server 连接

Claude Code 支持连接外部 MCP Server，通过 .claude/settings.json 配置。MCP 为 Claude Code 提供了接入外部工具和数据源的能力，比如数据库查询、API 调用、文件系统操作等。

扩展方式对比

扩展方式实现形式灵活度适用场景
CLAUDE.md 指令Markdown 文本低行为规范、编码约束
SkillsSKILL.md + YAML frontmatter低可复用指令集
MCP Server外部进程 JSON-RPC高外部工具、数据源接入
SubagentsMarkdown + YAML frontmatter中隔离上下文的子任务代理
HooksJSON + Shell / LLM / Agent中高生命周期事件自动化
Pluginsplugin.json 清单打包高分发以上所有组件

与 OpenCode 的扩展体系相比，Claude Code 没有 Plugin 层（无法在 Agent 进程内注入运行时逻辑），也没有 Skill 市场（无法从社区安装可复用的指令包）。扩展能力集中在“指令配置 + 外部协议“两个维度。

→ 扩展体系详解见 Claude Code 扩展机制参考，涵盖 CLAUDE.md、Skills、MCP、Subagent、Hook、Plugin 六层架构。 → Plugin 系统 详细介绍了 OpenCode 的 Plugin/Skill/MCP 三层扩展架构。

生态与社区

Anthropic 生态

Claude Code 的生态紧密围绕 Anthropic 的产品体系：

  • Anthropic Console：统一管理 API Key、用量监控、账单
  • Claude 模型家族：Sonnet（性价比）、Opus（最强能力）、Haiku（最快速度）
  • Model Context Protocol：Anthropic 主导的开放协议，用于标准化 AI 工具与外部系统的连接

MCP 是 Claude Code 生态中最有价值的部分。通过 MCP，Claude Code 可以连接数据库、版本控制、CI/CD 流水线、项目管理工具等。Anthropic 维护了一份 MCP Server 参考实现列表，社区也贡献了大量 Server 实现。

社区资源

Anthropic 官方提供了完整的 Claude Code 使用指南。GitHub 上有多个展示 CLAUDE.md 最佳实践的参考项目，开发者也在论坛和社交媒体上分享配置方案和使用技巧。

生态对比

生态维度Claude CodeOpenCode
模型生态仅 Claude 模型族Claude/GPT/Gemini/本地模型等 10+ Provider
工具扩展MCP Server（JSON-RPC）MCP + Plugin + Skill + 自定义 Tool
社区资产CLAUDE.md 模板、MCP Server 实现Skill 市场、Plugin 仓库、oh-my-openagent 社区
协议标准MCP（Anthropic 主导）MCP（完全兼容） + 原生 Plugin API
扩展粒度指令级 + 外部工具级代码级（Hook）+ 指令级 + 工具级

Claude Code 的生态优势在于 Anthropic 的品牌背书和 MCP 协议的标准化推广。OpenCode 的生态优势在于多模型支持和更丰富的扩展层次（Plugin 可以拦截任意 Agent 行为）。

→ MCP 服务器 详细讲解了 MCP 协议在 OpenCode 中的配置和实践。

使用建议

选择 Claude Code 还是 OpenCode

两个工具的适用场景有明显重叠，但也各有侧重。如果你的团队已经全面使用 Claude 模型，且项目不需要复杂的 Agent 编排，Claude Code 的简洁性是一个优势。它上手快、配置少、没有 Plugin/Skill 的认知负担。

如果你需要多模型灵活切换、自定义 Agent 行为、或团队共享工作流，OpenCode 的扩展体系更适合。OpenCode 的 Plugin 和 Skill 系统让你可以把最佳实践编码化，在团队内复制和演进。

CLAUDE.md 写作建议

写好 CLAUDE.md 的关键：具体、可执行、有边界。避免空泛的描述，给出明确的规则。推荐的 CLAUDE.md 结构：

  1. 项目简介：一两句话说清楚这是什么项目
  2. 技术栈：语言、框架、包管理器
  3. 代码规范：命名约定、格式化规则、禁止的写法
  4. 常用命令：构建、测试、lint 的具体命令
  5. 约束条件：不能修改的文件、不能执行的操作

权限配置建议

Claude Code 的权限提示虽然安全，但频繁弹出会打断工作流。建议在项目早期就把常用的构建、测试命令加入白名单，把危险操作（如 rm -rf）加入黑名单。既保证安全，又减少干扰。

→ 命令参考 — Claude Code 全部命令的详细用法 → 扩展机制参考 — 六层扩展体系完整参考（CLAUDE.md、Skills、MCP、Subagent、Hook、Plugin） → 生态参考 — 社区生态和最佳实践 → Claude Code Agent（智能体） 设计与开发指南 — 自定义 Agent 与 Subagent 的从入门到生产完整教程 → Claude Agent（智能体） SDK：编程式 Agent 开发 — 通过 @anthropic-ai/claude-agent-sdk 编程式驱动 Agent → OpenCode 内置能力 — 对应功能的对比参考 → 核心概念 — 设计哲学深入对比

2026年6月更新

以下是 2026 年 6 月期间 Claude Code 新增或变更的主要功能：

功能说明
嵌套子 Agent支持最多 5 层深度的子 Agent 嵌套调用，复杂任务可拆分为多级子任务
fallbackModel 配置支持配置最多 3 个备选模型，主模型不可用时自动切换
动态工作流（/workflows）新增 /workflows 命令，支持定义和执行多步骤工作流
Artifacts实时更新的网页分享功能，生成可交互的代码预览或文档
Safe mode--safe-mode 启用安全模式，限制高风险操作
/cd 命令新增 /cd 命令，快速切换工作目录
社区工具市场支持从社区安装第三方工具和 MCP Server
Agent checkpointing (beta)Agent 执行过程中支持检查点保存和恢复（Beta）
Per-agent 成本归属--attribution 标志支持按 Agent 粒度追踪成本

常见反模式

只用 Claude Code 的默认工具集而不探索扩展能力

许多开发者初次使用 Claude Code 时只停留在内置的 Read/Write/Edit/Bash/Grep/Glob 工具上，从不配置 MCP 服务器或创建自定义命令。Claude Code 的真正价值不在于它内置了什么，而在于它能连接什么。一个没有配置 GitHub MCP Server 的 Claude Code，无法直接操作 PR 和 Issue；一个没有连接数据库 MCP Server 的 Claude Code，只能通过 Bash 执行 psql 命令来查询数据，既不安全也不高效。

在开始正式使用前，花 10 分钟配置你最常用的 MCP 服务器（GitHub、文件系统、数据库），并为团队的高频操作创建自定义命令。这一步投入能将后续的效率提升放大数倍。

在 CLAUDE.md 中堆砌冗余规则

另一个常见反模式是把 CLAUDE.md 写成“百科全书“，包含 Claude 本身就能推断的规则（比如“使用 TypeScript“），或者过于详细的 API 文档。过长的 CLAUDE.md 会消耗宝贵的上下文窗口，导致后续对话中 Claude 对项目规则的遵循率下降，这被称为 “lost in the middle” 效应。

CLAUDE.md 应聚焦于 Claude 无法从代码推断的内容：构建命令、环境怪异之处、团队特有的架构决策、常见陷阱。保持在 200 行以内，把详细的 API 文档改为链接引用。定期审查和修剪 CLAUDE.md，删除不再适用的规则。

混淆 acceptEdits 和 bypassPermissions 的适用场景

有些开发者为了减少交互确认，直接使用 bypassPermissions 模式，即使他们的 Agent 需要执行写入操作。bypassPermissions 意味着 Agent 可以不经确认执行任何操作，包括删除文件、执行任意 Shell 命令、修改系统配置。在团队共享的项目中，一个人配置的宽松权限可能影响整个团队的安全边界。

正确做法是根据任务类型选择最小权限模式：只读分析用 plan，常规开发用 acceptEdits，只有在严格隔离的 CI/CD 沙箱环境中才考虑 bypassPermissions。使用 --permission-mode 标志或 /permissions 命令配置白名单，把常用的构建和测试命令加入 allow 列表。

适用场景与限制

仅支持 Claude 模型族

Claude Code 最显著的限制是只支持 Anthropic 的 Claude 模型系列（Sonnet、Opus、Haiku）。如果你的团队已经在使用 GPT-4o、Gemini 或其他模型，Claude Code 无法直接切换。这意味着你在不同项目中可能需要维护多套 AI 编程工具的配置，增加了团队的工具链复杂度。

对于需要多模型灵活切换的场景，OpenCode 提供了更好的支持。它内置了 75+ LLM 供应商的集成，可以在同一会话中按需切换模型。如果你的团队有混合模型需求，建议评估 OpenCode 作为替代方案。

缺乏代码级扩展 API

Claude Code 的扩展全部通过配置文件（CLAUDE.md、Skills JSON、Hook Shell 脚本）和外部进程（MCP 服务器）实现，没有类似 OpenCode definePlugin 的 TypeScript 回调 API。这意味着你无法在 Agent 进程内部拦截和修改任意行为——例如，你不能像 OpenCode 那样注册一个 Hook 在每次工具调用前注入自定义验证逻辑。

如果你需要深度定制 Agent 行为（比如实现复杂的审批流、自定义 Agent 编排），Claude Code 的配置驱动方式可能不够灵活。此时可以考虑使用 Agent SDK 进行编程式集成，或者迁移到扩展体系更丰富的 OpenCode。

工具集相对精简

Claude Code 内置工具集只有 7 个核心工具（Read、Write、Edit、Bash、Grep、Glob、WebFetch），没有 AST-grep、LSP、CodeGraph 等代码智能工具。对于需要精确代码重构、跨文件引用分析、AST 级别操作的场景，纯靠内置工具的 LLM 推理能力可能不够精确。

弥补方式是通过 MCP 服务器接入外部工具，或者使用 Agent SDK 的 tool() API 创建自定义工具。但这些都需要额外的配置和开发工作，不如 OpenCode 的开箱即用体验。

常见失败与陷阱

/init 生成的 CLAUDE.md 质量参差不齐

执行 /init 后 Claude Code 会自动生成 CLAUDE.md 文件，但生成质量取决于项目结构的清晰度和 Claude 的推断能力。对于技术栈不常见、目录结构不规范的项目，自动生成的 CLAUDE.md 可能包含错误的构建命令或遗漏关键规则。

不要盲目信任 /init 的输出。生成后必须人工审查：验证构建命令是否正确执行，检查是否有遗漏的环境变量要求，确认架构决策是否与团队约定一致。将审查后的 CLAUDE.md 提交到 Git，确保团队成员获得一致的行为。

MCP 服务器连接失败时的静默降级

Claude Code 在 MCP 服务器连接失败时不会中断会话，而是静默降级到不包含该工具的工作模式。这意味着你可能以为 Agent 有 GitHub 集成能力，实际上 MCP 服务器早已断开，Agent 在每次尝试调用时都失败但没有明确报错。

定期运行 /mcp 检查服务器连接状态。在 CI/CD 环境中，建议在会话启动时验证关键 MCP 服务器的可用性。对于生产级工作流，可以在 CLAUDE.md 中添加“如果 GitHub MCP 不可用，请明确告知用户“的指令，让 Claude 主动报告工具缺失。

上下文压缩导致早期指令丢失

Claude Code 的自动压缩（Compaction）在上下文接近窗口上限时触发，它会对较早的对话历史进行摘要。这意味着你在会话早期给出的详细指令可能在压缩后被简化或丢失，Agent 的行为在长会话中可能偏离预期。

关键规则和约束应该放在 CLAUDE.md 中而非对话 prompt 中。CLAUDE.md 在每次请求时都会重新注入，不受压缩影响。对于需要跨整个会话保持的重要状态，使用 /compact 时附带自定义指令来保留关键信息，或者拆分为多个短会话。

关联章节