ARTICLE DETAIL

资讯详情

深耕网站建设、视觉设计与SEO优化的一线实战洞察。

[效率] 从安装部署到入门 Claude Code:三条安装路线、模型接入、权限模式与日常命令一次讲清

[效率] 从安装部署到入门 Claude Code:三条安装路线、模型接入、权限模式与日常命令一次讲清

💡这两年我装过、也用过的 AI 编程工具不少:Cursor、Trae、Qoder、Codex,还有直接在终端里跑的 Claude Code。前几个都有图形界面,看得见摸得着;唯独 Claude Code 一上来就是一个黑乎乎的命令行,很多人第一次装它,卡住的地方既不是订阅也不是模型,而是一句"我这个claude命令怎么敲不出来"。

比较有意思的是,我最近看到好几篇讲 Claude Code 的教程(文末列了链接),大家讲的重点差异非常大:有的只讲"三分钟装完接上国产模型",有的讲怎么把权限收紧、把账号风险降下来,也有的直接把整套命令体系铺开。对刚上手的人来说,这三件事其实是三个阶段的问题——装得上、连得通、用得放心。

于是就很容易出现这种状况:命令装好了,第一次运行却卡在登录;登录过了,跑两句就不断弹权限确认;确认忍了十几次,又开始担心这么用下去到底有没有风险。

这篇想做的事就是把这三个阶段按顺序摊开:先说它到底是什么、跟 AI IDE 有什么不同,再走一遍安装与模型接入,然后讲最容易踩的权限那一块,最后给一份日常命令清单和一个十五分钟跑通的最小闭环。


1. 先把定位说清楚:它是一个跑在你终端里的 Agent

很多人把 Claude Code 理解成"命令行版的 Cursor",这个理解对了一半。

它对的一半是:底层同样是"模型 + 工具调用 + 你的代码仓库"这一套 Agent 循环。不对的一半是:它没有编辑器界面,也不打算替代你的 IDE——它就待在终端里,直接读你的目录、改你的文件、跑你的命令。

大模型(Claude / 兼容端点的其他模型) ↓ Claude Code CLI(会话、上下文、权限判定) ↓ 内置工具(Read / Edit / Write / Bash / Grep / Glob / Web) ↓ 你的本地仓库 + Shell + Git

一句话理解:模型负责思考,CLI 负责把你的授权和上下文喂给它,真正的"手"是那几个内置工具。你在终端里看到的每一句"是否允许执行npm test?",就是权限层在拦这只手。

Q1:它和 Cursor、Trae 这类 AI IDE 到底有什么区别?
维度Claude CodeAI IDE(Cursor / Trae / Qoder 一类)
形态终端 CLI,无界面完整编辑器,图形交互
改动落地直接写你磁盘上的文件在编辑器 diff 面板里确认
执行命令能自己跑 Bash、Git、测试视工具而定,多数也支持终端集成
上下文来源你的目录 +CLAUDE.md+ Git索引 + 你打开的标签页 + @ 引用
适合谁习惯终端、想让 Agent 干长任务的人习惯边看代码边改的人
模型来源官方订阅 / API Key / 兼容端点通常由 IDE 侧统一提供并计费

我自己的用法是:读代码、改多文件、跑测试这类"体力活"交给终端里的 Agent;需要一边看调用链一边手工微调的时候还是回到 IDE。两者不冲突,冲突的是想把它们混成一个界面。

Q2:为什么说它是"Agent"而不是"补全"?

因为它一轮做的事是"规划—执行—观察—再执行"。你让它加一个接口,它会先 Grep 找现有 Controller 的写法,再 Read 看 DTO,然后 Edit 两三个文件,最后自己跑一次编译,报错了回头改。补全类产品做不到这一点,它的循环长度是零。


2. 安装:三条路,选一条就够

系统门槛先摆出来,别在装到第三步才发现环境不达标。

官方要求(安装文档口径):

项要求
macOS13 及以上
Windows10 1809 及以上
LinuxUbuntu 20.04+ / Debian 10+ / Alpine 3.19+
内存4 GB 以上
架构x64 或 ARM64
ShellBash / Zsh / PowerShell / CMD
网络需要联网

