Claude Code 安装、配置与使用完全指南

前言

Claude Code 是 Anthropic 推出的终端原生 AI 编程助手。它不像 Copilot 那样只在 IDE 里补全代码，
而是直接在终端中以代理（Agent）的方式工作：读懂整个项目、自己动手改文件、跑命令、提交代码，
并能调用外部工具、浏览器、子代理协同完成任务。

它的设计哲学是**”在开发者真正工作的地方工作”**——终端 + 代码仓库，而不是网页聊天框。
这让它特别适合：

• 在大型代码库中跨文件重构
• 自动化完成重复性的工程任务（写测试、修 lint、批量迁移）
• 配合 MCP（Model Context Protocol）扩展能力（数据库、GitHub、Playwright）
• 嵌入 CI/CD 做自动化 PR Review、Issue 处理
• 团队内统一升级与策略下发（Managed Settings）

本文是一份从零到生产的完整指南，覆盖安装、认证、配置、日常使用、高级特性、性能调优、CI/CD 集成与团队管理。

一、安装

1.1 平台与前置要求

Claude Code 提供多种安装方式，覆盖 macOS、Linux、WSL、Windows：

建议个人开发者选原生安装或 npm 全局安装（自动后台更新，体验最好）；
团队/CI 环境可用包管理器版本（更可控）。

1.2 原生安装（推荐）

macOS / Linux / WSL

1
2
3
4
5
6
7
8

# 安装最新版本（latest 通道）
curl -fsSL https://claude.ai/install.sh | bash

# 安装 stable 通道（滞后约一周，更稳定）
curl -fsSL https://claude.ai/install.sh | bash -s stable

# 安装指定版本
curl -fsSL https://claude.ai/install.sh | bash -s 2.1.195

安装位置默认在 ~/.local/bin/claude（会被自动加入 PATH）。
如果安装后 claude 命令找不到，手动追加到 ~/.bashrc 或 ~/.zshrc：

1

export PATH="$HOME/.local/bin:$PATH"

Windows（PowerShell）

1
2
3
4
5

# 安装 latest
irm https://claude.ai/install.ps1 | iex

# 安装指定版本
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 2.1.195

1.3 npm 全局安装

1
2
3
4
5

# 安装最新
npm install -g @anthropic-ai/claude-code@latest

# 安装指定版本
npm install -g @anthropic-ai/claude-code@2.1.195

⚠️ 不要用 npm update -g @anthropic-ai/claude-code（会按 semver 范围走，可能跳不到最新）。
也不要用 sudo npm install -g（避免权限问题）。

如果遇到 EACCES 错误，把 npm 全局目录改成当前用户可写：

1

sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

或改用原生安装器一劳永逸避开 npm 权限问题。

1.4 包管理器安装

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# macOS / Linux Homebrew
brew install --cask claude-code         # stable
brew install --cask claude-code@latest  # latest

# Windows WinGet
winget install Anthropic.ClaudeCode

# Debian / Ubuntu
sudo apt install claude-code

# Fedora / RHEL
sudo dnf install claude-code

# Alpine
apk add claude-code

1.5 验证安装

1
2
3
4

claude --version        # 看当前版本
claude doctor           # 看健康状态、最近一次更新、配置问题
which claude            # 看安装路径（macOS/Linux）
where.exe claude        # Windows

二、认证与登录

2.1 三种认证方式

用 Claude 订阅登录

1
2

claude
# 在交互界面输入 /login，浏览器跳转到 claude.ai 完成 OAuth

用 API Key

写到 ~/.claude/settings.json：

1
2
3
4
5

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-..."
  }
}

或用环境变量：

1
2

export ANTHROPIC_API_KEY="sk-ant-..."
claude

用 Amazon Bedrock

1
2
3
4

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-west-2
export ANTHROPIC_MODEL=us.anthropic.claude-sonnet-4-6-20260101
claude

用 Google Vertex AI

1
2
3
4

export CLAUDE_CODE_USE_VERTEX=1
export ANTHROPIC_VERTEX_PROJECT_ID=my-project-id
export CLOUD_ML_REGION=us-central1
claude

用自建代理 / 中转站

1
2
3

export ANTHROPIC_BASE_URL="https://your-proxy.example.com"
export ANTHROPIC_AUTH_TOKEN="sk-..."
claude

2.2 给 CI 用的长期 Token

1

claude setup-token

生成的 OAuth Token 可放进 ANTHROPIC_API_KEY 环境变量，不需要每个 CI job 重新登录。
适合自托管 Runner 场景。

2.3 验证认证

1

claude auth status      # JSON 格式输出认证状态

三、配置体系

Claude Code 的配置是多层级、覆盖式的。优先级从高到低：

1. Enterprise managed（企业下发，无法被覆盖）
2. CLI 参数（--model、--permission-mode 等）
3. settings.local.json（本地，gitignore）
4. settings.json（项目级，提交 git）
5. 用户级 ~/.claude/settings.json

