Claude Code 安装与使用教程：Windows/macOS、CLI 登录、API Key 与权限配置（2026）

Claude Code 是 Anthropic 的编程 Agent，可以在终端中读取项目、修改文件、执行命令并调用开发工具。它与普通网页聊天的主要区别，是能够直接围绕本地代码仓库完成多步骤任务，因此安装后的第一件事不是选择“最强模型”，而是确认登录方式、工作目录和权限边界。

本文依据 Anthropic 在 2026 年 10 月 6 日可访问的 Claude Code 概览、安装文档、认证文档和设置文档整理。安装命令、账号权限和认证方式可能继续调整，实际操作前应再次打开官方页面核对。

先确认你要使用哪一种编程工具

如果你要使用 Anthropic 官方 Claude Code，请从本文列出的 claude.ai、code.claude.com 和 platform.claude.com 开始。需要 Claude Code 以外的中文编程 Agent 或 Codex 配置教程，也可以查看 ZeoGPT 注册入口。

第三方边界

ZeoGPT 是独立第三方服务，不是 Anthropic、Claude Code 或 OpenAI 官方产品。注册链接含推荐参数，是否注册完全自愿；模型、价格、额度、日志和数据处理规则以平台实时页面与服务条款为准。本文不声称 ZeoGPT 账号、Key 或配置可以直接用于 Claude Code。需要配置 OpenAI Codex 时，可阅读本站的 Codex 官网、CLI 与账号教程。

一、安装前要准备什么

项目	建议
账号	Claude 订阅账号、Claude Console 账号，或组织提供的受支持云服务凭证
终端	Windows Terminal、PowerShell、CMD，或 macOS Terminal
项目	优先使用有 Git 版本控制的测试仓库
权限	先确认公司是否允许代码发送给外部 AI 服务
密钥	使用 API 路径时，从 Claude Console 创建并妥善保存

Anthropic 当前文档说明，终端版 Claude Code 可使用符合条件的 Claude 订阅、Claude Console 或受支持的企业云服务。账号类型、地区和组织策略都会影响可用性；不要根据旧教程推断自己的账号一定已经开放。

第一次使用不要直接打开生产服务器目录、密钥仓库或包含客户数据的项目。先用一个可回退的测试仓库完成安装、登录、读取文件、修改代码和运行测试的全流程。

二、Windows 安装 Claude Code

Claude Code 可以原生运行在 Windows，也可以在 WSL 中运行。项目主要使用 Windows 工具链时，原生安装更直接；依赖 Linux 工具链或希望使用沙箱能力时，可以考虑 WSL 2。

方法 1：PowerShell 原生安装

在 PowerShell 中运行 Anthropic 官方安装命令：

powershell

irm https://claude.ai/install.ps1 | iex

安装完成后关闭并重新打开终端，再验证：

powershell

claude --version
claude doctor

官方文档说明，原生安装会在后台检查更新。执行 claude doctor 可以查看安装、更新和设置文件的只读诊断结果。

方法 2：CMD 安装

如果当前提示符是 CMD，而不是 PowerShell，使用：

bat

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

PowerShell 与 CMD 的语法不同。看到 && is not a valid statement separator，通常是把 CMD 命令粘贴到了较旧的 PowerShell；看到 irm is not recognized，通常是把 PowerShell 命令粘贴到了 CMD。

方法 3：WinGet 安装

powershell

winget install Anthropic.ClaudeCode

WinGet 安装默认需要手动升级：

powershell

winget upgrade Anthropic.ClaudeCode

Windows 原生与 WSL 怎么选

方式	更适合	注意事项
Windows 原生	Windows 项目、PowerShell、Visual Studio 工具链	官方文档当前说明原生 Windows 不支持 Claude Code 的 Bash 沙箱
WSL 2	Linux 工具链、希望使用沙箱执行	应在 WSL 终端内安装和启动，不是在 PowerShell 中启动
WSL 1	无法使用 WSL 2 的兼容方案	官方文档当前说明不支持沙箱

在原生 Windows 上，Git for Windows 是可选项。安装后 Claude Code 可以使用 Git Bash；没有安装时会使用 PowerShell 工具。WSL 环境不需要另外安装 Git for Windows。

如果在 WSL 中使用，进入 WSL 终端后按 Linux 方式安装：

bash

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

三、macOS 安装 Claude Code

方法 1：官方原生安装脚本

bash

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

安装后重新打开终端并验证：

bash

claude --version
claude doctor

方法 2：Homebrew

bash

brew install --cask claude-code

Homebrew 安装不会使用 Claude Code 的后台自动更新，升级时运行：

bash

brew upgrade claude-code

Anthropic 还提供不同的 Homebrew 发布通道。普通用户保留稳定通道即可；是否切换到最新通道，应以官方安装页当时的说明为准。