Windows 这里有两个细节值得单独说:官方把Git for Windows 列为可选但推荐(因为 Bash 类工具需要它),而沙箱能力只在 WSL 2 里可用,原生 Windows 不支持。也就是说同一份配置,在 WSL2 里能启用的隔离,在原生 CMD 下是失效的。

三条安装路线:

路线 A 原生脚本(推荐,自带后台自动更新) curl -fsSL https://claude.ai/install.sh | bash 路线 B Homebrew(macOS 上最省心) brew install --cask claude-code 路线 C npm 全局(已有 Node 环境的人) npm install -g @anthropic-ai/claude-code
路线命令更新方式卸载适合
原生脚本curl -fsSL https://claude.ai/install.sh | bash后台自动,也可claude updaterm -f ~/.local/bin/claude+rm -rf ~/.local/share/claude想要装了就不管
Homebrewbrew install --cask claude-code(稳定)/claude-code@latest(最新)brew upgrade claude-codebrew uninstall --cask claude-codemacOS 用户
npmnpm install -g @anthropic-ai/claude-codenpm install -g @anthropic-ai/claude-code@latestnpm uninstall -g @anthropic-ai/claude-code已有 Node、团队统一装
Windows 原生irm https://claude.ai/install.ps1 | iexwinget upgrade Anthropic.ClaudeCodewinget uninstall Anthropic.ClaudeCode不想装 Node

装完第一件事不是登录,是先确认命令真的在 PATH 上:

claude--version
Q1:为什么 npm 装的人最容易踩坑?

大概率是这三类:

  • EACCES / 权限报错:全局目录归 root。别用sudo npm install -g硬顶,正确做法是把 npm 全局前缀换到自己的目录(npm config set prefix ~/.npm-global)再重装。
  • 装了但command not found:~/.npm-global/bin或~/.local/bin不在PATH里,往 shell rc 文件追加一行export就完事。
  • Node 版本太老:npm 路线对 Node 有要求,老项目在维护机上很常见,先node -v看一眼再决定用不用 npm。

我个人的建议很直接:如果不是团队协作必须统一装法,就别用 npm 路线。原生脚本自带后台更新,少一个"三个月后你忘了升级"的隐患。


3. 连上模型:官方订阅、API Key、兼容端点,是三件不同的事

这一段是全篇最容易写歪的地方,因为网上多数教程只讲了其中一条路,然后把变量名当口诀背。

先把三条路摆开:

路线怎么认证计费配置成本适合
官方订阅登录浏览器 OAuth 登录(Pro / Max 一类套餐)走订阅额度零配置个人主力使用
Anthropic API KeyANTHROPIC_API_KEY按 token 用量低已有企业账号、需要单独结算
兼容端点(网关/第三方)ANTHROPIC_AUTH_TOKEN+ANTHROPIC_BASE_URL按对方价格中,要配模型映射预算敏感、内网合规、想用国产模型

真正值得记住的是第三条路的变量组合。它的形状是固定的,换哪家都一样:

# 只作为示例,一律用占位符;不要把真实 key 写进任何会被提交的文件exportANTHROPIC_BASE_URL="https://<你的兼容端点>/anthropic"exportANTHROPIC_AUTH_TOKEN="<你的 API Key>"exportANTHROPIC_MODEL="<主模型名>"

但只配ANTHROPIC_MODEL是不够的。Claude Code 内部会按角色挑模型:轻量的后台任务用一个便宜的,主力编码用中档的,复杂推理用顶档的。角色映射漏配,就会出现"明明设了主模型,某些操作却报找不到模型"。完整一点的写法是把它落到配置文件里:

{"env":{"ANTHROPIC_AUTH_TOKEN":"<你的 API Key>","ANTHROPIC_BASE_URL":"https://<你的兼容端点>/anthropic","ANTHROPIC_MODEL":"<主模型>","ANTHROPIC_DEFAULT_HAIKU_MODEL":"<轻量档模型>","ANTHROPIC_DEFAULT_SONNET_MODEL":"<主力档模型>","ANTHROPIC_DEFAULT_OPUS_MODEL":"<顶档模型>","CLAUDE_CODE_SUBAGENT_MODEL":"<子 Agent 模型>","CLAUDE_CODE_MAX_CONTEXT_TOKENS":"200000"}}

