昨天折腾 Claude Code 的时候，我发现新手最容易卡住的地方不是“它会不会写代码”，而是最前面几步：到底装在哪里、怎么登录、配置文件放哪、为什么终端里突然提示 claude: command not found。这些问题不解决，后面再强的 AI 编程能力也用不上。
这篇就按实战顺序，把 Claude Code 从零安装、登录、配置 settings.json、写 CLAUDE.md、日常使用和常见坑整理一遍。文章面向第一次接触终端 AI 编程助手的新手，命令尽量写成可以复制粘贴的样子。
一、Claude Code 是什么？它不是网页版 Claude
Claude Code 是 Anthropic 官方推出的 agentic coding tool，也就是“会读项目、改文件、跑命令”的 AI 编程助手。它可以在终端、IDE、桌面应用和浏览器等形态里使用。这里重点说的是终端 CLI，也就是我们在服务器或本地电脑里直接敲 claude 的那种用法。
很多人会把几个形态混在一起：网页版 Claude.ai 更像聊天窗口，适合问答、总结、写文案；桌面版更适合日常个人助理和文件交互；IDE 插件适合长期待在 VS Code、JetBrains 里的开发者；而 Claude Code CLI 更适合服务器、SSH、自动化脚本和真实项目目录。简单说：网页版是“问它”，Claude Code 是“让它进项目干活”。
这也是我更看重终端版的原因。像我这边的 WordPress、Hermes Agent、Podman 容器、OpenWrt 路由器，很多操作都发生在命令行里。一个能读文件、执行命令、配合 git 的 Agent，比单纯网页聊天更容易接进真实工作流。
二、安装前先准备什么？
Claude Code 本地只是一个客户端，模型计算主要在云端。你本机需要准备的是运行环境、账号和网络。Linux / macOS 用户可以用官方安装脚本，也可以用 npm。Windows 用户官方也提供了 PowerShell 和 WinGet 方式。
如果你已经有 Node.js，npm 安装是最容易理解的一种：
node -v
npm -v
npm install -g @anthropic-ai/claude-code官方文档里现在也推荐用安装脚本：
curl -fsSL https://claude.ai/install.sh | bash安装方式不用纠结太久。普通桌面或服务器环境，选一种能稳定跑起来的就行。真正重要的是安装后验证，而不是复制了某条命令就默认成功。
三、安装后先做三个验证
装完之后，我建议马上跑这几个命令：
claude --version
claude doctor
claude auth status --textclaude --version：确认命令能找到，并输出版本号。claude doctor：检查安装、更新、依赖和环境。claude auth status或claude auth status --text：确认当前登录/鉴权状态。
我昨天实际踩到的一个坑就是 PATH。Claude Code 已经装在机器上了，但终端里直接敲 claude 报 command not found。最后发现不是配置坏了，而是全局 npm bin 目录没进 PATH。类似问题可以先查：
which claude
npm root -g
npm config get prefix如果你是在 Hermes 这类长期运行服务里调用 Claude Code，还要注意服务进程自己的 PATH 可能和你手动 SSH 进去的 shell 不一样。必要时可以把实际安装位置软链到 /root/.local/bin/claude 或者在脚本里写绝对路径。
四、登录方式：账号订阅和 API Key 都可以
第一次运行 claude，通常会引导你完成登录。个人用户一般走 Anthropic 账号订阅；团队、服务器或自动化场景，也可以用 API Key。具体用哪种，看你的账号和用途。
claude
claude auth status --text如果你用的是第三方兼容网关，就要额外关注环境变量和 settings.json 里的 base URL / API key。这个属于进阶玩法，新手刚开始可以先按官方登录流程跑通，不要一上来就把代理、多个模型、fallback 全塞进去。
五、settings.json：控制模型、权限和环境变量
Claude Code 的配置不是只有一个文件，而是有层级的。常见位置包括：
- 用户级：
~/.claude/settings.json - 项目级：
.claude/settings.json - 本地覆盖：
.claude/settings.local.json
对新手来说，先记住一句话：全局习惯放用户级，项目规则放项目级，个人本机临时设置放 local。权限配置一定要谨慎，尤其是 Bash 命令。
{
"permissions": {
"allow": [
"Read",
"Edit",
"Bash(git diff *)",
"Bash(npm test *)"
],
"deny": [
"Read(./.env)",
"Read(./secrets/**)",
"Bash(rm -rf *)",
"Bash(git push --force *)"
]
},
"env": {
"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
}
}这里不要照抄成万能配置。不同项目的测试命令、构建命令、敏感文件都不一样。我的建议是先保守一点，让 Claude Code 多问几次确认；等你确认它不会乱动，再逐步放开常用命令。
六、CLAUDE.md：比提示词更重要的项目说明书
CLAUDE.md 可以理解成项目里的“AI 入职手册”。你把项目结构、技术栈、测试命令、代码规范、不能碰的目录写进去，Claude Code 每次进项目时就能少猜很多东西。
# Project Notes
- 这是一个 WordPress/Podman 相关项目。
- 修改前先看 git diff。
- Python 脚本用 python3。
- 不要读取 .env、secrets、私钥文件。
- 完成后运行对应测试或至少做语法检查。很多人一开始只会给 Claude Code 发很长的临时提示词。其实更稳的方式是把稳定规则写进 CLAUDE.md，临时提示词只描述这次任务。这样上下文更干净，也更适合长期维护。
七、日常使用：交互模式和 print mode
最常见的用法是在项目目录里直接启动：
cd /path/to/project
claude然后用自然语言描述任务，比如“阅读这个项目，找出登录失败的原因，先给我计划，不要直接修改”。适合重构、排错、写测试这类需要多轮交流的任务。
如果你只是想让它处理一次输入，或者接进脚本，-p / --print 更合适：
claude -p "总结当前 git diff 的改动" --output-format text --max-turns 1
git diff | claude -p "用中文写一条清晰的 commit message" --output-format text --max-turns 1我个人很喜欢 print mode，因为它更像 Unix 工具：输入一段内容，拿到一个结果，然后退出。做批量文章检查、日志总结、代码 diff 摘要都很顺手。
八、常见坑：先排这些，不要一上来重装
- 命令找不到：先查 PATH，不要立刻怀疑账号或模型。
- 登录正常但调用失败：看是不是 API Key、base URL 或网关返回了 401/403。
- 权限确认太多：先保守用，逐步把安全命令加入 allow，不要新手一上来全跳过权限。
- 配置不生效：检查是用户级、项目级还是 local 级文件，以及 JSON 有没有语法错误。
- 改坏文件：让 Claude Code 干活前保持 git 干净，随时可以
git diff和git restore。 - 版本太旧：跑
claude update或对应包管理器更新，再用claude doctor复查。
九、适合谁，不适合谁
Claude Code 适合每天写代码、维护服务器脚本、做自动化、写技术文档的人。特别是你已经习惯命令行、git、项目目录这些东西，它会很快变成一个能帮你拆任务、查文件、跑测试的助手。
它暂时不适合完全不懂命令行的新手，也不适合只想偶尔问两句“这段代码什么意思”的用户。那种场景用网页版就够了。Claude Code 的优势在于能动手，风险也在于它能动手，所以权限、git 状态和项目说明一定要提前管好。
下期预告
后面我会继续把 Agent 安装和实战链路补齐，比如 OpenCode、Codex CLI、Hermes Agent 多模型路由，以及怎么让这些工具配合 WordPress 自动写草稿、配图和发布。等这些基础篇连起来，新手就能看到一条比较完整的“从下载安装到真实工作流”的路线。
本文由 A7z-爱马仕整理，基于公开文档与实际 Agent 工作流搭建经验编写。涉及账号、价格、权限策略的部分，请以官方页面和你自己的后台显示为准。
