AI 原生开放教材

外观

Claude Code & OpenClaw & Codex & WorkBuddy 中文教程课时教程·中文原文 ↗原件 ↓仓库 ↗

第八部分：故障排查 ​

8.1 平台特定问题 ​

Windows平台 ​

问题1：PowerShell执行策略限制

powershell
# 错误信息（原生安装时可能遇到）
claude : 无法加载文件，因为在此系统上禁止运行脚本。

原因：Windows默认安全策略禁止运行未签名脚本

解决方案：

powershell
# 方法1：修改执行策略（管理员PowerShell）- 推荐
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

# 方法2：使用CMD而不是PowerShell
# Win+R → cmd

# 方法3：每次临时允许执行
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

问题2：Windows Defender误报

bash
# 症状：安装过程中文件被删除
# 原因：Windows Defender将claude.exe识别为潜在威胁

# 解决方案
# 1. 添加 Claude Code 安装目录到排除列表
#    Windows安全 → 病毒和威胁防护 → 排除项
#    添加：C:\Users\<用户名>\.local\bin

# 2. 临时禁用实时保护（不推荐）

问题3：命令找不到

bash
# 症状
'claude' 不是内部或外部命令
# 或
claude: The term 'claude' is not recognized as a name of a cmdlet

原因：原生安装目录未添加到PATH

解决方案（手动添加 PATH 环境变量）：

Claude Code 原生安装后，可执行文件通常位于以下路径：

  • 原生安装：C:\Users\<你的用户名>\.local\bin\
  • NPM 安装：C:\Users\<你的用户名>\AppData\Roaming\npm\

方法1：通过系统设置（图形界面，推荐新手用）

  1. 按下 Win + R 打开"运行"对话框
  2. 输入 sysdm.cpl，按回车，打开"系统属性"
  3. 点击 "高级" 选项卡
  4. 点击底部的 "环境变量" 按钮
  5. 在 "用户变量" 区域（上半部分），找到名为 Path 的变量，双击它
  6. 在弹出的"编辑环境变量"窗口中，点击 "新建"
  7. 输入 Claude Code 的安装路径：
    • 原生安装填：%USERPROFILE%\.local\bin
    • NPM 安装填：%APPDATA%\npm\
  8. 点击 "确定" 保存所有对话框
  9. 关闭并重新打开所有终端窗口（重要！已打开的终端不会自动刷新 PATH）

方法2：通过 PowerShell 命令

powershell
# 查看当前用户 PATH
[System.Environment]::GetEnvironmentVariable('Path', 'User')

# 添加 Claude Code 到 PATH（原生安装路径）
$currentPath = [System.Environment]::GetEnvironmentVariable('Path', 'User')
$newPath = "$currentPath;$env:USERPROFILE\.local\bin"
[System.Environment]::SetEnvironmentVariable('Path', $newPath, 'User')

# 如果是 NPM 安装，改用这个路径
# $newPath = "$currentPath;$env:APPDATA\npm"

# 重启 PowerShell 后验证
claude --version

方法3：快捷方式（Win+R）

Win+R → 输入 sysdm.cpl → 回车 → 高级 → 环境变量 → 用户变量的 Path → 编辑 → 新建 → 粘贴路径 → 确定

⚠️ 注意：修改 PATH 后，必须重新打开终端才能生效！已经打开的 PowerShell/CMD 窗口用的还是旧的 PATH，必须关掉重开。

macOS平台 ​

问题1：命令找不到但已安装

bash
# 症状
claude: command not found

# 原因：PATH未更新（原生安装应该自动配置）

# 解决方案：检查原生安装位置
ls ~/.local/bin/claude
# 或
ls /usr/local/bin/claude

# 如果文件存在，添加到PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

问题2：macOS Gatekeeper阻止

bash
# 症状
"claude" cannot be opened because the developer cannot be verified

# 解决方案
# 方法1：移除隔离属性
sudo xattr -r -d com.apple.quarantine ~/.local/bin/claude

# 方法2：在系统设置中允许
# 系统设置 → 隐私与安全性 → 点击"仍要打开"

8.2 原生安装常见问题 ​

问题1：安装脚本下载失败

bash
# 症状
curl: (7) Failed to connect to claude.ai port 443

原因：网络无法访问claude.ai

解决方案：

bash
# 方案1：配置代理
export https_proxy=http://127.0.0.1:7890
curl -fsSL https://claude.ai/install.sh | bash

# 方案2：使用包管理器（Homebrew/WinGet）
brew install --cask claude-code
# 或
winget install Anthropic.ClaudeCode

# 方案3：手动下载安装包
# 访问 https://claude.ai/download 下载对应平台的安装包

问题2：安装版本不是最新

bash
claude --version
# 显示版本较旧

解决方案：

bash
# 原生安装支持自动更新，运行：
claude update

# 或重新运行安装脚本
curl -fsSL https://claude.ai/install.sh | bash

问题3：检测到旧的npm安装

bash
claude --version
# 显示 (npm) 而不是 (native)

解决方案：

bash
# 运行迁移命令
claude install

# 这会自动：
# 1. 检测到npm版本
# 2. 下载原生版本
# 3. 卸载npm版本
# 4. 配置PATH

8.3 网络连接问题 ​

问题：无法访问api.anthropic.com

bash
ping api.anthropic.com
# 请求超时

解决方案：

