Claude Code 实战指南：终端 AI 编程 Agent 的安装、配置与自动化

这次我们把 AI 编程 Agent 方向里一个非常能打的终端工具完整过一遍：Claude Code。

Claude Code 是 Anthropic 官方推出的命令行编程代理。装好之后，你可以在终端里直接和它对聊，让它读项目、改代码、执行命令、跑测试、提交 Git，还能通过 MCP 把外部系统变成它的工具。和传统 IDE 插件不同，Claude Code 更接近一个独立的 Agent 运行时：模型负责推理，终端负责执行，MCP 负责连接外部服务，CLAUDE.md 负责记忆，Skill 负责沉淀和复用工作流。

先说门槛：它不在本地跑模型，不依赖 GPU 显存，核心依赖是 Node.js 环境和可用的模型服务端点。这个特性意味着普通办公笔记本也能用，部署成本比本地大模型低很多，也方便通过环境变量切换到兼容的国内模型服务端点。

本文会按一条完整链路来走：安装部署、认证与国内模型适配、交互和批量实战、记忆与权限、MCP 工具扩展、Skill 二次开发、批量自动化、资源占用与排错。适合已经熟悉 Git 和命令行的后端、前端、SRE 开发，也适合想把 AI 编程 Agent 接进团队工作流的人。文章偏实战，每个环节都给了可复制的命令和判断成功的标准。

1. Claude Code 核心能力速览

先看规格，再讲细节。

从架构上看，Claude Code 可以拆成几层：模型是内核，工具调用是手脚，MCP Server 是外部能力的插槽，CLAUDE.md 是长期记忆，Skill 是工作流说明书。理解这个分层，后面做二次开发会顺手很多。

2. 适用场景与使用边界

Claude Code 适合这几类人：

• 日常有大量增删改查、重构、补测试任务的开发。
• 想把 AI 编程接进脚本和 CI 流程，而不是只挂在 IDE 里。
• 对代码保密性有要求，需要把模型端点切换到可控网关或国内兼容服务。
• 想沉淀团队编码规范，让 Agent 每次生成代码都遵守同一套规则。

它能解决的核心问题有三个。第一是跨文件改动，一条指令可以同时修改多个模块并保持接口一致。第二是让 Agent 自己完成"改代码、跑测试、看报错、继续改"的闭环，而不是只给你一段参考代码。第三是批量机械化任务，比如给一批文件补注释、补单测、统一日志格式。

使用边界也要说清楚：

• 不适合完全无人值守的生产变更。线上发布、数据库迁移、破坏性重构必须有代码 review 和人工确认。
• 不适合需要完全离线推理的场景。Claude Code 本身不携带模型，模型能力完全取决于你接的服务端点。
• 国内模型适配不等于所有能力平替。补全、工具调用、长上下文表现取决于端点提供方，按实际测试结果为准。

合规方面有一条底线：代码和提示词可能会离开本机。敏感项目要先脱敏，企业内部数据要确认服务商的数据处理边界，接入 MCP 的外部服务要按最小权限设计。涉及版权代码、开源协议和公司保密条例时，先确认授权再让 Agent 处理。

3. Claude Code 环境准备与安装部署

3.1 环境要求清单

安装前先确认这几项：

• Node.js 18 及以上版本。
• 可用的终端环境，macOS 或 Linux 直接使用系统终端。
• Windows 环境建议先装 WSL，在 WSL 里操作比 PowerShell 兼容性更好。
• Git 不是硬依赖，但推荐安装，方便 Agent 查看 diff 和提交代码。
• 能访问模型服务端点的网络条件，以及一个可用的 API Key 或账号。

3.2 npm 方式安装

npm 是 Claude Code 最常用的安装方式，一条命令装到全局：

bash复制npm install -g @anthropic-ai/claude-code

安装完成后确认版本：

bash复制claude --version
claude --help

看到版本号和帮助信息，说明安装成功。如果提示找不到 claude 命令，通常是 npm 全局 bin 目录没有加入 PATH，检查一下 npm root -g 的实际路径。

3.3 官方原生安装器方式

不依赖 npm 的环境，可以使用官方原生安装器：

