Claude Code 使用指南：从安装配置到高级自动化

Claude Code 完整手册

Getting Started

Enable sound alerts when claude completes the task:

claude config set --global preferredNotifChannel terminal_bell

Quick Start

Send claude or npx claude in terminal to start the interface Go to Help & Troubleshooting to fix issues…

# Node.js 18+ (Universal Method)
npm install -g @anthropic-ai/claude-code

# Windows (CMD)
npm install -g @anthropic-ai/claude-code

# Windows (PowerShell)
irm https://claude.ai/install.ps1 | iex

# WSL/Git
npm install -g @anthropic-ai/claude-code

# MacOS
brew install node && npm install -g @anthropic-ai/claude-code

# Linux
sudo apt update && sudo apt install -y nodejs npm
npm install -g @anthropic-ai/claude-code

# Arch
yay -S claude-code

# Docker
# Windows (CMD)
docker run -it --rm -v "%cd%:/workspace" -e ANTHROPIC_API_KEY="sk-your-key" node:20-slim bash -lc "npm i -g @anthropic-ai/claude-code && cd /workspace && claude"
# macOS/Linux (bash/zsh)
docker run -it --rm -v "$PWD:/workspace" -e ANTHROPIC_API_KEY="sk-your-key" node:20-slim bash -lc 'npm i -g @anthropic-ai/claude-code && cd /workspace && claude'

# Check installation
which claude # Linux
where claude # Windows
claude --version # Universal

# Common Management
claude config # Configure settings
claude mcp list # Setup MCP servers
claude /agents # Configure Subagents
claude update # Update to latest

Open Project Via Terminal Into VS Code / Cursor:
cd /path/to/project
code .

Make sure you have the Claude Code extension installed in your VS Code / Cursor.

System Requirements

OS: macOS 10.15+, Ubuntu 20.04+/Debian 10+, or Windows 10/11 or WSL
Hardware: 4GB RAM minimum, 8GB+ recommended
Software: Node.js 18+ or git 2.23+ (optional) & GitHub or GitLab CLI for PR workflows (optional)
Internet: Connection for API calls

Initial Setup

Find API key from Anthropic Console. Do NOT commit real keys; use git-ignored files, OS key stores, or secret managers.

# Universal
claude /login
claude setup-token

# Windows
set ANTHROPIC_API_KEY=sk-your-key-here-here
setx ANTHROPIC_API_KEY "sk-your-key-here-here"

# Linux
export ANTHROPIC_API_KEY="sk-your-key-here-here"
unset ANTHROPIC_API_KEY

