Claude Code 使用
安装
npm install -g @anthropic-ai/claude-code
# 或
curl -fsSL https://claude.ai/install.sh | bash
# 更新
claude update
claude install
# 查看版本
claude --version- vscode 建议安装Claude Code插件
- 在对话框输入
/config进入设置,勾选Disable Login Prompt配置来关闭登录页面
- 在对话框输入
- 使用 bigmodel 模型配置
# https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys
# https://docs.bigmodel.cn/cn/coding-plan/tool/claude
# 实际修改的是 ~/.claude/settings.json
npx @z_ai/coding-helper常用指令
claude
claude [--verbose, --debug]
# unix
cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt
cat code.py | claude -p 'analyze this code for bugs' --output-format json > analysis.json
cat log.txt | claude -p 'parse this log file for errors' --output-format stream-json交互式 Slash 命令 (Interactive Slash Commands)
这些命令在 claude 交互模式下使用,以 / 开头。
| 命令 | 功能 | 示例 |
|---|---|---|
| /add-dir | 将额外的目录添加到当前会话上下文 | /add-dir ../frontend/src |
| /agents | 查看或管理自定义 AI 子代理 (Subagents) | /agents |
| /bashes(/tasks) | 列出或管理正在后台运行的 Bash 任务 | /bashes 或 /tasks |
| /clear | 清除当前会话的上下文历史 (重置记忆,但不删除文件) | /clear |
| /compact | 压缩当前对话上下文以节省 Token,可指定保留重点 | /compact "保留关于 API 错误的信息" |
| /config | 打开交互式配置菜单 (设置主题、通知等) | /config |
| /context | 可视化查看当前 Token 上下文的使用情况 | /context |
| /cost | 显示当前会话的 Token 消耗和估算费用 | /cost |
| /doctor | 运行诊断程序,检查安装、配置、网络及 MCP 状态 | /doctor |
| /exit | 退出 Claude Code 交互界面 | /exit |
| /export | 导出当前对话记录到文件 | /export ./chat_log.md |
| /help | 显示帮助信息,列出所有可用命令 | /help |
| /hooks | 管理工具事件的 Hook 配置 | /hooks |
| /ide | 管理 IDE 集成状态 (如 VS Code 连接) | /ide |
| /init | 在当前目录初始化项目,创建 CLAUDE.md 记忆文件 |
/init |
| /install-github-app | 安装 GitHub App 以集成 Pull Request 等功能 | /install-github-app |
| /login | 切换或登录 Anthropic 账号 | /login |
| /logout | 退出当前账号 | /logout |
| /mcp | 管理 MCP (Model Context Protocol) 服务器连接 | /mcp |
| /memory | 编辑 CLAUDE.md 项目记忆文件 (项目的长期记忆) |
/memory |
| /model | 切换当前使用的 AI 模型 (如 Sonnet, Opus 等) | /model |
| /output-style | 设置输出样式 (如 text, json) | /output-style |
| /permissions | 查看或更新工具的使用权限 | /permissions |
| /plan | 进入计划模式,让 Claude 先生成详细计划再执行 |
/plan "重构认证模块" |
| /plugin | 管理 Claude Code 插件 | /plugin |
| /pr-comments | 查看拉取请求 (Pull Request) 的评论 | /pr-comments |
| /release-notes | 查看版本发布说明 | /release-notes |
| /remote-env | 配置远程开发环境 (针对 claude.ai 订阅者) | /remote-env |
| /rename | 重命名当前会话 ID,便于后续查找 | /rename "AuthFix" |
| /resume | 恢复之前的某个会话 | /resume (显示列表供选择) |
| /review | 请求代码审查 (Review) | /review |
| /rewind | 时间倒流,撤销最近的一步操作或对话 |
/rewind |
| /status | 显示工具状态、版本及连接信息 | /status |
| /terminal-setup | (新增) 自动配置终端设置 (如修复 Shift+Enter 换行) | /terminal-setup |
| /theme | (新增) 更改界面颜色主题 (Light/Dark/Daltonize) | /theme |
| /todos | (新增) 列出对话中识别到的待办事项 | /todos |
| /usage | 显示当前计费周期的使用限额和状态 | /usage |
| /vim | 开启 Vim 风格的编辑模式 | /vim |
CLI 启动参数 (CLI Flags)
这些命令是在终端(Shell/PowerShell)中启动 claude 时使用的参数。
| 命令/参数 | 功能 | 示例 |
|---|---|---|
| claude | 启动标准交互式会话 | claude |
| claude “prompt” | 启动会话并带入初始提示词 | claude "解释当前目录结构" |
| -p, –print | 非交互模式:输出回复后立即退出 (适合管道/脚本) | cat log.txt | claude -p "分析错误" |
| -c, –continue | 继续上一次的会话上下文 | claude -c |
| -r, –resume ID | 恢复指定的会话 ID | claude -r <session_id> |
| –model | 指定本次会话使用的模型 | claude --model claude-3-5-sonnet |
| –add-dir | 启动时挂载额外目录 | claude --add-dir ./utils |
| –verbose | 启用详细日志 (Debug 模式) | claude --verbose |
| –allowedTools | 预设允许的工具,跳过权限确认 | claude --allowedTools "Bash,Read" |
| –disallowedTools | (补充) 禁止使用特定的工具 | claude --disallowedTools "Bash" |
| –dangerously-skip-permissions | 慎用:跳过所有权限询问,自动执行所有操作 | claude --dangerously-skip-permissions |
| –agent | 指定启动特定的 AI 代理 | claude --agent code-reviewer |
| –agents | (补充) 通过 JSON 动态定义子代理 | claude --agents '{"reviewer":{...}}' |
| –mcp-config | 指定 MCP 配置文件路径 | claude --mcp-config ./mcp.json |
| –max-turns | 限制对话的最大轮数 (常用于脚本自动化) | claude -p --max-turns 3 "任务..." |
| –output-format | 指定输出格式 (如 text, json) | claude --output-format json |
| –system-prompt | (补充) 替换默认的系统提示词 (System Prompt) | claude --system-prompt "你是Python专家" |
| –append-system-prompt | (补充) 在默认系统提示词后追加内容 | claude --append-system-prompt "总是写注释" |
| claude update | (命令) 更新 Claude Code 到最新版本 | claude update |
特殊语法与快捷键 (Special Syntax & Shortcuts)
在交互会话中提高效率的快捷操作。
| 符号/快捷键 | 功能 | 示例 |
|---|---|---|
| ! (感叹号) | 直接执行 Bash 命令,不经过 Claude 思考 | !ls -la |
| # (井号) | 快速添加内容到 CLAUDE.md (记忆文件) |
# 总是使用 TypeScript |
| @ (艾特符) | 引用文件或目录 (支持自动补全) | 解释 @src/main.py |
| Tab | 开启/切换 “Extended Thinking” (扩展思考模式) | 输入问题后按 Tab |
| Shift + Tab | (补充) 快速循环切换权限模式 (如从 Ask 切换到 Allow) | 输入时按 Shift+Tab |
| Shift + Enter | 多行输入 (换行而不发送) | 编写长 Prompt 时使用 |
| Ctrl + G | (补充) 在外部编辑器(如 Vim/Nano)中打开当前 Prompt 进行编辑 | 长文本编辑时非常有用 |
| Ctrl + O | (补充) 切换 Verbose 模式 (显示思考过程) | 调试 Claude 的推理逻辑 |
| Ctrl + C | 取消当前生成或输入 | 停止输出 |
| Ctrl + R | 搜索历史命令 | 类似 Shell 的搜索 |
| Ctrl + L | 清屏 (保留上下文,仅清除显示) | 清理界面显示 |
| Esc + Esc | 撤销/倒退 (Rewind) | 快速撤回上一步操作 |
| \ + Enter | (补充) 快速换行 (Quick Escape) | 替代 Shift+Enter 的另一种方式 |
memory
- 内存
- MEMORY.md 的前 200 行在每次对话开始时加载。第 200 行之后的内容在会话开始时不加载
- Claude 正在主动更新或读取
~/.claude/projects/<project>/memory/ /memory命令列出在当前会话中加载的所有 CLAUDE.md 和规则文件
其他命令
-
恢复分叉会话:
claude --continue --fork-session -
CLI 运行:
claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash" -
https://code.claude.com/docs/en/settings#tools-available-to-claude
-
claude 支持使用软连接 symlinks 共享 rules(参考)
-
claude 使用浏览器 https://code.claude.com/docs/zh-CN/chrome
环境变量
| 环境变量 (Variable) | 用途/说明 (Purpose) |
|---|---|
ANTHROPIC_API_KEY |
作为 X-Api-Key 标头发送的 API 密钥,通常用于 Claude SDK(如果是交互式使用,请直接运行 /login) |
ANTHROPIC_AUTH_TOKEN |
Authorization 标头的自定义值(在此处设置的值会自动添加 Bearer 前缀) |
ANTHROPIC_CUSTOM_HEADERS |
添加到请求中的自定义 HTTP 标头(格式为 Name: Value) |
ANTHROPIC_DEFAULT_HAIKU_MODEL |
指定默认的 Haiku 模型版本(参见模型配置) |
ANTHROPIC_DEFAULT_OPUS_MODEL |
指定默认的 Opus 模型版本(参见模型配置) |
ANTHROPIC_DEFAULT_SONNET_MODEL |
指定默认的 Sonnet 模型版本(参见模型配置) |
ANTHROPIC_FOUNDRY_API_KEY |
用于 Microsoft Foundry 身份验证的 API 密钥 |
ANTHROPIC_MODEL |
要使用的指定模型名称设置(参见模型配置) |
ANTHROPIC_LOG=debug |
开启 claude code debug日志 |
CLAUDE.md 总结
在 Claude Code 中,CLAUDE.md 是其官方指定的项目上下文入口文件。
| 文件路径 | 作用 |
|---|---|
| 项目根目录/CLAUDE.md | 项目共享的项目级配置,提交至 Git 供所有成员使用 |
| 项目根目录/CLAUDE.local.md | 个人本地覆盖配置,通常加入 .gitignore 避免影响他人 |
| 父目录/CLAUDE.md | 在 Monorepo 结构中自动继承的上级配置(递归向上查找) |
| 子目录/CLAUDE.md | 针对特定子模块/功能的独立配置(优先于父级配置加载) |
| ~/.claude/CLAUDE.md | 用户全局默认配置,适用于所有 Claude 会话的基线设定 |
CLAUDE.md -> AGENTS.md 使用说明
- CLAUDE.md 推荐写法:
Please follow the rules in @AGENTS.md
Claude Code 为了安全,在第一次遇到 CLAUDE.md 中的 @filename 引用时,会弹出一个一次性审批对话框,询问是否允许加载外部文件。
修复方法:找到你本机的配置文件(通常在 ~/.claude.json 或项目根目录下的 .claude/ 目录中),手动将审批状态改为 true。
{
`hasClaudeMdExternalIncludesApproved`: true
}修改后重启 Claude Code 会话。
Claude 对 @ 引用的解析比较敏感,请确保 CLAUDE.md 中的写法规范:
- 使用符号链接(Symlink)绕过加载逻辑 如果你希望多个 AI 工具(如 Cursor, OpenCode, Claude Code)共用一份规则,最稳妥的方法是使用符号链接。 由于 Claude Code 优先寻找 CLAUDE.md,你可以让 CLAUDE.md 直接指向 AGENTS.md:
# 在项目根目录下运行
ln -s AGENTS.md CLAUDE.md这样 Claude Code 在读取 CLAUDE.md 时,实际上就是在读取 AGENTS.md 的全部内容,不存在“引用失败”的问题。
显式强制加载:如果上述方法均无效,你可以在启动 Claude Code 后的第一次对话中显式要求它读取: “Please read AGENTS.md immediately to understand my project rules.”
强制深度思考
- 关键字
think harder
ultrathink
step-by-step reasoningcompaction
在 CLAUDE.md 中自定义 compaction 行为(参考):
# Compact instructions
When you are using compact, please focus on test output and code changesMCP
claude mcp add <name> <command> [args...]
# 示例
claude mcp add pg-server /path/to/postgres-mcp --connection-string "postgresql://user:pass@localhost:5432/mydb"# 查看已配置的服务
claude mcp list
# 查看服务详情
claude mcp get <name>
# 删除服务
claude mcp remove <name>
claude mcp add --transport http similarweb https://mcp.similarweb.com
claude mcp add slack --transport http https://mcp.slack.com/mcp
claude mcp add --transport http notion https://mcp.notion.com/mcp- 常用的
export CONTEXT7_API_KEY="xxx"
claude mcp add --transport http context7 https://mcp.context7.com/mcp \
--header "CONTEXT7_API_KEY: CONTEXT7_API_KEY"AI 自动化测试
npm init playwright@latest
claude mcp add playwright npx @playwright/mcp@latest
# 提示词
- 请使用 Playwright MCP 工具,分享当前项目中的 Web 页面,并生成完整的测试用例集
- 执行刚生成的所有测试用例,并输出测试结果
- 运行 npx playwright show-report 展示 html 报告Plugin
# 常用命令
/plugin install plugin-name@marketplace-name [--scope project]
/plugin uninstall plugin-name@marketplace-name [--scope project]
/plugin disable plugin-name@marketplace-name
/plugin enable plugin-name@marketplace-name
# marketplace 管理
/plugin marketplace list
/plugin marketplace update <marketplace-name>
/plugin marketplace remove <marketplace-name>
# 或
claude plugin install formatter@your-org
claude plugin uninstall formatter@your-org --scope project
/plugin marketplace add anthropics/claude-code
/plugin install frontend-design@claude-code-plugins
/plugin marketplace add ChromeDevTools/chrome-devtools-mcp
/plugin install chrome-devtools-mcp
# https://github.com/anthropics/skills
/plugin marketplace add anthropics/skills
/plugin marketplace add anthropics/claude-plugins-officialLanguage Server Protocol(lsp)
- 语言服务器协议(LSP)定义了编辑器或集成开发环境(IDE)与提供语言功能的语言服务器之间使用的协议,这些语言功能包括自动完成、转到定义、查找所有引用等。
- claude 支持的 lsp: https://code.claude.com/docs/en/discover-plugins#code-intelligence
/plugin install gopls-lsp@anthropics-claude-code
/plugin install pyright-lsp@anthropics-claude-code
/plugin install typescript-lsp@anthropics-claude-codeSkills (技能)
开源的 skills:
- https://skillsmp.com/
- https://skills.sh/vercel-labs/skills/find-skills find-skills 用来查找 skill
- https://github.com/openclaw/skills
- skills/felipeoff/ant-design-skill
Claude Code 技能遵循 Agent Skills 开放标准,该标准可在多种 AI 工具中使用。Claude Code 在该标准基础上扩展了额外功能,如调用控制、子代理执行和动态上下文注入。
示例:
$ cat ~/.claude/skills/explain-code/SKILL.md
---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
---
When explaining code, always include:
1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common mistake or misconception?
Keep explanations conversational. For complex concepts, use multiple analogies.使用:
/explain-code src/auth/login.ts- skill 支持级别
| Location | Path | Applies to |
|---|---|---|
| Personal | ~/.claude/skills/<skill-name>/SKILL.md |
All your projects |
| Project | .claude/skills/<skill-name>/SKILL.md |
This project only |
| Plugin | <plugin>/skills/<skill-name>/SKILL.md |
Where plugin is enabled |
- skill 结构
my-skill/
├── SKILL.md # 主要说明(必需)
├── template.md # Claude 要填写的模板
├── examples/
│ └── sample.md # 显示预期格式的示例输出
└── scripts/
└── validate.sh # Claude 可以执行的脚本- SKILL.md 支持的元数据
---
name: my-skill
description: What this skill does
disable-model-invocation: true
allowed-tools: Read, Grep
---- 支持的变量
| 变量 | 描述 |
|---|---|
$ARGUMENTS |
调用技能时传递的所有参数。如果内容中不存在 $ARGUMENTS,参数将作为 ARGUMENTS: <value> 追加。 |
${CLAUDE_SESSION_ID} |
当前会话 ID。用于日志记录、创建特定于会话的文件或将技能输出与会话关联。 |
第三方 skills
- https://skillsmp.com/zh
- https://github.com/affaan-m/everything-claude-code/ Claude Code 配置集合
- docs/zh-CN/skills/golang-patterns
- .agents/skills/api-design/SKILL.md
# Step 1: Install the Plugin
# Add marketplace
/plugin marketplace add affaan-m/everything-claude-code
# Install plugin
/plugin install everything-claude-code@everything-claude-code
# Step 2: Install Rules (Required)
# Clone the repo first
git clone https://github.com/affaan-m/everything-claude-code.git
cd everything-claude-code
# Recommended: use the installer (handles common + language rules safely)
./install.sh typescript # or python or golang or swift or php
# You can pass multiple languages:
# ./install.sh typescript python golang swift php
# or target cursor:
# ./install.sh --target cursor typescript
# or target antigravity:
# ./install.sh --target antigravity typescript
# Step 3: Start Using
# Try a command (plugin install uses namespaced form)
/everything-claude-code:plan "Add user authentication"
# Manual install (Option 2) uses the shorter form:
# /plan "Add user authentication"
# Check available commands
/plugin list everything-claude-code@everything-claude-codeHooks (钩子)
Hooks 允许在 Claude 执行流程的特定时间点运行 Shell 脚本。这是实现确定性自动化的关键。
- 配置文件:
.claude/settings.json - 文件格式:
json{ "hooks": [ { "name": "Format after edit", "event": "PostToolUse", "matcher": "Edit", // 当使用了 Edit 工具后触发 "command": "npx prettier --write \"$CLAUDE_MODIFIED_FILES\"" }, { "name": "Check sensitive info", "event": "PreToolUse", // 工具执行前拦截 "matcher": "Bash", "command": "./scripts/security-check.sh \"$CLAUDE_TOOL_INPUT\"" } ] } - 支持的事件:
PreToolUse/PostToolUse: 工具使用前后。UserPromptSubmit: 用户输入回车后。SessionStart/SessionEnd: 会话生命周期。
- 如何使用:配置后自动生效。主要用于代码格式化、Lint 检查、安全审计。
Subagents (子代理)
子代理是拥有独立上下文、特定权限和特定系统提示词 (System Prompt) 的 Claude 实例。它们适用于复杂的任务编排,避免主上下文被污染。
-
创建位置:
.claude/agents/my-agent.md -
文件格式 (.md):
markdown--- name: code-reviewer description: 专门负责代码审查的代理 tools: [Read, Bash] # 限制该代理只能读文件和运行命令,不能修改代码 skills: [security-best-practices] # 注入技能 --- 你是一个严格的代码审查员。你的目标是寻找代码中的安全漏洞和性能问题。 不要直接修改代码,而是生成一份 Markdown 格式的报告。 -
如何使用:
- 显式调用:在对话中告诉主 Agent:
请使用code-reviewer代理来检查这个文件。 - 通过 Flags 调用:
claude --agent code-reviewer
- 显式调用:在对话中告诉主 Agent:
-
核心优势:
- 上下文隔离:Reviewer 不会被主会话之前的聊天记录干扰。
- 权限控制:可以创建一个只读的 Agent,防止意外改坏代码。
Custom Commands、Skills、MCP、Hooks 和 Subagents 对比
| 功能模块 | 核心定义 | 典型用途 | 触发方式 | 复杂度 |
|---|---|---|---|---|
| Custom Commands | 可重用的 Prompt 模板 | 常用任务捷径(如 “总结PR”、“生成测试”) | 用户输入 /command |
⭐ 低 |
| Skills | 注入到上下文的知识/能力块 | 给 Agent 提供特定的领域知识或编码规范 | 被 Subagent 引用或自动加载 | ⭐⭐ 中 |
| MCP | 连接外部工具的标准协议 | 让 Claude 操作数据库、浏览器、GitHub 等 | Agent 自动调用工具 | ⭐⭐⭐ 高 (需配置服务) |
| Hooks | 生命周期事件触发器 | 自动化流程(如"保存后格式化"、“提交前检查”) | 自动触发 (Pre/Post Event) | ⭐⭐⭐⭐ 高 (涉及 Shell 脚本) |
| Subagents | 独立上下文的专用代理 | 隔离任务(如"代码审查员"、“架构师”) | 提示词调用或命令调用 | ⭐⭐⭐⭐⭐ 极高 |
自定义命令
- 用户级命令:
~/.claude/commands/,前缀/user:。 - 项目级命令:
.claude/commands/,前缀/project:。示例:创建optimize.md文件后,输入/project:optimize [args]自动执行optimize.md中的prompt,使用$ARGUMENTS介绍参数。
集成&工具
- 最佳实践
- https://code.claude.com/docs/zh-CN/best-practices
- 按 Ctrl+G 在文本编辑器中打开计划进行直接编辑
Claude Code GitHub Actions
ccusage 查看用来统计
npm install -g ccusage# 基础用法
ccusage # 显示每日报告(默认)
ccusage daily # 每日 token 使用量及费用
ccusage monthly # 月度汇总报告
ccusage session # 按会话统计用量
ccusage blocks # 5小时计费窗口数据
npx ccusage statusline # Compact status line for hooks (Beta)
# 实时监控
ccusage blocks --live # 实时用量仪表盘
# 筛选与选项
ccusage daily --since 20250525 --until 20250530 # 指定日期范围
ccusage daily --json # 输出 JSON 格式
ccusage daily --breakdown # 按模型细分费用cc-switch
- cc-switch 一款适用于 Claude Code、Codex 和 Gemini CLI 的跨平台桌面一体式辅助工具。它的核心作用是帮助开发者一键切换这些 AI 工具的“后台”(即 API 提供商、模型配置、系统提示词等),避免了频繁手动修改配置文件的繁琐过程。
- repair_claude_settings.py 修复 cc-switch 导致 ~/.claude/settings.json enabledPlugins 中缺少的 plugin 问题
参考
- https://code.claude.com/docs/zh-CN/overview
- https://code.claude.com/docs/zh-CN/features-overview
- https://code.claude.com/docs/en/overview
- https://code.claude.com/docs/en/slash-commands
- https://code.claude.com/docs/en/settings#environment-variables
- https://code.claude.com/docs/en/interactive-mode
- https://code.claude.com/docs/en/skills
- https://code.claude.com/docs/en/mcp
- https://code.claude.com/docs/zh-CN/gitlab-ci-cd
- https://www.npmjs.com/package/ccusage