3.1 常用 settings.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

{
  "env": {
    "ANTHROPIC_MODEL": "claude-sonnet-4-6",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com",
    "API_TIMEOUT_MS": "600000",
    "CLAUDE_CODE_MAX_RETRIES": "10"
  },
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(npm test *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl *)",
      "Bash(rm -rf *)",
      "Read(./.env)",
      "Read(./secrets/**)"
    ]
  },
  "enableAllProjectMcpServers": true,
  "claudeMdExcludes": [
    "**/node_modules/**/CLAUDE.md",
    "**/vendor/**/CLAUDE.md"
  ]
}

关键字段说明：

• permissions.allow / permissions.deny：工具白/黑名单，匹配规则自动放行，省掉每次点 “yes”。
• enableAllProjectMcpServers：让项目内 .mcp.json 自动批准（不用每次启动确认）。
• claudeMdExcludes：排除不需要加载的 CLAUDE.md（节省 token）。

3.2 关键环境变量

3.3 配置加载路径

四、CLAUDE.md：让 Claude 真正理解你的项目

CLAUDE.md 是 Claude Code 自动加载的项目级 prompt 文件。
写得好的 CLAUDE.md 能让 Claude 一次就做对，写得差的会让它反复犯同样的错。

4.1 CLAUDE.md 该写什么

• 构建/测试/lint 的具体命令（让 Claude 直接跑）
• 核心架构决策（为什么用 Postgres 不用 Mongo）
• 强约束 / 不变量（比如”所有 API 必须走 DRF”、”绝不直接 JOIN 用户表”）
• 命名规范和目录约定（比如”业务代码放 apps/，工具代码放 lib/“）
• 团队的 review checklist（PR 提交前要做什么）

4.2 不该写什么

• 通用编程知识（Python 怎么写类、JS 闭包）
• 长段历史背景
• 完整 API 文档（那种放 skill 按需加载）
• 流程化操作清单（那种也放 skill）
• 复制来的 README

4.3 一个真实的示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

# 项目说明

## 构建与运行
- 安装依赖：`uv sync`
- 跑测试：`uv run pytest`
- 代码格式化：`uv run ruff format .`
- 类型检查：`uv run mypy src/`
- 启动开发服务：`uv run python -m myproject`

## 架构
- 后端：FastAPI + SQLAlchemy 2.0（async）+ Alembic
- 数据库：PostgreSQL 16（主从，主库 10.0.0.1，从库 10.0.0.2）
- 缓存：Redis 7
- 队列：Celery + Redis broker

## 目录约定
- `src/myproject/api/`：HTTP 路由
- `src/myproject/services/`：业务逻辑层（不依赖 FastAPI）
- `src/myproject/models/`：SQLAlchemy ORM
- `src/myproject/schemas/`：Pydantic 模型
- `tests/`：pytest，文件名 `test_*.py`

## 强约束
1. 所有数据库访问必须走 `services/`，**不允许**在 API 层直接查 ORM
2. 任何外部 HTTP 调用必须用 `httpx.AsyncClient`，禁止用 `requests`
3. 数据库迁移必须用 Alembic 自动生成，**禁止**手动改 schema
4. 敏感配置走环境变量，从 `src/myproject/config.py` 读取
5. 任何 PR 必须包含测试，覆盖率不低于 80%

## 提交规范
- Commit 标题不超过 50 字符
- 格式：`<type>(<scope>): <subject>`，type 取 feat/fix/refactor/test/docs/chore
- Body 写清楚"为什么"而不是"做了什么"

4.4 嵌套 CLAUDE.md

Monorepo 中可以在子目录放 CLAUDE.md，只在 Claude 编辑该子目录的文件时自动加载，
节省主上下文 token。

1
2
3
4
5
6
7

monorepo/
├── CLAUDE.md              # 顶层（项目级）
├── apps/
│   ├── web/CLAUDE.md      # 仅 web 子目录编辑时加载
│   └── api/CLAUDE.md      # 仅 api 子目录编辑时加载
└── packages/
    └── shared/CLAUDE.md

4.5 自动生成

1

/init

扫描项目结构、依赖、配置，自动生成一份 CLAUDE.md 草稿。

五、核心使用

5.1 交互模式

1
2

cd /path/to/project
claude

进入 REPL 后可用命令：

5.2 常用工作流

探索陌生代码库

1

claude "这个项目是做什么的？给我画一张架构图"

修 bug

1

claude "登录接口偶发 500，看下 logs/auth.log 找到根因并修复"

重构

1

claude "把 src/services/order.py 重构成 strategy 模式，要保留所有现有测试"

写测试

1

claude "为 src/api/users.py 里所有 handler 补单元测试，覆盖率不低于 90%"

写 commit

1
2
3

git add -p
claude
> /commit

5.3 权限模式（Permission Modes）

按 Shift+Tab 在以下模式间循环：

CLI 启动指定：

1
2
3
4