这份配置的权威依据是官方环境变量文档,加上各家云厂商自己给的对接示例。我实测参照的是 阿里云百炼的 Claude Code 配置页,它把这套env块、三档角色映射、以及"用ANTHROPIC_AUTH_TOKEN而不是ANTHROPIC_API_KEY"都写得很明确,可以当作兼容端点这一类配置的标准样板来看。

配置文件本身的优先级也要分清,这是新手第二个坑:

文件作用域该不该进版本库
~/.claude/settings.json你机器上所有项目不进
<项目>/.claude/settings.json项目共享(团队约定)进
<项目>/.claude/settings.local.json只对本机的这个项目不进(放个人 key)
~/.claude.json登录态与首次运行状态不进

这里有一个能省掉不少麻烦的细节:如果你走的是兼容端点、根本不打算连官方服务,~/.claude.json里最好有{"hasCompletedOnboarding": true}。否则首次启动会去撞一遍官方流程,表现就是"卡在欢迎页、一直转圈"。百炼文档专门提示了这一点。

Q1:为什么有人配好了变量,/status里却还是 api.anthropic.com?

因为环境变量只对启动它的那个 shell 生效。你写在.bashrc里但没重开终端、或者在 IDE 内置终端里启动而那份环境没继承过来,都会是这个现象。排查方式很土但有效:先在同一个 shell 里echo $ANTHROPIC_BASE_URL,确认拿到了值,再启动claude。

Q2:ANTHROPIC_API_KEY和ANTHROPIC_AUTH_TOKEN有什么区别?

一句话:前者会把 key 明文暴露在进程环境里、并且走 Anthropic 官方认证头语义;后者是网关类接入的通用写法,认证仍由端点自己处理。所有第三方兼容端点的教程几乎都统一用ANTHROPIC_AUTH_TOKEN,这不是习惯问题,而是它们的服务端就按这个头来校验。混用的典型症状是 401。

Q3:模型名能不能随便写?

不能。这里必须看你所用端点的模型列表。我在准备这篇稿子时看到有教程标题写的是某个具体型号名,但我没能在那几家官方模型列表里逐条核实到完全一致的字符串,所以正文里一律写成占位符。宁可按claude --version那样先跑起来看/status,也别照抄一个记不住的型号名。


4. 权限:这一段才是"用得好不好"的分水岭

我见过太多人第一次用就把所有确认都点允许,然后再问"能不能干脆别问我"。

Claude Code 的权限模型只有两个概念:规则(哪一类操作放行/拦截)和模式(这一轮整体多激进)。

规则写在settings.json的permissions里,语法统一是Tool(specifier):

{"permissions":{"allow":["Bash(npm run test:*)","Read(~/.zshrc)"],"deny":["Bash(curl:*)","Read(./.env)","Read(./.env.*)","Read(./secrets/**)"]}}

