Claude Code 终端代理使用与进阶配置笔记

Claude Code 是一款强大的命令行 AI 代理工具 (CLI AI Agent)。它直接运行在终端，能理解整个代码库（Codebase），并自主执行读写文件、运行测试、Git 提交等复杂操作。

m0_48927448

422人浏览 · 2026-04-22 22:10:23

m0_48927448 · 2026-04-22 22:10:23 发布

一、简介

Claude Code 是一款强大的命令行 AI 代理工具 (CLI AI Agent) 。它直接运行在终端，能理解整个代码库（Codebase），并自主执行读写文件、运行测试、Git 提交等复杂操作。

二、安装与启动

全局安装：确保已安装 Node.js 后，在 PowerShell 执行：
```
npm install -g @anthropic-ai/claude-code
```
(如果出现 npm 版本升级提示，直接忽略即可。)
启动与验证：在终端输入 claude 启动。首次运行会提示选择终端颜色主题（Dark/Light mode）并要求进行身份验证。

三、环境变量配置详解（以第三方模型 DeepSeek 为例）

如果你想使用兼容 Anthropic 格式的第三方模型，需要通过环境变量进行“协议转换” 。以下是带有详细注释的 PowerShell 临时配置指令：

# 1. 替换基础地址与 API Key
# [说明] 告诉 Claude Code 拦截原本发往官方美国服务器的请求，将其重定向到第三方（如 DeepSeek）的 API 接口。
$env:ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"

# [说明] 这是你的“访问通行证”。将这里替换为你从第三方平台申请到的实际 API Key。程序读取到它后就不会强制要求你登录官方账号了。
$env:ANTHROPIC_AUTH_TOKEN="你的_第三方_API_KEY"

# 2. 强制指定模型名称
# [说明] Claude Code 默认寻找名为 'claude-3-5-sonnet' 的模型。此行强制它在发送请求时，声明自己需要调用名为 'deepseek-chat' 的模型大脑。
$env:ANTHROPIC_MODEL="deepseek-chat"

# [说明] Claude Code 在处理一些后台轻量级任务时会默认使用较小的 'haiku' 模型。配置此项可防止它在特定任务中偷偷切换回官方模型而导致报错。
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-chat"

# 3. 延长超时时间并禁用非必要官方遥测（防止卡顿或报错）
# [说明] 将等待 API 响应的超时时间延长到 600,000 毫秒（即 10 分钟）。当遇到需要读取大量文件的复杂代码任务时，AI 思考较长，此举能防止终端意外切断连接。
$env:API_TIMEOUT_MS="600000"

# [说明] 设置为 1 表示关闭向 Anthropic 官方发送非必要的数据诊断和遥测流量。既然已经换了第三方接口，关闭它可以减少后台网络请求，让连接更纯净。
$env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC="1"

永久生效提示：若希望一劳永逸，可使用 [Environment]::SetEnvironmentVariable("变量名", "变量值", "User") 命令将上述变量写入系统环境变量中，执行后需重启终端生效。

四、项目级进阶配置：`CLAUDE.md` 与 `.claudeignore`

为了让 Claude Code 更聪明地适应你的具体项目，你可以在项目的根目录下创建这两个关键文件。

1. 项目指南针：`CLAUDE.md`

在项目的根目录下创建一个名为 CLAUDE.md 的文件。 Claude Code 每次启动时都会自动读取这个文件，它就像是你给 AI 提前写好的“项目开发规范和备忘录”。

CLAUDE.md 配置示例：

# 项目构建与测试命令
- 编译项目：`mvn clean compile`
- 运行测试：`mvn test`
- 启动前端开发服务器：`npm run dev`

# 代码规范与架构要求
- 本项目是基于 Spring Boot 的后端服务，所有对外 API 必须遵循 RESTful 规范。
- 所有的 Controller 层必须加上 `@RestController` 和 `@RequestMapping` 注解。
- 统一使用 `Result<T>` 泛型类包装接口返回值。
- 提交 Git 时，必须遵循 Conventional Commits 规范（如 `feat: xxx`, `fix: xxx`）。

# 常用文件路径
- 数据库 MyBatis Mapper 存放于：`src/main/resources/mapper/`

2. AI 视线屏蔽：`.claudeignore`

有些敏感文件（如数据库密码）或极大的编译产物文件夹，绝对不能让 AI 去读取，否则不仅浪费 Token，还可能引发安全问题。它会默认尊重你原有的 .gitignore ，但你可以专门为 AI 创建一个 .claudeignore 文件，语法完全相同。

.claudeignore 配置示例：

# 1. 忽略本地敏感环境变量配置文件（防止泄露数据库密码或 API Key）
.env
.env.local
application-prod.yml

# 2. 忽略巨大的编译产物和依赖文件夹（防止 AI 扫描卡死或消耗海量 Token）
node_modules/
target/
dist/
build/
.idea/

# 3. 忽略日志文件和临时文件
*.log
logs/
npm-debug.log