claude --permission-mode plan
claude --permission-mode acceptEdits
claude --permission-mode auto
claude --dangerously-skip-permissions

5.4 Plan Mode（先思考后动手）

适合复杂任务：

1
2

claude --permission-mode plan
> 帮我把单体应用拆成微服务

Claude 读代码、搜索、出方案、列出 4 个选项让你选：

1. 批准并自动（切到 auto 模式开干）
2. 批准并接受编辑（切到 acceptEdits）
3. 批准并人工审（先看每一步 diff）
4. 继续规划（还要更多细节）

按 Ctrl+G 可以用你熟悉的编辑器打开当前 plan 修改后再批准。

5.5 OpusPlan 别名

opusplan 模型别名：plan 阶段用 Opus（推理强），实施阶段自动切 Sonnet（省 cost）。
适合”先思考、后落地”的场景。

1

claude --model opusplan "重构订单系统"

5.6 模型选择

1
2

/model                 # 交互选
claude --model opus     # 命令行

5.7 推理深度（Effort）

1

/effort                # 交互选

5.8 续接会话

1
2
3
4
5

claude -c                              # 续当前目录最近 session
claude -r auth-refactor "继续"          # 按 ID 或名字续
claude -r auth-refactor --fork-session # 续但开新 ID（探索分支）
claude --from-pr 123                   # 从 PR 关联的 session 续
claude -n "name"                       # 给 session 起名（prompt bar 显示）

避免每次开新 session 重复加载 CLAUDE.md 与 auto memory。

六、Slash Commands / Skills（自定义命令）

Claude Code 的”自定义命令”已经统一在 Skills 体系下。Skills 是带 frontmatter 的 Markdown 文件，
可被用户手动调用或被 Claude 自动触发。

6.1 Skill 存放位置

6.2 最小示例

.claude/skills/summarize-changes/SKILL.md：

1
2
3
4
5
6
7
8
9
10
11

---
description: Summarize uncommitted changes and flag risks
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize in 2-3 bullets, list risks.

调用：

1

/summarize-changes

6.3 动态上下文注入

用 !`command` 在 Claude 看到内容前就把 shell 输出塞进 prompt。

.claude/skills/pr-summary/SKILL.md：

1
2
3
4
5
6
7
8
9

---
name: pr-summary
context: fork
agent: Explore
---

- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

6.4 关键 frontmatter

6.5 参数替换

七、Hooks（自动化钩子）

Hooks 让 Claude 在工具调用前后自动跑命令。官方支持 24+ 事件：

PreToolUse / PostToolUse / PostToolUseFailure / UserPromptSubmit /
SessionStart / SessionEnd / Stop / StopFailure / Notification /
SubagentStart / SubagentStop / PreCompact / PostCompact /
PermissionRequest / PermissionDenied / ConfigChange / CwdChanged /
FileChanged / WorktreeCreate / WorktreeRemove 等

7.1 hooks.json 示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs -I {} uv run ruff format --quiet {}" }
        ]
      },
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs -I {} uv run mypy --no-incremental {}" }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.command' | grep -q 'rm -rf' && echo 'BLOCKED: dangerous rm' >&2 && exit 2 || exit 0" }
        ]
      }
    ]
  }
}

7.2 退出码语义

• exit 0：成功
• exit 2：阻塞操作并把 stderr 反馈给 Claude
• 其他非零：非阻塞警告

7.3 handler 类型

7.4 不会写 JSON？用 hookify

hookify 插件（/plugin install hookify@claude-plugins-official）让你用 Markdown 写 hook：

1
2
3
4
5
6
7
8

---
name: warn-rm
enabled: true
event: bash
pattern: rm\s+-rf
action: warn
---
⚠️ Dangerous rm detected

7.5 实战常见 hook 模板

八、Subagents（子代理）

Subagent 是 Claude Code 的”独立 context worker”——把脏活放进隔离 context，只把摘要返回主会话。

8.1 Subagent 价值

• 节省主 context token：大文件读取、批量搜索放进子代理
• 隔离权限：给子代理只读工具 / 限定工具集
• 省成本：用 haiku 跑简单任务
• 并行：多个子代理同时跑不同子任务
• 嵌套：最多 5 层

8.2 定义 Subagent

.claude/agents/code-reviewer.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

---
name: code-reviewer
description: Expert code reviewer. Reviews PR changes for quality and security.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer with 10+ years of experience.

When invoked:
1. Run `git diff main...HEAD` to see all changes
2. For each changed file, identify:
   - Logic bugs and edge cases
   - Security issues (SQL injection, XSS, auth bypass)
   - Performance issues (N+1, missing index, blocking I/O)
   - Style inconsistencies
3. Output a structured report with severity (Critical/Major/Minor)
4. Be concise. Skip nitpicks.

8.3 使用

Claude 会自动根据 description 决定何时调用，也可以显式要求：

1

用 code-reviewer 子代理审一下当前 PR

8.4 关键字段

8.5 常见 subagent 类型