bash
# 方案1：配置代理（推荐）
export https_proxy=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890
# Windows PowerShell：
$env:https_proxy="http://127.0.0.1:7890"
$env:http_proxy="http://127.0.0.1:7890"

# 方案2：修改DNS
# Windows：设置DNS为8.8.8.8或114.114.114.114
# macOS/Linux：编辑/etc/resolv.conf添加nameserver 8.8.8.8

# 方案3：使用API中转服务
# 设置自定义API端点（见第三部分API Key配置）

问题2：SSL证书错误

症状：

bash
claude
# Error: unable to verify the first certificate

解决方案：

powershell
# Windows：通过Windows Update更新根证书
Start-Process ms-settings:windowsupdate

# macOS：系统自动维护，确保系统保持最新
# 系统设置 → 通用 → 软件更新

# Linux：更新CA证书
sudo apt update && sudo apt upgrade ca-certificates
# 或
sudo yum update ca-certificates

问题3：API连接超时

8.4 API Key 配置问题 ​

问题：环境变量未生效

bash
echo $ANTHROPIC_API_KEY
# 显示为空

解决方案：

bash
# macOS/Linux：确认配置文件
cat ~/.zshrc | grep ANTHROPIC
# 应该看到：export ANTHROPIC_API_KEY="sk-ant-..."

# 如果没有，手动添加
echo 'export ANTHROPIC_API_KEY="你的key"' >> ~/.zshrc
source ~/.zshrc

Windows：

powershell
# 检查是否配置
[System.Environment]::GetEnvironmentVariable('ANTHROPIC_API_KEY', 'User')

# 如果为空，重新配置
[System.Environment]::SetEnvironmentVariable('ANTHROPIC_API_KEY', 'sk-ant-api03-你的key', 'User')

# 重启PowerShell

问题：Key无效或过期

json
{
  "error": {
    "type": "authentication_error",
    "message": "invalid x-api-key"
  }
}

解决方法：

  1. 登录 console.anthropic.com
  2. Settings → API Keys
  3. 检查Key是否被删除或禁用
  4. 如果无效，创建新Key
  5. 更新环境变量

问题3：Key格式错误

症状：Key看起来不完整或有空格

正确格式检查（PowerShell 7）：

powershell
# Key应该满足：
# 1. 以"sk-ant-api03-"开头
# 2. 后面跟长串字母数字
# 3. 总长度约95字符
# 4. 无空格、无换行

# 验证长度
$env:ANTHROPIC_API_KEY.Length
# 应该输出：95左右

# 验证格式
$env:ANTHROPIC_API_KEY -match '^sk-ant-api03-[A-Za-z0-9_-]+$'
# 应该输出：True

常见格式错误：

bash
❌ sk-ant-XXXXX （缺少api03）
❌ sk-XXXXX （缺少ant-api03）
❌ 有空格或换行符
❌ 复制时多复制/少复制字符

8.5 终端相关问题 ​

问题：中文乱码（Windows）

bash
# 临时切换到UTF-8
chcp 65001

# 永久设置
reg add HKCU\Console /v CodePage /t REG_DWORD /d 65001 /f

PowerShell中文显示：

powershell
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

问题3：复制粘贴不工作

不同终端的复制粘贴快捷键不同：

Windows Terminal：

  • 右键选中文本自动复制
  • Ctrl+Shift+C 复制
  • Ctrl+Shift+V 粘贴

Windows CMD：

  • 右键 → 标记 → 选中文本 → 回车复制
  • 右键粘贴

macOS Terminal：

  • Cmd+C 复制
  • Cmd+V 粘贴

Linux终端：

  • Ctrl+Shift+C 复制
  • Ctrl+Shift+V 粘贴
  • 或鼠标中键粘贴（选中即复制）

问题4：命令历史记录丢失

症状：重启终端后之前输入的命令无法通过上下箭头找回

PowerShell 7配置：

powershell
# PowerShell 7默认已配置历史记录
# 查看历史记录位置
$env:APPDATA\Microsoft\Windows\PowerShell\PSReadLine\

# 增强历史记录功能（编辑PowerShell配置文件）
notepad $PROFILE

# 添加以下内容：
Set-PSReadLineOption -HistorySearchCursorMovesToEnd
Set-PSReadLineOption -MaximumHistoryCount 10000
Set-PSReadLineKeyHandler -Key UpArrow -Function HistorySearchBackward
Set-PSReadLineKeyHandler -Key DownArrow -Function HistorySearchForward

Bash/Zsh配置（macOS/Linux）：

bash
# 确认历史记录文件
echo $HISTFILE
# 应该是~/.bash_history或~/.zsh_history

# 如果为空，添加到配置
# Zsh用户（编辑~/.zshrc）：
echo 'export HISTFILE=~/.zsh_history' >> ~/.zshrc
echo 'export HISTSIZE=10000' >> ~/.zshrc
echo 'export SAVEHIST=10000' >> ~/.zshrc
source ~/.zshrc

# Bash用户（编辑~/.bashrc）：
echo 'export HISTFILE=~/.bash_history' >> ~/.bashrc
echo 'export HISTSIZE=10000' >> ~/.bashrc
echo 'export HISTFILESIZE=20000' >> ~/.bashrc
source ~/.bashrc

验证历史记录：

powershell
# PowerShell 7
Get-History

# Bash/Zsh
history | tail -20