可选：通过 npm 安装

官方仍提供全局 npm 包，但当前文档要求 Node.js 22 或更高版本：

bash

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

升级使用：

bash

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

不要使用 sudo npm install -g，以免产生目录所有权和安全问题。对于新安装，优先使用官方原生安装脚本，通常可以减少 Node.js 版本和全局 npm 权限问题。

四、第一次启动与 CLI 登录

先进入项目目录，再启动 Claude Code：

bash

cd /path/to/your-project
claude

首次启动会打开浏览器完成认证。登录成功后返回终端即可。以后要切换账号或重新认证，在 Claude Code 会话中输入：

text

/login

查看当前登录与配置状态：

text

/status

退出当前账号：

text

/logout

如果浏览器没有自动打开，官方文档提示可以在终端按 c 复制登录链接，再粘贴到浏览器。在 WSL 2、SSH 或容器里，浏览器有时无法访问本地回调；若网页显示登录代码，将代码粘贴回终端并按提示完成即可。

账号密码、验证码和 API Key 只应输入 Anthropic 官方页面或本机终端。不要让远程“客服”代登，也不要购买共享账号。

五、使用官方 API Key 和环境变量

Claude 订阅登录与 Claude API 是两条认证路径。使用 API Key 时，CLI 会按 Claude Console/API 账户的用量规则工作；不要假定网页订阅额度自动等于 API 额度，也不要引用旧文章里的固定价格。

从 Claude Console 创建 Key 后，可以只给当前终端会话设置环境变量。

Windows PowerShell：

powershell

$env:ANTHROPIC_API_KEY = "你的_API_Key"
claude

macOS、Linux 或 WSL：

bash

export ANTHROPIC_API_KEY="你的_API_Key"
claude

首次检测到 ANTHROPIC_API_KEY 时，Claude Code 会跳过浏览器登录，并要求确认是否使用该 Key。完成测试后可以移除当前会话变量。

PowerShell：

powershell

Remove-Item Env:ANTHROPIC_API_KEY

macOS、Linux 或 WSL：

bash

unset ANTHROPIC_API_KEY

为什么登录后还在走 API Key

官方认证文档说明，环境变量中的 API 凭证可能优先于已保存的订阅登录。若你既登录了 Claude 账号，又设置了 ANTHROPIC_API_KEY，Claude Code 在你批准后会使用 Key。遇到组织已停用、Key 失效或计费主体不符时，应先移除变量，再用 /status 确认当前实际使用的认证方式。

ANTHROPIC_AUTH_TOKEN、ANTHROPIC_BASE_URL 和 apiKeyHelper 主要用于企业网关、代理或动态凭证。只有在组织管理员或服务文档明确给出配置时才使用；不要把来源不明的 Base URL、Token 或脚本写入全局配置。使用第三方网关时，代码、提示词和元数据会经过该服务，应单独审核其日志与数据政策。

六、第一次任务怎么做

先让 Claude Code 只读理解项目：

text

先不要修改文件。请说明这个项目使用的语言和框架、入口文件、构建命令、测试命令，以及你还需要哪些信息。

确认路径和命令正确后，再给一个范围明确的小任务：

text

请修复一个最小范围的测试失败。先说明根因和计划修改的文件；修改后运行相关测试，并展示结果和改动摘要。

常用命令包括：

命令	用途
`claude`	在当前目录启动交互会话
`claude --version`	查看安装版本
`claude doctor`	在无法正常启动时检查安装和设置
`/help`	查看会话内命令
`/status`	查看认证、设置来源和当前状态
`/config`	修改部分个人配置
`/login`、`/logout`	重新认证或退出

七、权限设置与安全边界

Claude Code 可以修改文件和运行命令，实际默认权限模式会随 CLI 版本、账号和组织策略变化。不要根据旧教程假定“每一步都会询问”。启动后先看界面显示的权限模式；终端版可使用 Shift+Tab 在可用模式间切换。

设置文件放在哪里

范围	路径	用途
用户	`~/.claude/settings.json`	当前用户所有项目
团队共享	`.claude/settings.json`	可随仓库提交的团队规则
项目本地	`.claude/settings.local.json`	只对自己和当前项目生效

Windows 中的 ~/.claude 对应 %USERPROFILE%\.claude。项目本地设置不应提交；如果是手动创建，请把 .claude/settings.local.json 加入 .gitignore。

下面的示例只放行固定的检查命令，并阻止读取常见环境变量文件：

json

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

Claude Code 设置文件是严格 JSON，不能写 // 注释，也不能留下尾随逗号。保存后使用 /status 确认设置来源，使用 claude doctor 查看被拒绝或格式错误的配置项。

建议保留的安全习惯