• Explore：代码探索（只读，haiku 即可）
• Plan：架构设计（plan mode，强推理）
• code-reviewer：PR review
• test-writer：写测试
• refactor：代码重构
• doc-writer：写文档
• db-explorer：只读查数据库

九、Plugins（插件）

9.1 插件市场

1
2
3

/plugin marketplace add anthropics/claude-plugins-official
/plugin marketplace add anthropics/claude-plugins-community
/plugin install <name>@claude-plugins-official

或交互式：/plugin > Discover

也支持本地/远程加载：

1
2

claude --plugin-dir ./my-plugin
claude --plugin-url https://example.com/plugin.zip

9.2 官方推荐插件

起步推荐：先装 code-review + commit-commands + security-guidance 三个，单这 3 个就值回票价。

9.3 外部热门插件

十、MCP（Model Context Protocol）

MCP 是 Claude Code 的”工具扩展协议”——任何实现了 MCP 的服务都能成为 Claude 的工具。

10.1 推荐必装 MCP

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# 实时拉最新库文档，避免幻觉（强烈推荐）
claude mcp add --transport http context7 https://mcp.context7.com/mcp
# 或 npx ctx7 setup 一键

# 浏览器自动化（写测试、抓数据）
claude mcp add --transport stdio playwright -- npx @playwright/mcp@latest

# Git 仓库读/搜索
claude mcp add --transport stdio git -- uvx mcp-server-git --repository /path/to/repo

# GitHub
claude mcp add --transport stdio github \
  --env GITHUB_PERSONAL_ACCESS_TOKEN=xxx \
  -- npx -y @modelcontextprotocol/server-github

# PostgreSQL
claude mcp add --transport stdio postgres \
  -- npx -y @modelcontextprotocol/server-postgres "postgresql://localhost/mydb"

# SQLite
claude mcp add --transport stdio sqlite \
  -- npx -y @modelcontextprotocol/server-sqlite /path/to/db.sqlite

# 文件系统（可限制范围）
claude mcp add --transport stdio filesystem \
  -- npx -y @modelcontextprotocol/server-filesystem /path

# Greptile（AI 代码 review）
claude mcp add --transport http greptile https://mcp.greptile.com/mcp \
  --header "Authorization: Bearer $GREPTILE_API_KEY"

10.2 MCP scope

1

claude mcp add --scope project --transport stdio my-mcp -- my-command

10.3 MCP 配置文件

<repo>/.mcp.json（项目级，提交 git）：

1
2
3
4
5
6
7
8
9
10
11
12
13

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GITHUB_TOKEN}" }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    }
  }
}

配合 enableAllProjectMcpServers: true 启动时自动批准，不用每次点 yes。

10.4 完整管理命令

1
2
3
4
5
6

claude mcp list                  # 列出已配 MCP
claude mcp get <name>            # 看配置
claude mcp add ...               # 新增
claude mcp remove <name>         # 删除
claude mcp reset-project-choices # 重置项目级批准选择
claude mcp serve                 # 启动一个 MCP server（被其他 client 调用）

十一、性能调优

11.1 减 token 消耗

11.2 提速

• 模型选择：haiku 跑简单任务（找文件、解释单函数），sonnet 日常，opus 复杂推理

• fast mode：/fast 切换（在订阅允许时）

• 并行 background agents：

  1 2 3 4 5

  claude --bg "investigate the flaky test" # 返回 session ID，立刻返回 claude agents # 看所有后台 session claude logs <id> # 看输出 claude attach <id> # attach 到本终端 claude stop <id> # 停止

• Advisory 模式（v2.1.98+）：claude --advisor haiku，server-side advisor 用便宜模型给建议

• agent 编排：在 subagent 用 haiku，主对话用 sonnet/opus

11.3 Prompt cache

Anthropic API 自动对 prompt 前缀做 cache（5 分钟 TTL）。要最大化命中率：

• CLAUDE.md / system prompt 稳定不变（别每次拼不同内容）
• 把 cwd、env、git flag 等 per-machine 段挪到第一条 user message（用 exclude-dynamic-system-prompt-sections）
• 长会话用 1M context 模型，省去频繁 compact

11.4 长会话管理

• 主动 /compact
• Auto memory 把关键洞察存盘，跨会话保留
• 用 subagent / context: fork skill 把大量输出隔离
• cleanupPeriodDays: 30 自动 trim 30 天前的 session 文件

11.5 CI 友好参数

1
2
3
4
5
6
7
8

claude -p "query"                          # 非交互模式
claude -p --max-turns 10 "fix this"         # 限制轮数
claude -p --max-budget-usd 5.00 "investigate"  # 限制预算
claude --bare -p "query"                   # 启动快 2-3 倍
claude -p --output-format json "query"     # 结构化输出
claude -p --output-format stream-json "query"  # 流式 JSON
claude -p --model haiku "query"            # 便宜模型
claude -p --permission-mode dontAsk "query" # 无人值守