三个键分别是allow(放行)、ask(每次问)、deny(直接拒,优先级最高)。deny里放.env、secrets/**这类路径,是我认为每个项目都该做的一次配置——因为模型一旦把密钥读进上下文,它就有可能出现在后续请求、日志或者它替你写的测试数据里。

模式则有六种,官方文档列的是default、acceptEdits、plan、auto、dontAsk、bypassPermissions:

模式行为我什么时候用
default该问的问第一次进一个陌生仓库
plan只读+分析,不动文件、不执行大改造、重构、先要一份方案
acceptEdits文件编辑自动接受,命令仍确认日常写代码,最常用
auto更少的打断已经验证过的小范围任务
dontAsk未匹配到规则的直接拒绝CI、脚本里跑
bypassPermissions全部放行只在隔离环境里(见下)

真正需要说清楚的是--dangerously-skip-permissions这个开关。它的名字叫"危险地"不是吓唬人:一旦加上,模型可以不经确认执行任意命令,包括rm -rf、改你的 shell 配置、往 Git 远端推东西。合理用法只有一种——把它放进一个用完即弃的隔离环境里(容器、独立 VM、或 WSL2 沙箱),并且那个环境里没有你不想丢的东西、也没有裸放的凭据。前面提到过:原生 Windows 不支持沙箱能力,所以这个组合在 Windows 上要格外当心。

还有两个更常被忽略的边界控制:--add-dir决定 Agent 能看到哪些目录之外的路径,--allowedTools/--disallowedTools在启动时决定哪些工具压根不加载。缩小工具面比事后拦命令有效得多。


5. 日常命令:第一批记住这十几个就够

内置斜杠命令现在长得吓人(官方命令页列了上百个),但真正构成日常节奏的其实就那么十来个。

命令干什么什么时候用
/init扫描仓库、生成CLAUDE.md每个项目第一件事
/plan切到只规划模式改动大、想先看方案
/compact压缩当前上下文会话长了、答非所问时
/clear清空当前上下文换任务,别让它带着旧记忆
/context看上下文占用明细排查"它是不是没读到我的文件"
/model切换模型简单活用便宜档
/cost、/usage看这次会话/额度消耗月底对账
/permissions图形化改规则不想手改 JSON
/memory编辑记忆文件补项目约定
/doctor自检环境与安装任何"莫名其妙"的第一步
/mcp管理 MCP 服务接外部工具时
/agents管理子 Agent要把活儿拆开时
/rewind回退到某个改动点改坏了想退
/export导出会话存档、贴给同事看
/statusline自定义状态栏想常驻显示目录/模型

两个补充点:

记忆文件是这个工具能不能长期用的关键。~/.claude/CLAUDE.md是你所有项目共享的偏好(比如"提交信息用中文、不要自动 push"),<项目>/CLAUDE.md是项目事实(模块划分、构建命令、代码规范)。对话里直接打#也能当场把一句话写进记忆,这个交互很轻,但养成习惯之后差别很大。

自定义命令不用改代码。官方现在把自定义斜杠命令归到 skills 体系里,用.md文件定义——也就是你写一份"怎么三步跑完一次发布检查"的 Markdown,它就变成了一个可复用的/命令。这对后端同学特别友好:你写的是文档,得到的是工具。

无界面/一次性模式则用来接进脚本:

claude-p"把 src/main/java 下的所有 TODO 注释列出来,输出成表格"
Q:/compact和/clear到底用哪个?

看你想留什么。/clear是把这一轮上下文直接抹掉,适合"我要开始一件完全无关的事";/compact是把已有对话摘要压缩,保留结论但腾出窗口,适合"这件事还没做完,但我已经说了三万字"。我一般在同一任务里连续跑超过二三十轮工具调用后主动/compact,而不是等它自动触发——自动压缩的时机通常已经晚于我需要它的时机。


6. 关于"账号安全",能做的动作其实只有几条

网上有一类标题是"我怎么做到不被封号"。我不打算复制这套叙事,因为其中相当一部分内容本质上是在讲怎么绕开服务条款,那不是我建议你做的事。

但把问题换成"怎么把自己暴露在风控/泄密之下的概率降下来",答案是具体可执行的,而且和技术配置完全相关:

做法为什么有效怎么做
只用自己名下、正规渠道的订阅或 API Key共享账号、来路不明的"合租/代充"是最高频的风险来源没有技术步骤,纯粹是选择
不接来路不明的第三方中转你的全部代码上下文都会流经对方服务器,泄露与滥用风险都在别人手里只连厂商公开的官方端点
Key 永不进仓库、不进 shell 历史一旦提交进 Git,撤回成本高到离谱用settings.local.json+.gitignore;或在 CI 里用密钥管理服务
deny掉敏感路径从源头阻止密钥被读进上下文Read(./.env)、Read(./secrets/**)
高风险执行放隔离环境既能放开手脚,出事也不影响主机容器 / 独立 VM / WSL2 沙箱
定期看/usage、/cost异常用量是最早的信号养成一天一次的习惯
关注官方对可用地区与服务条款的说明是否可用、如何使用要以官方条款为准,不要照抄别人的"经验"读官方条款与定价页
Q:那我用兼容端点是不是就"安全"了?

要分开看。风控意义上,你不再使用官方订阅身份,自然不涉及订阅侧的违规判定;但数据意义上你的代码全部流向另一家服务商,这未必更安全。企业环境里这一步应该由合规决定,而不是由谁便宜谁决定。我自己的判断是:练手用兼容端点没问题,涉及公司代码之前先看清那边的数据处理条款。


7. 十五分钟跑通一个最小闭环

如果你今天只想验证"这东西到底能不能干活",按这个顺序走一遍。

① 装 curl -fsSL https://claude.ai/install.sh | bash claude --version ② 进项目 cd <你的仓库> && claude ③ 建记忆 /init ④ 要方案 /plan → "读一遍现有鉴权逻辑,给出接入 JWT 的改造步骤,先不动代码" ⑤ 放开编辑 切 acceptEdits → 让它执行第 1 个改动 ⑥ 让它自查 "跑一次测试,把失败的地方修掉" ⑦ 看差异 git diff(人工 Review,这步不要省) ⑧ 收工 /cost 看消耗 → /clear 或 /compact

第一次跑的时候,第 ④ 步是最有信息量的:它给出的方案质量,直接取决于/init生成的CLAUDE.md有没有写对。所以我建议CLAUDE.md生成之后人工读一遍,把里面的构建命令、模块边界补准——这是一次性投入、长期收益的典型。


相关报错

  • 下载报错,可能由于网络引起:
==>Fetching downloads for: claude ✘ Cask claude(2.31226.1,8576520051724193e9f74 Downloading14.1MB/384.0MB Error: Download failed on Cask'claude'with message: Download failed: https://downloads.claude.ai/releases/darwin/universal/2.31226.1/Claude-8576520051724193e9f74fc538f9ce8125e9ddd2.zip curl:(18)Transferred a partialfileError: claude: Download failedforclaude.

最后总结

# 命令行安装brewinstall--caskclaude-code# 安装成功之后,查看版本claude--version#vi~/.claude.json"hasCompletedOnboarding":true
  • 安装成功


  • 只是想看一眼它长什么样:原生脚本装 +/init+/plan,十分钟,不动代码。
  • 要日常写代码:acceptEdits+ 角色映射配全 +deny掉敏感路径,这三件事配好,体验会有个明显的台阶。
  • 要跑长任务、批量改动:先把它放进隔离环境,再考虑--dangerously-skip-permissions;顺序不能反。
  • 对后端 / 架构的人来说,我更关注两件事:一是CLAUDE.md的工程价值(它其实是给 AI 看的 README),二是工具面与目录边界的最小化(--allowedTools、--add-dir),这两件做好了,其他都是模型能力的事。
  • 一句话结论:Claude Code 的上手难度不在安装,而在你愿不愿意花二十分钟把权限和配置一次性立好规矩——立好了它是效率工具,立不好它是风险源。

参考资料 & 致谢

[1] 高级设置(安装与卸载)- Claude Code Docs
[2] 环境变量 - Claude Code Docs
[3] 配置权限 - Claude Code Docs
[4] 选择权限模式 - Claude Code Docs
[5] 设置文件和优先级 - Claude Code Docs
[6] Commands(内置斜杠命令)- Claude Code Docs
[7] CLI 参考 - Claude Code Docs
[8] 使用 skills 扩展 Claude - Claude Code Docs
[9] Claude Code - 大模型服务平台百炼
[10] 一人公司AI团队9:我是怎么做到 Claude Code 不被封号的 - 哔哩哔哩
[11] 3分钟安装 ClaudeCode 并接入 deepseek-v4-pro 大模型 - 哔哩哔哩
[12] 保姆级 Claude Code 速成,必学!简单!【附完整文档】 - 哔哩哔哩
[13] 国内爽用 Claude Code + Codex,2分钟搞定! - 哔哩哔哩

返回列表