用 Git 或备份保存可回退状态，再让 Agent 修改文件。
不把 .env、私钥、云凭证、生产数据库导出或客户资料交给模型。
不把 API Key 写入仓库、README、截图或共享的 .claude/settings.json。
对安装依赖、删除文件、数据库迁移、部署和 Git 推送逐项检查。
修改后查看 git diff，并运行与改动相关的测试、类型检查和构建。
公司项目先核对组织的数据使用政策和 Claude Code 管理策略。

Anthropic 官方文档说明，macOS 通常把登录凭证保存在系统钥匙串；Linux 默认保存在权限为 0600 的 ~/.claude/.credentials.json；Windows 默认保存在 %USERPROFILE%\.claude\.credentials.json 并继承用户目录访问控制。不要手动复制、编辑或提交这些凭证文件。

八、常见安装与登录报错

1. `claude` 不是命令或 `command not found`

先关闭并重新打开终端，再运行：

bash

claude --version

仍失败时执行 claude doctor；如果连诊断命令也无法运行，重新执行与你系统匹配的官方安装方式，并检查安装目录是否进入 PATH。不要同时混用多种安装方式，以免旧版本或别名抢先被调用。

2. npm 出现 `EBADENGINE`

当前官方文档要求 Node.js 22 或更高版本。先升级 Node.js，再执行：

bash

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

也可以改用官方原生安装脚本，绕开全局 npm 目录和版本问题。

3. 安装脚本返回 403、curl 错误或 HTML 语法错误

先确认复制的是 claude.ai 官方安装地址，并且命令与 PowerShell、CMD 或 Bash 相匹配。网络或企业代理拦截脚本时，可以改用 WinGet 或 Homebrew 等官方列出的安装渠道。不要从陌生网盘下载重新打包的可执行文件。

4. 浏览器登录后没有回到终端

在终端按 c 复制登录链接并手动打开；
WSL、SSH 或容器中若网页给出代码，把代码粘贴回终端；
使用 /login 重新开始认证；
用 /status 检查是否已有其他凭证生效；
查看 Anthropic 服务状态。

5. 已登录却提示认证失败或组织不可用

检查是否仍设置了 ANTHROPIC_API_KEY 或其他组织网关变量。移除不需要的变量后重新启动 Claude Code，并用 /login、/status 核对实际账号和组织。Key 已撤销、组织已停用或管理员强制登录方式时，需要在对应组织中解决，反复重装 CLI 不会修复账号权限。

6. 登录已过期

在会话中运行：

text

/login

再用 /status 确认状态。长期后台任务在凭证到期后可能停止，应在无人值守运行前检查登录状态。

7. 设置文件不生效或出现 `Settings Error`

检查 JSON 是否包含注释、尾随逗号、拼错的键或格式错误的权限规则。使用 /status 查看加载了哪些设置来源，使用 claude doctor 查看具体被忽略的项。组织托管设置优先级更高，本地文件无法覆盖管理员强制策略。

8. Windows 找不到 Git Bash

原生 Windows 没有 Git for Windows 时，Claude Code 会使用 PowerShell 工具。如果需要 Bash，可以安装可信来源的 Git for Windows；若已经安装但仍找不到，应按官方设置文档配置实际的 Git Bash 路径，不要照搬别人的盘符。

9. WSL 搜索慢或结果不完整

官方排错文档建议把项目放在 WSL 的 Linux 文件系统，例如 /home/用户名/项目，避免长期在 /mnt/c/ 跨文件系统读取。也可以改用原生 Windows 运行 Claude Code。

10. 权限提示与预期不同

先确认当前 CLI 版本、界面显示的权限模式和组织策略。使用 Shift+Tab 切换当前会话模式，并检查用户、项目和本地设置文件。对生产目录不要为了省一次确认而直接开启宽泛权限。

九、Claude Code、Codex 和 Grok API 怎么选

需求	建议阅读
使用 Anthropic 编程 Agent	本文 Claude Code 安装、登录和权限教程
使用 OpenAI 编程 Agent	ChatGPT Codex 官网、CLI 与账号教程
安装 Codex 并了解第三方配置	Codex 下载、安装与配置教程
对比两个编程 Agent	Codex 与 Claude Code：安装、认证、权限和费用对比
用 Python 调用 xAI 接口	Grok API Python 与错误处理教程

三者的账号、API Key、计费和数据处理主体不同。不要把 Claude API Key、OpenAI API Key 和第三方平台 Key 混用，也不要因为某个平台界面写着“兼容”就假定所有工具和接口都可直接互换。

十、常见问题

Claude Code 支持 Windows 吗？

支持。Anthropic 提供 Windows PowerShell、CMD 和 WinGet 安装方式，也支持在 WSL 中运行。原生 Windows 与 WSL 的沙箱和工具链能力不同，应按项目所在环境选择。

Claude Code 一定要通过 npm 安装吗？