十二、CI/CD 集成

12.1 GitHub Action

仓库：https://github.com/anthropics/claude-code-action（8.2k ⭐，被 17.8k 仓库用）

一键安装

在 Claude Code 内：

1

/install-github-app

手动安装

.github/workflows/claude.yml：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          # claude_args: |
          #   --model claude-sonnet-4-6
          #   --max-turns 30

支持 Bedrock / Vertex AI / Foundry / Workload Identity Federation。
内置 8 种 solutions：自动 PR review、路径触发、外部贡献者审查、定制清单、定时维护、Issue triage、文档同步、安全审查。

PR 自动 review

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

name: Claude PR Review
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          direct_prompt: |
            请 review 这个 PR。重点关注：
            1. SQL 注入 / XSS / 认证绕过
            2. 性能问题（N+1、缺失索引、阻塞 I/O）
            3. 测试覆盖率
            4. 是否符合 CLAUDE.md 的强约束
            请用中文输出，按 Critical / Major / Minor 分级。

12.2 Agent SDK（编程式调用）

把 Claude Code 当库用，Python 或 TypeScript：

1
2

npm install @anthropic-ai/claude-agent-sdk
pip install claude-agent-sdk

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Find and fix the bug in auth.py",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Bash"],
            permission_mode="acceptEdits",
            cwd="/path/to/repo",
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

1
2
3
4
5
6
7
8
9
10
11
12

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Find and fix the bug in auth.ts",
  options: {
    allowedTools: ["Read", "Edit", "Bash"],
    permissionMode: "acceptEdits",
    cwd: "/path/to/repo",
  },
})) {
  if ("result" in message) console.log(message.result);
}

可用的工具：Read / Write / Edit / Bash / Monitor / Glob / Grep / WebSearch / WebFetch / AskUserQuestion。
支持 hooks、subagents、MCP、permissions、sessions。

12.3 其他 CI 平台

• GitLab CI/CD：https://code.claude.com/docs/en/gitlab-ci-cd
• Claude Code on the Web：https://claude.ai/code（浏览器跑，无需本地环境）
• claude remote：创建 web session
• Headless：claude -p "query" + --output-format json/stream-json 配合 shell pipeline

十三、IDE 集成

十四、监控与分析

十五、团队与企业

15.1 Managed Settings

Managed settings 是企业下发、用户和项目 settings 都覆盖不了的最高优先级配置。
适合公司统一管控升级通道、强制最低版本、禁止特定工具、注入组织 CLAUDE.md 等。

分发路径：

drop-in 目录：

