Claude CodeAI CodingCodeGateway
Claude Code 完整配置指南：从环境准备到 Skills 实战
2026年5月7日
加载中…
一句话：Claude Code 配置易上手、难精通。CLI 一行命令就能跑，但要把 Skills、Hooks、子代理、多项目工作流串起来，需要对每个配置位的作用心里有数。本文从环境准备讲到团队协作，是一篇给"装好之后怎么用得专业"的工程师准备的完整手册。
Claude Code 是 Anthropic 推出的命令行 AI 编程工具，区别于 Cursor / Continue 这种 IDE 内嵌的助手，它把"AI 编辑器"的逻辑反过来：编辑器是终端 + 你的工作目录，AI 在终端里以代理形态运作，能自主读文件、写文件、跑命令、起子代理。这种形态对长链路任务（多文件重构、跨服务迁移、整套测试与文档生成）友好得多。
成熟开发者用 Claude Code 时关心的不是"它会不会写代码"，而是：
下面按这条路径展开。
# 终端版本
echo $SHELL
# Node.js 版本（要求 18+）
node --version
# npm 版本
npm --version
# Git 版本（Claude Code 大量依赖 git）
git --versionNode 版本不到 18 升级到 LTS（推荐 20.x）。Windows 用户强烈建议 WSL2 + Ubuntu，原生 PowerShell 在长任务、stdin 管道场景稳定性差一些。
npm install -g @anthropic-ai/claude-code
claude --version更新机制是 npm 自管，需要时跑 npm update -g @anthropic-ai/claude-code。
接 Anthropic 直连或接 CodeGateway 都能跑。本文以 CodeGateway 为例：
sk-cg-，仅展示一次，及时存到密码管理器。截图占位：API Key 创建页。
# ~/.zshrc 或 ~/.bashrc
export ANTHROPIC_BASE_URL="https://api.codegateway.dev"
export ANTHROPIC_API_KEY="sk-cg-xxxxxxxxxxxxxxxxxxxxxx"
# 默认模型（可按项目覆盖）
export ANTHROPIC_MODEL="claude-sonnet-4-6"source ~/.zshrc 让变量生效。
Anthropic 当下三个主力模型，对 Claude Code 工作流的对应关系：
模型 | 强项 | 适用场景 | 计费倾向 |
|---|---|---|---|
| 深度推理能力较强 | 架构决策、跨服务设计、复杂调试 | 输入 / 输出高，慎用 |
| 平衡 + 编码强 | 日常主力（重构、生成、Code Review） | 性价比推荐，默认推荐 |
| 快、便宜 | 工具型 sub-agent、批量 lint、简单生成 | 输入 / 输出至少 |
按价值密度建议：把日常主力设 Sonnet，子代理（频繁调用、并行多个）切 Haiku，一次性架构决策 / 长 chain 推理切 Opus。
mkdir hello-claude && cd hello-claude
git init
echo "# Hello" > README.md
claude进入交互式会话，输入：
请把这个仓库初始化成一个 Python 项目，用 uv 管理依赖，加一个基础的 hello.py，
并写一个小 pytest 测试。正常情况下 Claude Code 会自主执行 uv init、写文件、运行测试，全程在终端 stream 输出。
Claude Code 的 Skills 是"可复用的行为规范"。每个 Skill 是一个目录，含 SKILL.md 描述触发条件、行为约束、引用的工具白名单。Skill 可以是个人级（~/.claude/skills/）也可以是项目级（.claude/skills/）。
举个例子，常用 Skill：
tdd-workflow：强制先写测试再实现python-patterns：Pythonic 习惯 + PEP 8 + 类型提示golang-testing：Go 测试模式，table-driven 风格e2e-testing：Playwright Page Object Model 写法frontend-design：前端设计系统约定（颜色、字体、动效语言）在 Claude Code 会话里：
/skill tdd-workflow或者隐式触发：当 Claude Code 识别到任务匹配某个 Skill 描述时会自动加载。
新建 .claude/skills/my-team-react/SKILL.md：
---
name: my-team-react
description: 团队 React 组件约定。每次新增 React 组件时启用：使用函数组件 + TS、props 类型显式声明、CSS 用 CSS Modules、单元测试用 Vitest + RTL。
---
# 团队 React 约定
## 组件结构
- 函数组件 + TypeScript
- Props 接口命名 `<Component>Props`
- 默认导出，不使用 `React.FC`
## 样式
- CSS Modules（`Component.module.css`），不用 styled-components
- 主色变量统一引用 `tokens.css`
## 测试
- Vitest + React Testing Library
- 每个交互态至少一个测试用例
- 单元测试覆盖率 ≥ 80%
## 文件组织
- `Component.tsx` + `Component.module.css` + `Component.test.tsx`
- 同目录下放 `index.ts` 导出之后 Claude Code 在该项目里写 React 组件就会按这套规范走。Skill 文件托到团队仓库，新人 clone 之后直接复用。
按角色配 Skills：
角色 | 推荐组合 |
|---|---|
全栈个人开发者 |
|
后端工程师 |
|
前端工程师 |
|
平台 / DevOps |
|
Claude Code 提供三类 hook：
.claude/settings.json:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"command": "ruff check --fix \"$FILE_PATH\" && ruff format \"$FILE_PATH\"",
"description": "格式化 + lint Python 文件"
}
]
}
}每次 Claude Code 写或编辑文件，hook 自动把对应文件 lint + 格式化一遍，避免最后统一收拾。
{
"hooks": {
"Stop": [
{
"command": "pnpm build",
"description": "会话结束验证 production build"
}
]
}
}适合本地开发当"最后一道闸"。
{
"hooks": {
"PreToolUse": [
{
"matcher": "Write",
"command": "node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);const c=i.tool_input?.content||'';const lines=c.split('\\n').length;if(lines>800){console.error('[Hook] BLOCKED: 超过 800 行');process.exit(2)}console.log(d)})\"",
"description": "阻止写超过 800 行的文件"
}
]
}
}现象 | 检查项 |
|---|---|
401 / 403 | API Key 拼对没？base URL 对没？环境变量是否被旧 shell 缓存？ |
422 模型不存在 | 模型 ID 是 |
429 太频繁 | 降低并发、升级阶梯倍率、或加 sub-agent 排队 |
| 项目目录权限，特别是 Linux + Docker 容器内挂载 |
Hook 不触发 |
|
Skill 不加载 |
|
跑 | 检查 stdin 是否被 redirect 了；非交互场景应使用 |
长任务 ECONNRESET | 链路侧 idle timeout，详情见Claude Code 连接超时排查 |
公司网络强制走 HTTP 代理时：
export HTTPS_PROXY=http://corp-proxy.example.com:8080
export HTTP_PROXY=http://corp-proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1如果公司代理使用自签证书，再加：
export NODE_EXTRA_CA_CERTS=/etc/ssl/corp-ca.pemClaude Code 在客户端会缓存最近的 prompt / context 索引。占用过大时清理：
rm -rf ~/.claude/cache服务侧（Anthropic 自己 / CodeGateway 透传）支持 prompt caching，长 context 重复使用时显著降低成本（具体折扣见 Anthropic 文档）。
不同项目想用不同模型 / 不同 hooks，落到 .claude/settings.json（项目级）覆盖个人级：
~/.claude/settings.json # 个人默认
project-a/.claude/settings.json # 项目 A 覆盖（更严格的 hook）
project-b/.claude/settings.json # 项目 B 覆盖（不同模型）Claude Code 启动时自动找最近的 .claude/settings.json 合并。项目级一直优先。
把 PRD（Markdown）丢到项目里，会话开头：
读 docs/PRD.md，按里程碑拆任务，每个任务给出验收条件、影响文件清单、预估工时。
输出到 docs/tasks.md。Claude Code 会读文档、列任务、写文件。这种规划阶段建议挂 Opus 模型，深度推理优势更明显。
对当前 git diff 跑一遍 review，重点关注：
1. 是否有未处理的错误
2. 是否引入了硬编码密钥
3. 是否破坏了已有测试
按 CRITICAL / HIGH / MEDIUM / LOW 输出，含改动建议代码片段。Claude Code 自动跑 git diff、读相关文件、出 review 报告。让团队节奏快很多。配合 code-reviewer Skill 时输出更结构化。
跨多个仓库改字段名是 Claude Code 擅长的典型场景之一。/agents 起 sub-agent 并行处理：
主代理负责调度与汇总。Sub-agent 推荐用 Haiku，避免过高成本。
团队建一个 team-skills 仓库放共用 Skills：
team-skills/
├── react-conventions/SKILL.md
├── pr-template/SKILL.md
├── changelog-style/SKILL.md
└── README.md每个项目通过 .claude/skills/ 软链或 git submodule 引入。
CI 容易出现"本地没 lint，PR 一片红"的情况。把 lint / format / type-check hooks 写到 .claude/settings.json 并 commit 到仓库，团队里所有人在 Claude Code 写文件时都自动跑同一套质量门，CI 失败率显著下降。
不要共享个人 Key。CodeGateway 上每人单独账号，按 90 天累计消耗算阶梯倍率，至少 1.2x。共享 Key 会导致：
CI 单独申请 Key（命名 ci-<repo>），保存在 GitHub Actions / GitLab CI 的 Secrets 里。
Q：Claude Code 和 Cursor 哪个更值？
A：两个工具的形态不同，不直接竞争。Cursor 是 IDE，强在交互式编辑、行内补全、UI 反馈。Claude Code 是终端代理，强在长链路任务、自动化、与 git / shell 工具链直接集成。日常做编辑器内编辑选 Cursor，做大块自动化任务选 Claude Code。完整对比参见Claude Code vs Cursor vs GitHub Copilot。
Q：Skills 和 Hooks 有什么区别？
A：Skills 偏"行为规范"，影响 Claude Code 怎么思考与组织代码；Hooks 偏"自动化机制"，在工具调用前后强制跑命令。两者经常组合：Skill 给规范，Hook 兜底执行。
Q：必须用 CodeGateway 吗？
A：不必须。Claude Code 原生支持 Anthropic 直连。CodeGateway 主要解决"接入复杂度 + 网络稳定性 + 计费灵活度"三个变量。具体取舍看直连 / 第三方代理 / CodeGateway 对比。
Q：Sub-agent 数量有上限吗？
A：Claude Code 客户端没硬上限，主要受网关 RPM 与并发数限制。CodeGateway 默认 RPM 比 Anthropic 直连宽松，正常用法下不会撞限。
Q：能不能在企业内网无外网环境跑？
A：不行。Claude Code 必须能访问模型 API。内网通常的方案是配置出口代理（参见上面"高级配置 → HTTP 代理"），或者部署 CodeGateway 自托管版本（联系企业版咨询）。
Q：配置文件能不能版本管理？
A：推荐。把 .claude/settings.json、.claude/skills/、.claude/hooks/ commit 到仓库，新成员 clone 之后零配置就能复用团队约定。注意 API Key 不要进仓库。
Q：怎么看自己花了多少钱？
A：CodeGateway Dashboard → Logs / Overview。Overview 顶上有 Total Tokens 卡片，Logs 支持时间范围筛选（Today / 7d / 30d / 90d / All），按模型按 Key 都能拆。详细计算公式见充值费用指南。
Q：Claude Code 会不会偷跑命令？
A：Claude Code 默认对潜在破坏性操作（rm -rf、git reset --hard、force push）会先请求用户确认。可以在 settings 里调整自动允许范围，但不要全开 --dangerously-skip-permissions，相当于把方向盘给了 AI。
把上面这些配置一次性铺开看似复杂，但实际接入路径很短：装 CLI → 配 Key 与默认模型 → 跑通一次会话。Skills 和 Hooks 是"用熟之后慢慢加"，不必一开始全配。配置文件 commit 到仓库，团队节奏自然对齐。