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

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:

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 Line Flags

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

Multiline Input

Vim Mode

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

Vim Mode Switching

Vim Navigation

Vim Editing

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.

1. 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

1. Start → type: Environment Variables
2. Open Edit the system environment variables → Environment Variables
3. Under User variables select Path → Edit → New add:
   • C:\Users\<you>\AppData\Roaming\npm
   • C:\Program Files\nodejs
4. 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

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

Monitoring & Alerting

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

Collaboration Best Practices

1. Share versioned configuration: Commit .claude/settings.json to the repo.
2. Documentation automation: Update docs with explicit tasks.
3. 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.