managed-settings.d/*.json 按文件名字母序合并在 managed-settings.json 之上。
可用数字前缀控制顺序（如 10-telemetry.json、20-security.json）。

15.2 关键 managed 设置

1
2
3
4
5
6
7
8
9
10
11
12
13

{
  "autoUpdatesChannel": "stable",
  "requiredMinimumVersion": "2.1.100",
  "requiredMaximumVersion": "2.1.195",
  "forceRemoteSettingsRefresh": true,
  "env": {
    "DISABLE_UPDATES": "1"
  },
  "permissions": {
    "deny": ["Bash(curl *)", "Read(./secrets/**)"]
  },
  "claudeMd": "## 组织规范\n所有 PR 必须经过双人 review..."
}

⚠️ requiredMin/Max 写错默认失败开放（strip 而不 enforce），
避免一次错误推送让全员启不来。官方建议在测试机上跑 claude doctor 验证后再批量下发。

15.3 企业内自建 npm registry

官方 troubleshoot-install 文档里的明确警告：

Corporate npm mirror is missing the platform packages. Ensure your registry mirrors all eight @anthropic-ai/claude-code-* platform packages in addition to the meta package.

@anthropic-ai/claude-code 这个 meta 包依赖 8 个 per-platform optional dependencies 拉取 native binary：

• @anthropic-ai/claude-code-darwin-arm64
• @anthropic-ai/claude-code-darwin-x64
• @anthropic-ai/claude-code-linux-x64
• @anthropic-ai/claude-code-linux-arm64
• @anthropic-ai/claude-code-linux-x64-musl
• @anthropic-ai/claude-code-linux-arm64-musl
• @anthropic-ai/claude-code-win32-x64
• @anthropic-ai/claude-code-win32-arm64

企业 npm 镜像必须把这 8 个包 + meta 包都同步上。
且 .npmrc 不能设 optional=false，npm 命令不能带 --omit=optional / --no-optional / --ignore-optional。

15.4 升级策略

十六、安全与权限

16.1 内置安全机制

• 工具白/黑名单（permissions.allow / deny）
• 预执行钩子拦截（PreToolUse hook 阻断危险命令）
• Prompt injection 防护（disableSkillShellExecution: true 禁 skill 里的 ! 内联 shell）
• 代码签名验证（native binary 经 GPG 签名，macOS Apple 公证，Windows Authenticode 签名）

16.2 推荐的权限设置

~/.claude/settings.json：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(npm test *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)"
    ],
    "deny": [
      "Bash(curl *)",
      "Bash(wget *)",
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(~/.ssh/**)",
      "Read(~/.aws/**)"
    ]
  }
}

16.3 数据流向

Claude Code 不会主动上传你的代码库。但默认行为是：

• 用户输入 + 工具调用结果 → Anthropic API
• 会话 transcript 存到本地（默认 ~/.claude/，30 天后自动 trim，可配 cleanupPeriodDays）

如果合规要求”数据不出本地”：

• 用 Bedrock / Vertex 走自己的云
• 用 --bare 模式减少自动发现的本地文件
• 设置 cleanupPeriodDays: 1 减少本地留存
• managed settings 加 permissions.deny 限制读取范围

十七、常见问题（FAQ）

Q1：Claude Code 会无限重试吗？

不会。默认最多重试 10 次（v2.1.186 起硬上限 15 次），用指数退避，spinner 显示 Retrying in Ns · attempt x/y。
重试范围只覆盖 transient 错误（5xx、529、临时 429、timeout、网络断开）。
4xx（401/403/404 等）不会重试，立即报错。

可用变量调小上限：CLAUDE_CODE_MAX_RETRIES=2，让 CI 配错 base URL 时更快失败。

Q2：怎么升级到最新版？

1
2
3
4
5

claude update                                       # 通用（推荐）
npm install -g @anthropic-ai/claude-code@latest    # npm
curl -fsSL https://claude.ai/install.sh | bash     # 原生
brew upgrade claude-code                            # Homebrew
winget upgrade Anthropic.ClaudeCode                # WinGet

Q3：怎么关闭自动更新？

写到 ~/.claude/settings.json 的 env：

1
2
3
4
5

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

彻底锁死（连 claude update 都不能用）：

1
2
3
4
5

{
  "env": {
    "DISABLE_UPDATES": "1"
  }
}

Q4：怎么用本地代码库而不联网？

用 Bedrock / Vertex 走自己的云端点：

1
2
3

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-west-2
claude

注意这要求 Bedrock 那边已经开通 Claude 模型访问权限。

Q5：怎么给团队统一发配置？

用 managed settings（详见第十五章）。它下发的策略用户和项目 settings 都覆盖不了。
企业管理员通过 claude.ai admin 控制台统一下发。

Q6：CLAUDE.md 写多长合适？

越短越好。官方建议不超过 200 行。

把始终需要的事实放 CLAUDE.md（命令、约束、约定）；
把长但偶尔用的流程放 skill（按需加载）；
把通用知识留给 Claude 自己知道（不写）。

Q7：怎么减少 token 消耗？

按优先级：

1. 精简 CLAUDE.md
2. claudeMdExcludes 排除 vendored 库
3. 用 subagent 隔离大文件读取
4. 用 context: fork skill
5. /compact 主动触发
6. 选合适的模型（简单任务用 haiku）
7. permissions.allow 加白名单（避免弹窗打断）
8. --bare 启动（CI 场景）

Q8：怎么从 Copilot / Cursor 迁过来？

Claude Code 与 IDE 不冲突。推荐渐进式迁移：

1. 在终端跑 Claude Code 做工程任务（重构、写测试、git 操作）
2. IDE 继续用 Copilot 做行内补全
3. 逐步把”复杂任务”都让 Claude Code 在终端做
4. 装 VS Code / JetBrains 扩展，IDE 里也能用 Claude Code

Q9：怎么调试 Claude 做了什么？

• /statusline 看当前 session 状态
• claude doctor 看配置 / hooks 是否有误
• --verbose 启动看详细日志
• ~/.claude/ 看本地 transcript（每个 session 一个 JSONL 文件）
• GitHub issue 时附上 claude doctor 输出 + transcript 路径

Q10：怎么接入私有 LLM / 第三方代理？

1
2
3

export ANTHROPIC_BASE_URL="https://your-proxy.example.com"
export ANTHROPIC_AUTH_TOKEN="sk-..."
claude

要求代理实现 Anthropic Messages API 兼容端点。

Q11：Windows 上能用吗？

可以，原生安装器（irm https://claude.ai/install.ps1 | iex）和 npm 都支持。
注意 WSL 比原生 Windows 体验更好（路径处理、shell 兼容性）。

Q12：能离线用吗？

不能。Claude Code 需要联网调用 Anthropic API（或自建代理）。
但会话 transcript 离线可看（JSONL 格式，存 ~/.claude/）。

Q13：怎么回滚到旧版本？

1
2
3
4
5
6
7
8

# 原生
curl -fsSL https://claude.ai/install.sh | bash -s 2.1.193

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

# 或用 claude install
claude install 2.1.193

Q14：怎么报告 bug？

• 在 Claude Code 内 /feedback
• GitHub issues：https://github.com/anthropics/claude-code/issues
• 附上：claude doctor 输出、复现步骤、transcript 路径

十八、参考资源

官方文档

• 总览：https://code.claude.com/docs/en/overview
• 安装：https://code.claude.com/docs/en/setup
• 设置：https://code.claude.com/docs/en/settings
• 错误处理：https://code.claude.com/docs/en/errors
• 环境变量：https://code.claude.com/docs/en/env-vars
• CLI 参考：https://code.claude.com/docs/en/cli-reference
• Hooks：https://code.claude.com/docs/en/hooks
• MCP：https://code.claude.com/docs/en/mcp
• Sub-agents：https://code.claude.com/docs/en/sub-agents
• Skills：https://code.claude.com/docs/en/skills
• Plugins：https://code.claude.com/docs/en/plugins
• Permission modes：https://code.claude.com/docs/en/permission-modes
• Memory：https://code.claude.com/docs/en/memory
• Model config：https://code.claude.com/docs/en/model-config
• 故障排查：https://code.claude.com/docs/en/troubleshooting
• 故障排查（安装）：https://code.claude.com/docs/en/troubleshoot-install
• Changelog：https://code.claude.com/docs/en/changelog
• GitHub Actions：https://code.claude.com/docs/en/github-actions
• Agent SDK：https://code.claude.com/docs/en/agent-sdk/overview
• VS Code：https://code.claude.com/docs/en/vs-code
• JetBrains：https://code.claude.com/docs/en/jetbrains
• GitLab CI/CD：https://code.claude.com/docs/en/gitlab-ci-cd
• Fast mode：https://code.claude.com/docs/en/fast-mode
• Managed settings：https://code.claude.com/docs/en/permissions#managed-settings

官方仓库

• Claude Code：https://github.com/anthropics/claude-code
• 官方插件目录：https://github.com/anthropics/claude-plugins-official
• 社区插件：https://github.com/anthropics/claude-plugins-community
• GitHub Action：https://github.com/anthropics/claude-code-action
• Agent SDK 示例：https://github.com/anthropics/claude-agent-sdk-demos

MCP 生态

• MCP 参考实现：https://github.com/modelcontextprotocol/servers
• Claude 工具目录：https://claude.ai/directory
• context7（库文档）：https://github.com/upstash/context7
• Playwright MCP：https://github.com/microsoft/playwright-mcp

十九、总结

Claude Code 是当前最接近”AI 软件工程师”形态的终端 Agent。它强在：

• 原生 Agent 体验：不只补全代码，而是真正读懂项目、改文件、跑命令
• 极强的扩展性：hooks、subagents、skills、plugins、MCP 五维可扩展
• 完整的工程闭环：从开发到 PR review 到 CI 都有官方支持
• 企业级管控：managed settings 让大公司可以放心推

适用人群

• ✅ 个人开发者：日常编码、自动化工程任务、学习新代码库
• ✅ 小团队：统一代码规范、自动 PR review、提速
• ✅ 大企业：managed settings 统一管控、合规、可观测

下一步

1. 5 分钟起步：原生安装 → /login → 在一个小项目里跑 claude "解释这个项目"
2. 一周深入：写一份精炼的 CLAUDE.md，装 code-review + commit-commands + context7 三个插件
3. 一月精通：用 subagents 隔离脏活、用 skills 沉淀团队流程、用 hooks 自动 lint/test、用 GitHub Action 自动化 PR review
4. 长期演进：用 Agent SDK 把 Claude Code 嵌入自己的产品；用 managed settings 团队统一管控

希望这篇指南能帮你用好 Claude Code，把更多时间留给真正有创造性的工作。🚀

二十、附录：用 OpenClaw + 微信 把 Claude Code 变成微信里的远程 Agent

OpenClaw（Tencent 开源的本地 AI Agent Gateway）原生支持 20+ 消息渠道（含微信）。
配合 Claude Code CLI 作 agent runtime，可把任意一台机器上的 Claude Code 变成”微信里的远程打工人”——
手机发消息，Claude Code 处理，微信秒回。无需公众号、无需企业认证。

20.1 架构

1
2
3

[手机微信] → [openclaw-weixin 插件] → [OpenClaw Gateway (root)] → [Claude Code CLI] → [Anthropic API]
                                                                          ↑
                                                                    user namespace (uid=nobody)

关键事实：Claude Code CLI 在主机以 nobody 身份运行（不是 root），但仍在 root 的文件系统里——不需要额外用户、不需要容器、不需要 sudo 切权。

20.2 一键安装流程

按顺序执行，整套约 10 分钟：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

# ========== 1. 装 OpenClaw + 微信插件 ==========
npm install -g openclaw
npx -y @tencent-weixin/openclaw-weixin-cli install
openclaw channels login --channel openclaw-weixin    # 终端扫码登录微信

# ========== 2. 启动 OpenClaw gateway ==========
openclaw gateway restart
openclaw channels status                              # 应显示 running

# ========== 3. 配 Claude Code 作 agent runtime ==========
# 编辑 ~/.openclaw/openclaw.json，在 agents.defaults.models 里加：
#   "anthropic/claude-sonnet-4-6": {
#     "alias": "Sonnet",
#     "agentRuntime": { "id": "claude-cli" }
#   }
# 并把 agents.defaults.model.primary 改成 "anthropic/claude-sonnet-4-6"
openclaw gateway restart

# ========== 4. 解决 root 跑 Claude CLI 被拒（核心 hack）==========
# 4a. 让 nobody 能读 .claude 登录态
chmod -R o+rX /root/.claude

# 4b. 把原 Claude 二进制改名
mv /root/.local/bin/claude /root/.local/bin/claude.real

# 4c. 在原位置放 wrapper（unshare 让 Claude 在 namespace 内变 nobody）
cat > /root/.local/bin/claude <<'EOF'
#!/bin/bash
exec unshare -U /root/.local/bin/claude.real "$@"
EOF
chmod +x /root/.local/bin/claude

# ========== 5. 验证 ==========
claude -p "say hi"                                    # 应返回正常回复
openclaw agent --model anthropic/claude-sonnet-4-6 --to openclaw-weixin --message "ping"
# 手机微信发消息，秒回 Claude 风格内容

20.3 三个最常踩的坑

坑 1：--dangerously-skip-permissions cannot be used with root/sudo privileges

Claude Code 出厂安全策略，禁止 root 用 --dangerously-skip-permissions。

错误做法：创建 openclaw-user、装 Docker、sudo 切用户——全都引入了额外复杂度。
正确做法：unshare -U 创建 user namespace，进程在 namespace 内看到自己是 nobody (uid=65534)，实际仍是 root 跑。

验证命令：

1

unshare -U id    # 应返回 uid=65534(nobody)

坑 2：wrapper 放错位置

OpenClaw gateway 进程的 PATH 是：

1

/root/.nvm/versions/node/v24.16.0/bin:/root/.nvm/current/bin:/root/.local/bin:...

/root/.local/bin 在 /usr/local/bin 前面。

→ wrapper 必须放 /root/.local/bin/claude，不能放 /usr/local/bin/claude。
放错位置，OpenClaw 调的是真 binary（root 检测生效 → 报错）。

验证 wrapper 生效：

1
2

which claude        # 应是 /root/.local/bin/claude
head -1 $(which claude)    # 应是 #!/bin/bash

坑 3：openclaw-weixin 插件所有权错

/root/.openclaw/npm/.../openclaw-weixin 必须归 root 所有。uid=1000 会被拒：

1
2

plugins.entries.openclaw-weixin: blocked plugin candidate: suspicious ownership
(uid=1000, expected uid=0 or root)

修复：

1
2

chown -R root:root /root/.openclaw
openclaw gateway restart

20.4 故障排查速查表

20.5 升级注意事项

Claude Code 自动升级时，/root/.local/bin/claude.real 指向的版本路径不会自动变。

升级后跑：

1
2

readlink /root/.local/bin/claude.real           # 看指向哪个版本
ls /root/.local/share/claude/versions/          # 看实际装的版本

如果不一致：

1

ln -sf /root/.local/share/claude/versions/$(ls /root/.local/share/claude/versions/ | sort -V | tail -1) /root/.local/bin/claude.real

20.6 进阶：用 minimax 兼容 API 省钱

如果不需要 Sonnet/Opus 的强推理，OpenClaw 可配国内 Anthropic 兼容 API（如 MiniMax、DeepSeek 等）走 anthropic-messages 协议：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

// ~/.openclaw/openclaw.json
{
  models: {
    mode: "merge",
    providers: {
      minimax: {
        baseUrl: "https://api.minimaxi.com/anthropic",
        apiKey: "ENV:MINIMAX_API_KEY",
        models: [{ id: "MiniMax-M3", name: "MiniMax M3" }],
        api: "anthropic-messages",
        authHeader: true
      }
    }
  },
  agents: {
    defaults: {
      model: { primary: "minimax/MiniMax-M3" },     // 日常用便宜的
      models: {
        "anthropic/claude-sonnet-4-6": {             // 复杂任务切 Sonnet
          agentRuntime: { id: "claude-cli" }
        }
      }
    }
  }
}

运行时 openclaw agent --model anthropic/claude-sonnet-4-6 --message "..." 临时切到 Claude。

20.7 反模式（不要做的事）

• ❌ 创建 openclaw-user 用 sudo 跑——引入手动 sync .claude 登录态的麻烦
• ❌ Docker 容器化 Claude CLI——破坏”单用户单套”的目标
• ❌ 用 chmod o+x /root 然后让 wrapper 跑其他用户——权限边界混乱
• ❌ 复制 /root/.claude 给其他用户——OAuth token 散落、升级易断
• ❌ 改 Claude CLI 源码去掉 root 检查——下次升级自动失效

20.8 一句话总结

1

unshare -U + 位置对的 wrapper = root 跑 OpenClaw + Claude Code CLI 唯一干净的姿势