Claude Code 使用指南

理解 Claude Code 的工作方式

Claude Code 是具备项目读写和工具执行能力的编码代理。

• 先确认位置：代码和工具在哪里运行，再核对账号、模型与权限。
• 入口差异：终端、IDE、桌面、网页和远程入口，不共享所有本机环境变量、认证后端和运行能力。

当前模型入口

• 可用别名：本次官方文档包含 best、fable、sonnet、opus、haiku 等；指向随提供商、账号和时间变化。
• default：清除覆盖，回到账号的运行时默认值。
• 需要复现：固定有权限的完整模型 ID，不沿用旧 Opus / Sonnet 版本号作为全局默认建议。

依据：产品概览 · 模型配置

五条日常工作原则

• 描述结果与验收，给足项目背景和约束；复杂缺陷提供原始日志与复现，不要求模型盲猜。
• 存在设计分歧时先计划，明确的小修改直接实施；不要让计划流程替代交付。
• 围绕当前任务选择必要上下文；AGENTS.md 与 CLAUDE.md 的加载方式不同，不假设完全互通。
• 依据当前文件运行适用验证；问题根因、可能风险和未测试路径分别说明。
• 授权与范围明确后持续完成，遇到阻塞报告证据与解除条件；不要自动扩展到推送、发布或发消息。

依据：官方实践

近期变化与版本边界

依据：官方发行说明 · 设置优先级 · 认证与提供商限制

安装、更新与首次验证

• 安装渠道：原生安装、Homebrew 等渠道各有更新机制。先检查路径与版本，排除多个安装相互遮蔽。
• Windows：原生 Windows 可用 PowerShell；需要 Linux 沙箱能力时再查 WSL 方案，不要求所有用户都使用 WSL。

# macOS / Linux / WSL 的官方原生安装入口示例
curl -fsSL https://claude.ai/install.sh | bash
# 或按官方 Homebrew 渠道（与上面二选一）
# brew install --cask claude-code
claude --version
claude --help
claude
# 会话内 /status 检查账号、模型和设置来源

• Homebrew：使用对应 cask 的 brew upgrade；不由 Claude 原生自动更新机制更新。
• 版本渠道：stable 与 latest 不同，先确认自己的安装来源。
• 首次任务：先确认仓库和验证入口，再做小范围修改。本页展示命令，不代替读者执行安装或登录。

依据：安装与平台差异 · 登录

命令速查

开始与继续会话

脚本与结构化输出

模型、权限与工作树

认证、扩展与诊断

会话内高频命令

查询状态与调整配置

计划、上下文与工具

依据：CLI 参考 · 交互模式

输入与快捷键

自定义按键、Vim 模式和终端冲突查当前官方交互文档。不能把某个桌面或 IDE 的键位写成所有入口通用。

依据：交互模式与快捷键

按需要选择扩展

依据：Skills · Hooks · MCP · 子代理

技能、Hooks、MCP 与子代理

Skills

• 项目技能：.claude/skills/<name>/SKILL.md。
• 个人与插件技能：个人目录为 ~/.claude/skills/，插件也可提供技能。
• 编写与移植：写清触发条件和输入/输出，长资源按需读取；跨代理移植时核对工具、权限和路径。

Hooks

• 触发方式：在对应设置层的 hooks 中配置，由事件触发。
• 先查语义：匹配器、同步/异步、超时、JSON 输出及非零退出的含义；不是每种 Hook 都能阻止动作。
• 避免重复负担：不要每次编辑都跑全量检查，也要防止停止后重复触发。

MCP

• 作用域：用户、本地项目和共享 .mcp.json 分别管理。
• 连接方式：HTTP 与 stdio 的认证不同；模型 API Key 和 MCP OAuth 也不是同一认证。
• 检查与登录：先用 claude mcp list 检查服务；支持的服务再用 claude mcp login <name> 登录。

Subagents

• 角色配置：按当前代理文档定义角色说明、工具、模型和权限。
• 交接证据：委派明确的调查、实现或审阅任务，不能只接收一句“完成”。
• 版本边界：嵌套、后台执行及额度上限按当前版本核实，不沿用旧教程的固定数字。

依据：Skills · Hooks · MCP · Subagents

订阅、账单与上下文

• 先减少浪费：控制无关文件和重复结果，明确范围，选合适模型并完成验收。
• 预算参数：--max-budget-usd、最大轮数等，按本机帮助与 costs 文档确认适用模式。
• 边界：不能将这些参数当成所有入口统一的绝对账单上限。

依据：费用 · 认证

图片、Artifacts 与电脑操作

• 入口差异：网页/桌面的 Artifacts、浏览器或电脑操作，与终端 Claude Code 的内置编码能力不同。
• 操作前：确认工具是否可用、执行的账号和机器，以及获准的操作范围。

• 产物格式：图片输入用于理解，不自动等于可编辑的 Figma / SVG。
• 分别验收：检查产物格式、交互行为和截图；截图通过不能代替功能测试。

浏览器任务参见 电脑与浏览器操作专题。

八类任务怎么交付

理解问题与实施改动

审阅、文档与自动化

先把任务做成可审查结果，再执行已授权的交付。分析请求不等于修改授权，实施请求也不自动包含推送、发布或对外发消息。

上下文、规则与记忆

