终端AI编程Agent实操：从安装到计划模式

一、本文范围

本文以 Anthropic 推出的终端编程助手 Claude Code 为例。读者可以按步骤完成安装、登录、启动项目、使用计划模式，并排查常见问题。

文中命令依据撰写时的官方文档整理。这类工具更新较快，命令名、菜单和计费规则都可能变化。执行前请以 Anthropic 官网中 Claude Code 的文档页面为准。

二、适用场景与边界

Claude Code 可以读取本地项目文件、搜索代码、执行终端命令并修改文件。它适合以下任务：

1. 跨多个文件的重构，例如统一修改某个模块的接口命名。
2. 编写数据清洗、日志整理、环境检查等小型脚本。
3. 结合报错日志与相关源码，定位问题并给出修改方案。

以下场景不建议直接交给它处理：涉及生产数据库写操作、密钥轮换，或改动范围大到无法逐行审查的情况。助手输出的内容需要人工核对。

模型能一次处理的内容有长度上限，上限取决于所选模型与账户方案。这个上限表示单次请求的token预算，不代表工具会永久记住整个项目。跨会话的项目知识应写入项目说明文件，见第六节。

三、前置准备

1. 操作系统：macOS 或 Linux 可直接安装。Windows 用户建议在 WSL2 的 Ubuntu 中运行，本文示例按 Linux 和 macOS 的终端环境书写。
2. Node.js：npm 安装方式需要 Node.js 18 或更高版本。
3. Git：项目若是 Git 仓库，可以在开始前建立分支，方便回滚。
4. 网络：终端需要能访问 Anthropic 的服务端点。内网环境的代理配置见第九节。
5. 账号：可以使用 Claude 订阅账号登录，也可以使用 Anthropic Console 创建的 API Key。两种方式的计费口径不同，订阅额度与 API 按 token 计费的规则请以官方说明为准。

检查基础工具是否就绪：

node --version
npm --version
git --version

如果 node 版本低于 18，先升级 Node.js。可以通过 nvm 或系统包管理器完成升级。

四、安装

1. 使用 npm 安装

推荐使用 npm 安装。命令如下：

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

不建议对全局安装加 sudo。如果出现权限错误，应调整 npm 的全局安装目录，或者改用 nvm 管理的 Node.js。随意使用 sudo 会让权限问题变得更难追查。

安装完成后验证版本：

claude --version

2. 使用官方安装脚本（可选）

官方也提供原生安装脚本。直接执行 curl ... | bash 前，建议先下载脚本并审查内容：

curl -fsSL https://claude.ai/install.sh -o install.sh
less install.sh
bash install.sh

如果同一台机器上装过多个版本，可以用 which -a claude 查看所有可执行文件的位置。只保留一种安装方式，可以减少版本冲突。

安装后若启动异常，可运行 claude doctor 查看诊断信息。

五、鉴权配置

方式一：交互登录

进入任意目录运行 claude。首次启动时，工具会提示选择登录方式。按提示在浏览器中完成授权即可。登录凭证由工具自行保存，不需要写入 shell 配置文件。

方式二：API Key

在 Anthropic Console 中创建 API Key。不要把密钥写进项目代码、README 或提交记录。推荐把密钥放在单独的文件里，并限制文件权限：

mkdir -p ~/.config
touch ~/.config/claude-env
chmod 600 ~/.config/claude-env

用编辑器打开 ~/.config/claude-env，写入一行：

export ANTHROPIC_API_KEY="你的密钥"

然后在 ~/.zshrc 或 ~/.bashrc 末尾加入加载语句：

[ -f ~/.config/claude-env ] && source ~/.config/claude-env

刷新配置并确认变量已加载：

source ~/.zshrc
echo ${#ANTHROPIC_API_KEY}

第二条命令只输出密钥的长度，不输出密钥内容。如果输出为 0，说明变量没有加载成功。

如果同时存在登录凭证和环境变量，实际生效的认证方式取决于工具版本。遇到认证混乱时，可以在会话中查看当前认证状态，再决定保留哪一种方式。

密钥泄露后，应立即在 Console 中撤销并重新创建。

六、启动工具并配置项目

进入需要处理的项目根目录后启动：

cd /path/to/your/project
claude

启动后，工具会按需读取和搜索文件。它不会预先把整个仓库塞进上下文。

在会话中输入 /init，工具会生成 CLAUDE.md 文件。这个文件记录项目的构建命令、测试命令和代码约定，每次会话都会读取。生成后请人工检查内容，删除不准确的部分，并补充业务规则。例如可以写明：“认证相关代码只能修改 services 目录，不得改动 router 层。”

项目级权限可以写在 .claude/settings.json 中。下面的示例禁止读取环境变量文件和密钥目录