不需要。官方目前优先提供原生安装脚本，另有 Homebrew、WinGet 和 npm。npm 方式当前要求 Node.js 22 或更高版本。

Claude 网页订阅是否等于 API 额度？

不能这样理解。订阅登录和 Claude Console/API Key 是不同的认证与用量路径，具体权益和用量应查看账号与 Console 的实时页面。

API Key 应该写进 `.env` 吗？

本地服务可能用 .env 管理开发变量，但密钥文件必须排除版本控制，并限制访问权限。对 Claude Code CLI，可先使用当前终端会话的环境变量，测试结束后移除。不要把 Key 写进共享设置或文章示例。

如何确认 Claude Code 当前使用哪个账号或 Key？

在会话中运行 /status。如果同时存在订阅登录、API Key、企业网关或云服务凭证，应先清理不需要的环境变量，再重新检查。

ZeoGPT 是 Claude Code 官方入口吗？

不是。ZeoGPT 是第三方服务，本文只把它作为 Codex 等中文编程工具的可选参考入口，不代表 Anthropic 官方授权或 Claude Code 兼容性承诺。

参考资料

本站为独立的 AI 教程站，不属于 Anthropic、Claude Code、OpenAI 或 ZeoGPT。安装方式、账号资格、API 权限和产品功能以各平台实时页面为准。

Claude Code 安装与使用教程：Windows/macOS、CLI 登录、API Key 与权限配置（2026） ​

先确认你要使用哪一种编程工具 ​

一、安装前要准备什么 ​

二、Windows 安装 Claude Code ​

方法 1：PowerShell 原生安装 ​

方法 2：CMD 安装 ​

方法 3：WinGet 安装 ​

Windows 原生与 WSL 怎么选 ​

三、macOS 安装 Claude Code ​

方法 1：官方原生安装脚本 ​

方法 2：Homebrew ​

可选：通过 npm 安装 ​

四、第一次启动与 CLI 登录 ​

五、使用官方 API Key 和环境变量 ​

为什么登录后还在走 API Key ​

六、第一次任务怎么做 ​

七、权限设置与安全边界 ​

设置文件放在哪里 ​

建议保留的安全习惯 ​

八、常见安装与登录报错 ​

1. claude 不是命令或 command not found ​

2. npm 出现 EBADENGINE ​

3. 安装脚本返回 403、curl 错误或 HTML 语法错误 ​

4. 浏览器登录后没有回到终端 ​

5. 已登录却提示认证失败或组织不可用 ​

6. 登录已过期 ​

7. 设置文件不生效或出现 Settings Error ​

8. Windows 找不到 Git Bash ​

9. WSL 搜索慢或结果不完整 ​

10. 权限提示与预期不同 ​

九、Claude Code、Codex 和 Grok API 怎么选 ​

十、常见问题 ​

Claude Code 支持 Windows 吗？ ​

Claude Code 一定要通过 npm 安装吗？ ​

Claude 网页订阅是否等于 API 额度？ ​

API Key 应该写进 .env 吗？ ​

如何确认 Claude Code 当前使用哪个账号或 Key？ ​

ZeoGPT 是 Claude Code 官方入口吗？ ​

参考资料 ​

Claude Code 安装与使用教程：Windows/macOS、CLI 登录、API Key 与权限配置（2026）

先确认你要使用哪一种编程工具

一、安装前要准备什么

二、Windows 安装 Claude Code

方法 1：PowerShell 原生安装

方法 2：CMD 安装

方法 3：WinGet 安装

Windows 原生与 WSL 怎么选

三、macOS 安装 Claude Code

方法 1：官方原生安装脚本

方法 2：Homebrew

可选：通过 npm 安装

四、第一次启动与 CLI 登录

五、使用官方 API Key 和环境变量

为什么登录后还在走 API Key

六、第一次任务怎么做

七、权限设置与安全边界

设置文件放在哪里

建议保留的安全习惯

八、常见安装与登录报错

1. `claude` 不是命令或 `command not found`

2. npm 出现 `EBADENGINE`

3. 安装脚本返回 403、curl 错误或 HTML 语法错误

4. 浏览器登录后没有回到终端

5. 已登录却提示认证失败或组织不可用

6. 登录已过期

7. 设置文件不生效或出现 `Settings Error`

8. Windows 找不到 Git Bash

9. WSL 搜索慢或结果不完整

10. 权限提示与预期不同

九、Claude Code、Codex 和 Grok API 怎么选

十、常见问题

Claude Code 支持 Windows 吗？

Claude Code 一定要通过 npm 安装吗？

Claude 网页订阅是否等于 API 额度？

API Key 应该写进 `.env` 吗？

如何确认 Claude Code 当前使用哪个账号或 Key？

ZeoGPT 是 Claude Code 官方入口吗？

参考资料