Claude Code：Anthropic 官方终端 AI 编码代理

为什么需要 Claude Code：聊天窗无法触及仓库，终端代理接管研发循环

传统 AI 辅助开发依赖浏览器聊天窗口，模型看不到完整项目结构，无法执行测试验证自己的改动。工程师要手工复制报错信息、粘贴要修改的文件片段，再把模型回复的代码合并进项目。涉及跨文件重构、跑完测试看结果再迭代的场景时，这套「复制—粘贴—手工应用」的循环严重拖慢节奏，上下文也随对话增长而失真。

Claude Code 以终端为驻地，直接获得当前目录的文件系统与命令执行能力。它自己读文件、做定点编辑、跑 bash、执行测试，看到失败再迭代修复，整个过程不需要人工搬运信息。它遵循权限模型：默认每个有副作用的操作（改文件、跑命令）都先征求你同意；会话上下文可通过 -c/--resume 跨多次启动继续，CLAUDE.md 文件则沉淀项目特定的规范与约定，让新会话自动继承。

与 LangChain、LlamaIndex 这类「构建 Agent 的框架」不同，Claude Code 是一个开箱即用的 Agent 产品：你不需要写编排代码，只需要下指令。它的定位介于「个人结对编程助手」与「可在 CI 中运行的自动化代理」之间，这也是它与编排框架最本质的气质差异——前者消费模型能力，后者让你生产模型应用。

安装与环境配置：3 步就绪

前置条件：npm 方式需要 Node.js 18+；支持 macOS 10.15+、Ubuntu 20.04+/Debian 10+；Windows 在 WSL 2 中运行。

步骤一·安装：使用 npm 全局安装官方包，或运行官方原生安装脚本（脚本会自动处理 Node.js 运行时，适合版本较旧的机器）。

步骤二·认证：个人开发环境直接运行 claude，首次启动会输出一个浏览器授权链接，用 Claude 账号（Pro/Max/Team）完成 OAuth 登录；CI 或脚本环境没有浏览器交互，改用 ANTHROPIC_API_KEY 环境变量注入 API 密钥。

步骤三·验证：执行 claude --version 确认版本，再运行一条非交互提示词验证认证链路是否打通。

# 前置检查node -v   # 需要 18.0 及以上 # 方式一：npm 全局安装（推荐）npm install -g @anthropic-ai/claude-code # 方式二：官方原生安装脚本（自动管理运行时）curl -fsSL https://claude.ai/install.sh | bash # 登录方式 A：交互式 OAuth（个人开发）claude   # 首次运行会输出浏览器授权链接 # 登录方式 B：环境变量注入 API 密钥（CI/脚本）export ANTHROPIC_API_KEY="sk-ant-api03-..."claude -p "你好，用一句话说明你的能力"   # 非交互验证

快速上手：5 分钟跑通第一个任务

最小可用流程的思路：选一个真实的小项目，先用交互模式完成一次「提问—批准—看到结果」的完整闭环，再切换到非交互模式验证脚本化调用。

步骤一：cd 进入项目目录，运行 claude 启动交互式 REPL。步骤二：输入自然语言任务，例如「描述这个仓库的功能与模块划分」，代理会提出读取文件的请求，按回车批准即可。步骤三：让它执行一个小改动，并跑测试验证，例如「把日志输出改为 JSON 格式，然后运行 go test」。步骤四：在会话中执行 /init 生成 CLAUDE.md 沉淀项目规范，之后新会话自动加载。步骤五：退出后体验会话管理——claude -c 继续最近会话，claude --resume <会话ID> 恢复指定会话。

进阶技巧：Claude Code 提供官方 SDK，可在 Node.js 服务里以代码方式调用代理能力，适合把终端能力嵌入自研工具链。

cd ~/workspace/my-serviceclaude "这个仓库怎么启动？入口在哪里？"    # 交互模式直接带问题启动claude                                   # 或进入 REPL 后输入任务claude -p "统计本仓库 Go 文件行数并输出 top5"  # 非交互一次性任务claude -c                                # 继续最近一次会话claude --resume 2f4a...                  # 恢复指定会话

// Claude Code SDK：在 Node 服务中以代码方式调用import { query } from "@anthropic-ai/claude-code"; const res = await query("Review the latest commit and list potential bugs", {  options: {    cwd: "/path/to/repo",           // 工作目录    permissionMode: "acceptEdits",  // 允许自动编辑    model: "sonnet",                // 指定模型  },});console.log(res.text);              // 终端文本输出

核心能力详解：5 大支柱