bash复制# macOS / Linux 环境，实际安装地址以官方 README 为准
curl -fsSL https://claude.ai/install.sh | bash

安装器会把可执行文件放到用户目录下，安装完成后同样执行 claude --version 验证。

3.4 Windows 注意点

在 Windows 上最容易踩的坑是路径和终端模拟器不兼容。推荐的做法是：

• 先装 WSL2 和 Windows Terminal。
• 在 WSL 里安装 Node.js。
• 在 WSL 终端里执行 npm 全局安装。

这样文件读写、命令执行、Git 操作都和 Linux 环境一致，Claude Code 的行为更可预期。

3.5 安装后第一件要做的事

先跑一个最小指令，验证整条链路是否通：

bash复制claude -p "只输出当前目录下的文件和目录结构，不要做任何修改"

如果它能正确列出目录结构，说明安装、模型端点和工具调用链路都正常。再做大任务前，务必先通过这个最小验证。

4. Claude Code 认证与国内模型适配配置

4.1 官方认证方式

Claude Code 支持两种官方认证：使用 Claude 订阅账号登录，或者使用 Anthropic 控制台创建的 API Key。

交互式登录：

bash复制claude

首次启动会引导完成登录授权。如果用 API Key，直接通过环境变量注入：

bash复制export ANTHROPIC_API_KEY="your-api-key-here"
claude

4.2 环境变量统一配置

生产环境或脚本环境，建议把配置写到 .env 文件里，统一管理：

bash复制export ANTHROPIC_API_KEY="your-api-key"
export ANTHROPIC_BASE_URL="https://your-endpoint.example.com"
export ANTHROPIC_MODEL="claude-sonnet-4-5"

注意，这里不写死任何具体服务商地址。.env 里的 BASE_URL 和 MODEL 需要根据你实际使用的模型服务商来填。

4.3 国内模型适配配置

国内模型适配的核心是让 Claude Code 指向兼容 Anthropic Messages API 的服务端点。目前不少国内云厂商和模型社区已经提供了兼容接口，Claude Code 通过环境变量切换即可。

典型配置如下：

bash复制export ANTHROPIC_BASE_URL="https://your-provider-api.example.com/anthropic"
export ANTHROPIC_API_KEY="provider-issued-key"
export ANTHROPIC_MODEL="provider-model-name"

适配时重点核对五个配置项：

最容易踩的坑有两个：第一是模型名写得像官方名，但服务商实际支持的别名不一样，导致请求直接报错；第二是兼容端点不支持 tool calling，Agent 会退化成普通对话，无法执行命令和读写文件。切换端点后，先跑一遍最小任务，确认工具调用是否正常。

4.4 模型选择与成本控制

模型选择直接影响成本和效果。重任务用强模型，轻任务用轻量模型。CLI 工具不会把模型常驻内存，成本主要来自 token 消耗。可以在 .env 里同时配置主模型和轻量模型，让 Agent 在后台小任务时自动使用更便宜的模型。

5. Claude Code 核心功能实战测试

5.1 交互模式：日常开发主战场

启动交互模式：

bash复制claude

进入会话后，直接输入中文或英文任务即可。建议从简单任务开始：

• "解释当前目录下 package.json 的依赖结构。"
• "在 src/utils.ts 里新增一个防抖函数，并补充单元测试。"
• "运行测试，如果有失败用例，定位原因并修复。"

交互模式里可以输入 /help 查看斜杠命令列表，输入 /status 查看当前会话的上下文占用，输入 /exit 退出。不同版本命令有差异，以当前版本的 /help 输出为准。

5.2 非交互模式：批量与脚本化

非交互模式是 Claude Code 做自动化的关键能力：

bash复制claude -p "解释当前目录下的 package.json 依赖结构"

需要结构化输出时，可以指定 JSON：

bash复制claude -p "列出 src 目录下所有测试文件路径，返回 JSON" --output-format json

非交互模式适合放进脚本和 CI，也适合在批量任务里循环调用。

5.3 多文件任务示例

下面是一段实际可用的任务描述：

text复制在当前项目里新增一个订单号生成模块：
1. 在 src/order 下创建 generator.ts，包含订单号生成函数和校验函数。
2. 不修改现有对外接口。
3. 为新增模块补充单元测试。
4. 运行测试确认通过。