# PowerShell
$env:ANTHROPIC_API_KEY = "sk-your-key-here-here"
[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY","sk-your-key-here-here","User")

# Persist Bash/Zsh/Fish
echo 'export ANTHROPIC_API_KEY="sk-your-key-here-here"' >> ~/.bashrc && source ~/.bashrc
echo 'export ANTHROPIC_API_KEY="sk-your-key-here-here"' >> ~/.zshrc && source ~/.zshrc
fish -lc 'set -Ux ANTHROPIC_API_KEY sk-your-key-here-here'

Configuration & Environment

Environment Variables

You can also set any of these in settings.json under the 'env' key for automatic application.

Windows Users replace export with set or setx for permanent changes.

export ANTHROPIC_API_KEY="sk-your-key-here-here"
export ANTHROPIC_AUTH_TOKEN="my-auth-token"
export ANTHROPIC_MODEL="claude-sonnet-4-20250514"
export BASH_DEFAULT_TIMEOUT_MS=60000
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096
export DISABLE_TELEMETRY=0
export HTTP_PROXY="http://proxy:8080"
export HTTPS_PROXY="https://proxy:8443"

Global Config Options

claude config set-g theme dark
claude config set-g preferredNotifChannel iterm2_with_bell
claude config set-g autoUpdates true
claude config set-g verbose true
claude config set-g includeCoAuthoredBy false
claude config set-g model "claude-3-5-sonnet-20241022"
claude config set-g enableAllProjectMcpServers true
claude config set-g enabledMcpjsonServers '["memory","github"]'
claude config set-g disabledMcpjsonServers '["filesystem"]'

Configuration Files

Claude Code offers four memory locations in a hierarchical structure:

Memory Type	Location	Purpose
Enterprise policy	`/Library/Application Support/ClaudeCode/CLAUDE.md` (macOS)	Organization-wide instructions managed by IT/DevOps
Project memory	`./CLAUDE.md`	Team-shared instructions for the project
User memory	`~/.claude/CLAUDE.md`	Personal preferences for all projects
Project memory (local)	`./CLAUDE.local.md`	Personal project-specific preferences

All memory files are automatically loaded into Claude Code's context when launched. Files higher in the hierarchy take precedence.

Commands & Usage

Claude Commands

Command	Purpose
`/add-dir`	Add additional working directories
`/agents`	Manage custom AI subagents
`/bug`	Report bugs
`/clear`	Clear conversation history
`/compact`	Compact conversation
`/config`	View/modify configuration
`/cost`	Show token usage statistics
`/doctor`	Checks health of installation
`/help`	Get usage help
`/init`	Initialize project with CLAUDE.md
`/login`	Switch Anthropic accounts
`/mcp`	Manage MCP server connections
`/memory`	Edit CLAUDE.md memory files
`/model`	Select or change the AI model
`/permissions`	View or update tool permissions
`/review`	Request code review
`/vim`	Enter vim mode

Command Line Flags

Flag / Command	Description
`-d, --debug`	Enable debug mode
`--verbose`	Override verbose mode setting
`-p, --print`	Print response and exit
`--output-format <format>`	Output format (text, json, stream-json)
`--allowedTools`	Comma/space-separated list of allowed tools
`--disallowedTools`	List of denied tools
`--mcp-config`	Load MCP servers from JSON files
`--permission-mode`	Permission mode for the session
`--model <model>`	Model for the current session
`--continue`	Continue most recent conversation
`--dangerously-skip-permissions`	Bypass all permission checks

Cheat Sheet

# Basics
claude # Start interactive REPL
claude "explain this project" # Start REPL seeded with prompt
claude -p "summarize README.md" # Non-interactive print mode
cat logs.txt | claude -p "explain" # Pipe input to Claude

# Update & Install
claude update
claude doctor
claude migrate-installer

# Config
claude config get <key>
claude config set <key> <val>
claude config add <key> <vals…>
claude config remove <key> <vals…>
claude config list

# MCP Management
claude mcp list
claude mcp add <name> <command>
claude mcp remove <name>

# Other useful flags
claude --add-dir ../apps ../lib
claude --allowedTools "Bash(git log:*)" "Read"
claude --dangerously-skip-permissions

Interface & Input

Keyboard Shortcuts

Shortcut	Description
`Ctrl+C`	Cancel current input or generation
`Ctrl+D`	Exit Claude Code session
`Ctrl+L`	Clear terminal screen
`Up/Down arrows`	Navigate command history
`Esc + Esc`	Edit previous message

Multiline Input

Method	Shortcut
Quick escape	`\` + `Enter`
macOS default	`Option+Enter`
Terminal setup	`Shift+Enter`
Control sequence	`Ctrl+J`

Vim Mode

Enable vim-style editing with /vim command or configure permanently via /config.

Vim Mode Switching

Command	Action
`Esc`	Enter NORMAL mode
`i`	Insert before cursor
`a`	Insert after cursor
`o`	Open line below

Command	Action
`h/j/k/l`	Move left/down/up/right
`w/e/b`	Word navigation
`gg/G`	Beginning/End of input

Vim Editing

Command	Action
`x/dd/D`	Delete character/line/end of line
`cc/C`	Change line
`.`	Repeat last change

Command History

Claude Code maintains command history for the current session:

History is stored per working directory
Cleared with /clear command
Use Up/Down arrows to navigate
Ctrl+R: Reverse search through history (if supported)
History expansion (!) is disabled by default

Advanced Features

Thinking Keywords

Gives Claude extra pre-answer planning time by adding ONE of these keywords to your prompt.

Planning the solution
- Checking constraints & edge cases
- Weighing alternatives/trade-offs
- Breaking down steps

Examples:

claude -p "Think. Outline a plan to refactor the auth module."
claude -p "Think harder. Draft a migration plan from REST to gRPC."
claude -p "Ultrathink. Propose a step-by-step strategy to fix flaky payment tests."

Sub Agents

Sub‑Agents are purpose‑built helpers with their own prompts, tools, and isolated context windows.

Create your core agents

planner (read‑only): turns features/issues into small, testable tasks.
codegen (edit‑capable): implements tasks.
tester (read‑only or patch‑only): writes failing tests.
reviewer (read‑only): leaves structured review comments.
docs (edit‑capable): updates documentation.

Example prompt (tester.prompt.md):

Role: Write a single, focused failing test for the specific scenario I describe.
Scope: Only create/modify tests under tests/. Do not change src/.
Output: A brief rationale + a unified diff or patch.

MCP Integration

Understanding MCP (Model Context Protocol)

MCP extends Claude's capabilities by connecting to external services, databases, APIs, and tools.

MCP Setup & Configuration

Basic MCP Commands:

claude mcp # Interactive MCP configuration
claude mcp list # List configured servers
claude mcp add <name> <cmd> # Add new server
claude mcp remove <name> # Remove server

Configuration File Location:

~/.claude.json - Global File
.mcp.json - Project-scoped servers

Popular MCP Servers:

Development Tools: git-mcp-server, github-mcp-server
Database Integration: postgres-mcp-server, mysql-mcp-server

MCP Tool Permissions

claude --allowedTools "mcp__git__commit,mcp__git__push"
claude --allowedTools "Edit,View,mcp__git__*"

Hooks System

Hooks allow implementing custom logic based on events.

Configuration

Hooks are configured in settings files:

~/.claude/settings.json - User settings
.claude/settings.json - Project settings
.claude/settings.local.json - Local project settings

Structure:

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [{"type": "command", "command": "your-command-here"}]
      }
    ]
  }
}

Hook Events

PreToolUse: Runs before processing a tool call.
PostToolUse: Runs immediately after a tool completes.
Notification: Runs when Claude needs permission or is idle.
UserPromptSubmit: Runs when user submits a prompt.
Stop: Runs when agent finishes responding.
SessionStart: Runs when starting a new session.

Security Considerations

USE AT YOUR OWN RISK: Claude Code hooks execute arbitrary shell commands on your system automatically. By using hooks, you acknowledge that you are solely responsible for the commands you configure.

Always review and understand any hook commands before adding them to your configuration.

Security & Permissions

Dangerous Mode

NEVER use in Production systems, shared machines, or any systems with important data. Only use with isolated environments like a Docker container.

claude --dangerously-skip-permissions

Security Best Practices

Keep ~/.claude.json private (chmod 600).
Prefer environment variables for API keys over plain-text.
Use --strict-mcp-config to only load MCP servers from specified config files.
Validate and sanitize inputs in hooks.
Always quote shell variables.

Automation & Integration

Automation & Scripting with Claude Code

GitHub Actions integration allows automated reviews and triage.

Auto PR Review (inline comments)

File: .github/workflows/claude-pr-auto-review.yml

name: Auto review PRs
on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]
jobs:
  auto-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Claude PR review
        uses: anthropics/claude-code-action@main
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          direct_prompt: |
            Review this pull request's diff for correctness, readability, testing, performance, and DX.
          allowed_tools: >-
            mcp__github__get_pull_request_diff,
            mcp__github__create_pending_pull_request_review,
            mcp__github__add_comment_to_pending_review,
            mcp__github__submit_pending_pull_request_review

Issue Triage

File: .github/workflows/claude-issue-triage.yml

name: Claude Issue Triage
on:
  issues:
    types: [opened, edited, reopened]
jobs:
  triage:
    runs-on: ubuntu-latest
    env:
      CLAUDE_MODEL: claude-3-5-sonnet-20241022
    steps:
      - name: Ask Claude for triage JSON
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          # Collect context and ask Claude
          cat > payload.json << 'JSON'
          { "model": "${{ env.CLAUDE_MODEL }}", ... }
          JSON
          curl -s https://api.anthropic.com/v1/messages ...

Help & Troubleshooting

Debug Quick Commands

Check the output of claude doctor for log locations and environment checks.

Path Temp Fix

Your PATH likely doesn't include the global npm bin directory.

Windows (CMD): C:\Users\<you>\AppData\Roaming\npm
Windows (PowerShell): C:\Program Files\nodejs
Linux/MacOS (bash/zsh): $(npm config get prefix)/bin

Windows Path Perm Fix

Start → type: Environment Variables
Open Edit the system environment variables → Environment Variables
Under User variables select Path → Edit → New add:
- C:\Users\<you>\AppData\Roaming\npm
- C:\Program Files\nodejs
Click OK. Open a new Command Prompt/PowerShell and verify:
- where claude
- claude doctor

Installation / Node.js Issues

Must be Node 18+ (20+ recommended).

node --version
npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

Authentication Issues

Verify your Anthropic API key is available to the CLI.

# PowerShell (Windows)
echo $env:ANTHROPIC_API_KEY
claude -p "test" --verbose

# bash/zsh (macOS/Linux)
echo $ANTHROPIC_API_KEY
claude -p "test" --verbose

Full Clean Reinstall (Windows / PowerShell)

Uninstall the global npm package and remove leftover files.

npm uninstall -g @anthropic-ai/claude-code
Remove-Item -LiteralPath "$env:USERPROFILE\.claude\downloads\*" -Recurse -Force
Remove-Item -LiteralPath "$env:USERPROFILE\.claude.json" -Force
npm install -g @anthropic-ai/claude-code

Best Practices

Effective Prompting

Good: Specific and detailed (claude "Review UserAuth.js for security vulnerabilities...")
Bad: Vague (claude "check my code")

Tip: claude "query" starts the interactive REPL pre-seeded with your prompt; claude -p "query" runs print mode (non-interactive) and exits.

Performance Tips

Pick the right model (CLI aliases: --model sonnet or --model opus).
Limit context scope (--add-dir ./services/api).
Keep sessions tidy (claude config set-g cleanupPeriodDays 20).
Bound non-interactive work (--max-turns 3).
Use machine-readable output in automations (--output-format json).

Monitoring & Alerting

Health checks: Use claude doctor.
Log analysis batch job: Daily analysis with non-interactive JSON output.
Telemetry: Claude Code emits OpenTelemetry metrics/events.

Collaboration Best Practices

Share versioned configuration: Commit .claude/settings.json to the repo.
Documentation automation: Update docs with explicit tasks.
Code review standards: Review local diffs with constrained tools.

Common Pitfalls to Avoid

Security: Don't use --dangerously-skip-permissions on production systems. Don't hard-code secrets.
Performance: Don't load an entire monorepo when you only need a package.
Workflow: Don't skip project context (CLAUDE.md). Be specific in prompts.

Third-Party Integrations

DeepSeek Integration

Have Claude Code installed:

npm install -g @anthropic-ai/claude-code

Config Environment Variables:

export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=${YOUR_API_KEY}
export ANTHROPIC_MODEL=deepseek-chat

Now launch claude. Find more information from the Official Deepseek Docs.

Conclusion

Claude Code provides a powerful terminal-based interface for AI-assisted development. This guide covered installation, configuration, advanced features like Sub-Agents and Hooks, and integration with CI/CD pipelines. By following security best practices and optimizing prompts, developers can effectively leverage AI to enhance productivity and code quality.