• 团队规则：项目级 CLAUDE.md 保存稳定的构建、验证和行为约束；.claude/rules/ 用于分拆规则。
• 个人偏好：与团队规则分开管理。
• 加载范围：CLAUDE.local.md、导入语法和子目录加载按官方 Memory 文档核对；不需要一开始把所有文件全部塞进上下文。

依据：记忆与项目说明 · 上下文实践

权限规则、模式与沙箱

工具权限与 OS 沙箱分开看。

• 选择模式：Manual、自动审批、接受编辑、Plan、绕过权限等支持情况，查本机 --permission-mode 和官方文档。
• Auto mode：使用判断器减少提示，并非无条件批准。

{
  "permissions": {
    "allow": ["Bash(npm run lint)", "Bash(npm run test *)"],
    "deny": ["Read(./.env)", "Read(./.env.*)"]
  }
}

此例限制匹配的文件工具调用；不能单独保证这些内容无法经命令、MCP 或其他渠道读到。需要隔离时落实对应平台沙箱与服务权限，而非只给模型一句“不要读”。

依据：权限与规则 · 权限模式

设置文件与登录方式

配置层：与 Codex 的 TOML 不同

普通设置优先级：从上到下逐级降低。

1. 托管设置
2. CLI --settings
3. 项目 local 设置
4. 共享项目设置
5. 用户设置

• 环境变量：覆盖关系按字段决定，不作为统一的一层。例如 shell 的 ANTHROPIC_MODEL 与默认模型变量不同。
• 数组例外：通常合并，但 fallbackModel、modelPicker、availableModels、modelSettings 有专门规则。

• 格式：严格 JSON：不写注释，不留尾随逗号。
• 查看来源：/config 只展示部分选项；/status 的 Setting sources 展示加载来源，不是每个键的最终获胜来源。
• 生效方式：多数文件设置可热重载；model、effort 等用对应命令切换，并非改文件后全部立即生效。

关键配置分组

登录不止两种：先确定收费与凭据归属

• macOS：通常用 Keychain；写入失败时，部分登录可回退到受限权限凭据文件。Console 创建 Key 的场景还有额外限制。
• Linux / Windows：各有对应凭据存储路径。
• 分享前检查：不要把认证文件、setup-token 输出或真实密钥贴进配置示例。

依据：设置文件与优先级 · 全部设置字段 · 认证与存储

与 Codex 等工具协作

• 协作分工：一个实施，一个基于同一基线独立审阅，以源码和验证结果决定结论。
• 移植范围：Skills 目录有可复用部分；Hook 事件、权限字段、项目说明和提供商协议需分别检查。

1. 先用 claude import codex --dry-run 预览当前工具支持的转换。
2. 检查来源和目标文件，再决定是否实施；本页没有执行导入。

Codex 提供商与认证的完整关系见 config.toml 配置专题。

依据：CLI import

常见误区与排错顺序

• 版本先确认：文档新增项可能未在本机版本出现；别名解析和账号权限不能从产品名称推出。
• 设置不生效先看 /status 来源与 doctor，不先删除整个 ~/.claude 或重新登录。
• 不要把设了 ANTHROPIC_BASE_URL 解释成已切换凭据、套餐或协议；网关认证和上游认证可能不同。
• 不要认为 .claude/settings.local.json 永远自动被 Git 忽略；手工创建后应实际检查。
• /clear、/compact、低档模型与后台代理都不承诺固定省费比例或重置额度。
• 恢复、回滚与删除任务前看清影响；代码回滚、对话回滚和外部服务副作用并不相同。

依据：设置排错 · 费用

可改写的任务模板

目标：<用户可观察的行为或产物>
范围：<相关模块、允许写入位置、必须保持的不变量>
依据：<当前版本、日志、复现与官方来源>
验收：<必要检查及通过条件>
执行：在授权范围完成工作；存在实质分歧先说明，普通实施细节自行决定。
交付：结果、文件位置、验证证据、推断与未验证范围；不自动扩大为发布操作。

• 代码审查：写明“只审查，不修改被审对象”，并给出比较基线。
• 生产缺陷：增加数据来源和版本。
• 配置排错：补充认证方式、目标端点与启动入口，不只给一张缺少环境说明的截图。

本机诊断与信息保护

claude --version
claude --help
claude auth status
claude doctor
claude mcp list
# 会话内：/status、/permissions、/context、/usage
# 若本机 help 支持 --safe-mode，可用其隔离自定义扩展进行排查

• 确认能力：用命令帮助和只读诊断查看支持范围。
• 安全模式：--safe-mode 可关闭多类自定义扩展，但组织策略仍有效，不能用来绕过限制。
• 分享日志：去除环境变量中的敏感值、凭据文件和完整调试输出中的秘密。
• 服务验证：记录实际入口、模型、认证方式和时间。

依据：CLI 参考

官方资料与验证范围

• 产品概览 · 安装 · 发行说明
• CLI · 交互模式 · 模型
• 设置文件 · 全部设置 · 认证
• 权限 · 记忆 · 费用
• Skills · Hooks · MCP · 子代理

• 核对日期：2026-10-20；官方发布版本与本机版本分开记录。
• 已核对：官方资料与本机 --help，没有升级软件、修改个人设置或登录第三方服务。
• 仍需实测：API / 网关、平台差异与账号权限，需在目标环境验收。