执行后重点观察三点：Agent 是否真的创建了文件、是否遵守了"不修改现有接口"的约束、测试是否通过。

5.4 命令执行与权限确认

Claude Code 执行 Bash 命令前，默认会请求确认。交互模式下人工逐个确认即可。非交互模式下需要用参数指定允许范围：

bash复制claude -p "运行项目测试并修复失败用例" --allowedTools "Bash,Read,Write"

--allowedTools 的准确写法以版本帮助为准，但思路是先收窄工具范围，再放开执行。不要用全局跳过权限的方式跑批量任务，除非任务完全不涉及危险操作。

5.5 判断成功标准

一次成功的编码任务应满足：

• 文件内容符合任务约束，没有多余改动。
• 测试执行后 exit code 为 0。
• 命令执行记录里没有非预期的高危操作。
• 代码可以过 review，而不是只有"看起来像"。

失败时的排查顺序：先看提示词是否太宽泛，再看模型端点的工具调用是否正常，最后看权限规则是否拦截了必要命令。

6. Claude Code 记忆与权限管理

6.1 项目记忆 CLAUDE.md

Claude Code 通过 CLAUDE.md 保存项目级长期记忆，放在项目根目录：

markdown复制# 项目记忆

- 技术栈: TypeScript + Node.js 22 + Fastify
- 测试命令: npm run test
- 约定: 所有新模块必须补充单元测试
- 禁止: 修改 public/ 下的构建产物
- API 风格: REST + JSON，错误码统一返回 { code, message }

每次会话启动，Claude Code 会自动读取这个文件。项目规范越具体，Agent 生成代码越贴合团队习惯。注意，CLAUDE.md 不是无限记忆，它更像一份"开机自动加载的说明书"，内容要精简、可执行。

6.2 全局记忆

个人级 CLAUDE.md 放在用户主目录：

text复制~/.claude/CLAUDE.md

全局文件适合放跨项目的个人偏好，比如缩进风格、命名习惯、常用工具链。项目级文件适合放只属于当前仓库的约束。两者是叠加关系，不互相覆盖。

6.3 权限管理

权限管理是 Claude Code 安全性的核心。交互模式下输入 /permissions 可以查看和调整权限规则。更工程化的方式是维护 ~/.claude/settings.json：

json复制{
  "permissions": {
    "allow": [
      "Read",
      "Bash(npm run test:*)",
      "Bash(git status:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(git push --force:*)"
    ]
  }
}

上面是示例配置，具体 schema 以当前版本文档为准。原则是白名单优先，把高频安全命令加入 allow，把破坏性命令加入 deny。不要为了省事把所有命令都放行。

6.4 安全边界

给 Agent 授权时要默认"最小可用"。开发环境可以放开测试和 Git 命令，但不建议放开数据库执行、生产环境部署命令。任何由 Agent 执行的破坏性操作，都应该走到人工确认这一步。

7. Claude Code MCP 工具扩展

7.1 MCP 是什么

MCP 全称 Model Context Protocol，是一套让模型客户端接入外部工具的统一协议。可以理解为 Agent 的"外接设备接口"：MCP Server 把某个能力包装成标准服务，Claude Code 作为宿主调用它。

MCP 和 Skill 的区别要分清：MCP 提供的是"能力"，比如读写某个外部系统、调用某个 API；Skill 提供的是"方法论"，比如一份代码评审流程、一份提交信息规范。两者互补。

7.2 添加 MCP Server

添加 MCP Server 的标准命令：

bash复制claude mcp add my-server -- npx -y @some/mcp-server
claude mcp list

不同版本对参数顺序可能有要求，拿不准时先看 claude mcp add --help。claude mcp list 用来确认接入状态。添加后需要重启会话才能生效。

7.3 项目级 MCP 配置

想把 MCP 配置共享给团队，可以在项目根目录放 .mcp.json：

json复制{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./data"]
    }
  }
}

.mcp.json 会随仓库分发，适合团队统一使用同一套外部工具。个人临时调试可以用 claude mcp add，团队协作用 .mcp.json。

7.4 测试一个 MCP 是否生效

接入后做一个端到端验证：