支柱一·代理式编码循环。代理内置 Read（读文件）、Edit（定点编辑）、Bash（执行命令）、Glob/Grep（检索）等工具，能在「读代码→改代码→跑测试→看报错→再修」的循环里自主迭代。遇到编译错误时，它会自己查看日志定位原因并重试，不需要人把报错粘贴给模型。

支柱二·CLAUDE.md 项目记忆。放在项目根目录的记忆文件，每个会话启动时自动加载，可用 @other.md 语法引用仓库内其他文档。适合写入架构约定、启动命令、测试命令与代码风格要求；/init 命令会扫描仓库自动生成初始版本。

支柱三·MCP 扩展生态。通过 claude mcp add <名称> <启动命令> 一条命令接入 MCP 服务器，将浏览器、数据库、工单系统、监控平台等外部能力接入代理；项目级配置写入 .mcp.json，claude mcp list 查看已接入服务器，claude mcp remove 移除。

支柱四·权限与安全模型。--permission-mode 支持 default（逐项询问）、acceptEdits（自动接受文件编辑）、plan（只读规划）、bypassPermissions（跳过确认）四种模式；支持工具级 allowlist/denylist；Hooks 体系（PreToolUse、PostToolUse、Notification 等）可在工具调用前后插入自定义脚本做审计与拦截。

支柱五·自动化与嵌入。-p 非交互模式配合 --output-format text/json/stream-json 供脚本与程序解析；SDK 的 query 接口可在 Node 服务内调用；官方 GitHub Action 把代理接入 PR 流程；ANTHROPIC_BASE_URL 环境变量可指向企业网关，统一计量与管控。

生产部署与监控：从上线到运维

部署方式一·GitHub Actions 集成。anthropics/claude-code-action 可在 PR 打开或更新时自动审查变更、修复失败的测试并提交修复 commit，开发者只做最终 review。CI 中通过 ANTHROPIC_API_KEY 密钥注入认证：

部署方式二·自建调度与服务嵌入。定时任务或事件触发时执行 claude -p "任务描述" --max-turns 40 --output-format json，通过退出码判断成功失败，失败由调用方重试；需要长期运行的场景用 SDK 的 query 嵌入 Node.js 服务，--append-system-prompt 注入企业规范。

可观测性。非交互模式用 --output-format stream-json 消费逐条事件流，实时跟踪代理行为；会话内执行 /cost 查看 token 消耗；用 CLAUDE_CODE_MAX_OUTPUT_TOKENS 限制单次输出上限防止失控；通过 SessionStart/SessionEnd Hook 把会话元数据推送到日志平台，实现成本与行为的统一审计。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>Node 版本过低会导致 CLI 直接启动失败：npm 方式需 Node.js 18+，安装前先执行 node -v；版本过旧时改用官方原生安装脚本，脚本会自动处理运行时。</li><li>CI 中裸用 --dangerously-skip-permissions 等于把任意命令执行权交给模型：应先以 plan 只读模式做审查，或配置工具 allowlist/denylist 与 Hooks 审计，再考虑放宽权限。</li><li>不要把 ANTHROPIC_API_KEY 写进代码或镜像：本地个人环境用 OAuth 登录即可免密钥，CI 用平台 Secrets 注入；必要时设置 ANTHROPIC_BASE_URL 指向公司网关统一计量。</li><li>大仓库一次性全量读入会迅速耗尽上下文与费用：在 CLAUDE.md 中圈定模块边界，用 Glob/Grep 定向检索，按需打开文件，并用 --max-turns 限制代理循环轮数。</li></ul>

# .github/workflows/claude-review.ymlname: Claude Code PR Reviewon:  pull_request:    types: [opened, synchronize]jobs:  review:    runs-on: ubuntu-latest    permissions:      contents: write      pull-requests: write    steps:      - uses: actions/checkout@v4        with:          fetch-depth: 0      - name: Claude Code        env:          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}        uses: anthropics/claude-code-action@v1        with:          claude_code_command: |            claude -p "审查本次 PR 的变更，修复发现的 bug 并输出审查结论。"          github_token: ${{ secrets.GITHUB_TOKEN }}

版本迭代

Claude Code 于 2025 年 2 月以研究预览（Research Preview）形式首次公开，5 月随 1.0 正式版转为 GA，9 月通过 2.0 完成从「单会话代理」到「Agent 原生」的架构升级。版本主线围绕 MCP 扩展、权限安全与多代理协作三条线演进。

AI 应用场景

常见误区

面试题

参考来源

• webpageClaude Code 产品页官方介绍与能力更新公告