1. 重启 Claude Code 会话。
2. 直接给任务，比如接入了 filesystem 服务后，让它"读取 data 目录下文件列表"。
3. 观察 Agent 是否调用该 MCP 工具。
4. 查看工具调用返回结果是否正确。

判断标准很简单：Agent 能通过 MCP 完成原本做不到的任务，且返回结果真实可验证。

7.5 MCP 安全提醒

MCP Server 本质上获得了 Agent 的执行上下文。只安装可信来源的服务，优先使用 stdio 本地服务，远程 MCP 服务要确认鉴权和数据边界。外部服务类 MCP 接入前，先看它请求了哪些权限、数据会流向哪里。

8. Claude Code Skill 二次开发

8.1 Skill 是什么

Skill 是一份可复用的"技能包"，本质是结构化的工作流说明书。一个 Skill 由 SKILL.md 文件组成，可以附带脚本、模板和参考文件。社区里常见的 Skill 包括"去 AI 味"文本优化、代码评审、提交信息规范、接口文档生成等。

从实现角度看，Skill 二开的门槛并不高：你不需要写插件，只需要把一套可执行的流程写清楚，让 Agent 在触发条件满足时按流程执行。

8.2 Skill 目录约定

个人级 Skill 放在：

text复制~/.claude/skills/

项目级 Skill 放在：

text复制.claude/skills/

每个 Skill 是一个独立目录，目录名就是 Skill 名。

8.3 SKILL.md 文件结构

markdown复制---
name: simple-code-review
description: 当用户要求做代码评审、检查改动风险时使用。自动读取当前分支 diff，输出风险点和修改建议。
---

# Simple Code Review

按以下步骤执行代码评审：

1. 读取当前分支的 git diff。
2. 检查类型安全、空值处理、错误处理是否完整。
3. 检查是否有测试覆盖新增逻辑。
4. 输出 Markdown 评审报告，包含风险等级、文件路径、具体建议。

注意 description 是触发器的关键。描述里要写清楚"什么时候用"，Agent 会根据任务内容匹配最合适的 Skill。描述写得太泛，Skill 就不会被触发。

8.4 验证 Skill 生效

验证流程：

1. 保存 SKILL.md 到 ~/.claude/skills/ 或 .claude/skills/。
2. 重启 claude 会话。
3. 输入能触发该 Skill 的任务，比如"帮我对当前分支做一次代码评审"。
4. 观察输出是否严格按 SKILL.md 流程执行。

如果 Skill 没有生效，优先检查 description 与任务描述的匹配度，其次检查目录路径和文件命名。当前版本如果支持 /skills 命令，可以输入查看已加载的 Skill 列表。

8.5 Skill 二开的进阶方向

一个 Skill 可以从纯文档升级为带脚本的完整工具包，目录结构示例：

text复制~/.claude/skills/gen-api-doc/
├── SKILL.md
├── template.md
└── script/
    └── extract_routes.py

SKILL.md 里描述触发条件和使用步骤，template.md 提供输出模板，script 里的脚本负责抽取路由信息、生成文档片段。这样 Skill 就不只是提示词，而是真正可执行的工程能力。

9. 批量任务与接口自动化

9.1 批量脚本示例

把 Claude Code 的非交互模式包进脚本，就能处理批量任务。比如给多个文件批量补充 JSDoc：

bash复制#!/usr/bin/env bash
set -e

for file in src/**/*.ts; do
  echo "Processing: $file"
  claude -p "为 $file 中的函数补充 JSDoc 注释，保持原有逻辑不变，只输出改动摘要" \
    --output-format text
done

大批量任务必须加超时和日志，否则某条任务卡住会拖垮整个循环。建议每条任务独立记录执行时间、输出摘要、成功失败状态。

9.2 JSON 输出与解析

需要把结果接入系统，用 JSON 输出：

bash复制claude -p "查找所有未提交修改的文件路径，返回 JSON" --output-format json

Python 调用示例：

python复制import json
import subprocess

def run_claude(prompt, timeout=600):
    result = subprocess.run(
        ["claude", "-p", prompt, "--output-format", "json"],
        capture_output=True,
        text=True,
        timeout=timeout,
        check=False,
    )
    if result.returncode != 0:
        raise RuntimeError(f"claude failed: {result.stderr[:500]}")
    return json.loads(result.stdout)

data = run_claude("列出本项目所有测试文件路径")
print(data)

注意，返回结构以当前版本为准，解析前先打印一次原始输出确认字段名。

9.3 失败重试策略

批量任务里失败是常态，重试要带策略：

• 单条任务超时后，先重试 2 到 3 次。
• 重试前把任务拆小，缩小 Agent 单次处理的文件数量。
• 连续失败超过阈值就跳过并记录，不要无限重试。
• 任务设计成幂等的，同一输入重复执行结果一致，避免重复调用产生副作用。

9.4 接入 CI 工作流

思路是让 Claude Code 承担只读和生成类任务，比如生成 changelog、检查测试覆盖、生成接口文档草稿，把修改类任务控制在开发分支内，由人工 review 后再合并。接口化之后，Claude Code 就可以当作团队里的"AI 编码工人"纳入流程管理。

10. 资源占用与性能观察

10.1 不依赖 GPU 显存

Claude Code 不本地推理，因此没有显存占用问题。普通办公笔记本和云服务器都能跑，硬件门槛比本地大模型低很多。资源消耗集中在 Node 进程、网络请求和 token 成本上，注意内存和磁盘占用即可。

10.2 观察方法

可以通过系统命令观察进程状态：

bash复制ps aux | grep claude

终端会话里的状态面板会显示当前会话的上下文占用。长任务建议用 timeout 限制执行时长，避免任务卡死。

10.3 提速与降本建议

• 大任务拆小任务，降低单轮上下文长度。
• 简单任务指定轻量模型，复杂任务再用强模型。
• CLAUDE.md 写得精简，减少重复加载无效上下文。
• 批量任务控制轮次上限，防止 Agent 在无关细节里越陷越深。
• 高峰期排队时，错开执行时间，比盲目加重试更有效。

11. Claude Code 常见问题与排查方法

国内模型适配场景里有一个高频坑：模型名使用了官方模型别名，但服务商不支持。排查时先向服务商确认"该端点支持的模型别名列表"，再逐个填入 ANTHROPIC_MODEL 验证。另一个高频坑是兼容端点不支持 tool calling，表现是 Agent 不会真正读写文件、不会执行命令，只会输出文字建议。遇到这种情况，换支持工具调用的端点，不要指望在配置层面绕过。

12. 最佳实践、合规提醒与下一步

12.1 工程化建议

• 第一次先跑小任务，不要上来就做全仓库重构。
• 把最小可用配置保存下来，比如写一个 setup.sh，一键完成环境变量和插件配置。
• 模型配置、输入素材、输出结果、日志分目录管理，批量任务尤其重要。
• 每次变更保留 diff 记录，方便回滚和 review。
• 使用 .env 管理密钥，绝不要提交到公开仓库。

12.2 合规与安全边界

• 代码和提示词可能发送到模型服务端，敏感项目先脱敏。
• 企业内部数据要确认服务商的合规边界和处理协议。
• 不要在生产密钥、数据库连接串、内部 token 出现在提示词场景下运行 Agent。
• MCP 外部服务按最小权限接入，先确认数据流向。
• 使用开源组件和模型服务，遵守对应的开源协议和服务条款，商用前逐项确认。

12.3 建议先跑通的三件事

如果只选三件事，按这个顺序来：

1. 安装并配置认证，跑通 claude -p "输出当前项目结构"，确认整条链路可用。
2. 建立项目级 CLAUDE.md 和一个自定义 Skill，让 Agent 按你的规范生成代码。
3. 接入一个 MCP 写一个批量脚本，把重复的机械化任务交给 Agent 执行。

最容易踩的坑是"配置完成后没有做最小验证就直接跑大任务"：端点不兼容、模型名错误、工具调用不可用，这些问题都会在大任务里被放大。反过来，把最小验证、规范记忆、批量脚本这三件事跑顺，Claude Code 就不再是一个聊天工具，而是真正可复用、可纳入团队流程的 AI 编程工作流。接下来建议往两个方向扩展：一是把团队评审规范沉淀成 Skill 库，二是把批量任务接入 CI，让 Agent 在受控范围内承担更多自动化工作。