> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rayinai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code

> Claude Code 常见问题解答

## 安装与更新

<AccordionGroup>
  <Accordion title="命令未找到">
    **Native Install 或 Homebrew 安装**

    检查安装是否成功：

    ```bash theme={null}
    claude doctor
    ```

    如果提示命令未找到，重新安装：

    ```bash theme={null}
    # macOS Homebrew
    brew install --cask claude-code

    # macOS/Linux Native Install
    curl -fsSL https://claude.ai/install.sh | bash

    # Windows PowerShell
    irm https://claude.ai/install.ps1 | iex
    ```
  </Accordion>

  <Accordion title="如何更新 Claude Code">
    **Native Install（自动更新）**

    Native Install 会自动在后台更新，也可以手动更新：

    ```bash theme={null}
    claude update
    ```

    **Homebrew**

    ```bash theme={null}
    brew upgrade claude-code
    ```

    **WinGet**

    ```powershell theme={null}
    winget upgrade Anthropic.ClaudeCode
    ```
  </Accordion>

  <Accordion title="安装失败">
    **排查步骤**

    1. 检查网络连接
    2. Windows 用户确保已安装 [Git for Windows](https://git-scm.com/downloads/win)
    3. 查看详细错误信息
    4. 参考 [官方文档](https://code.claude.com/docs/en/setup)
  </Accordion>

  <Accordion title="Windows 需要 Git Bash">
    Claude Code 在 Windows 上需要 Git Bash 环境

    **安装 Git for Windows**

    1. 下载 [Git for Windows](https://git-scm.com/downloads/win)
    2. 运行安装程序
    3. 重启终端后再运行 `claude`

    **或使用 WSL**

    ```powershell theme={null}
    wsl --install
    ```
  </Accordion>
</AccordionGroup>

## 配置问题

<AccordionGroup>
  <Accordion title="配置文件在哪里">
    * **macOS/Linux**: `~/.claude/settings.json`
    * **Windows**: `C:\Users\你的用户名\.claude\settings.json`
  </Accordion>

  <Accordion title="API 端点配置">
    Claude Code 使用 Anthropic 格式，端点**不包含** `/v1` 路径

    ```
    https://code.rayinai.com
    ```
  </Accordion>

  <Accordion title="API 连接失败">
    检查环境变量和网络连接

    ```bash theme={null}
    echo $ANTHROPIC_AUTH_TOKEN
    curl -I https://code.rayinai.com
    ```

    确认配置文件 `~/.claude/settings.json` 中的配置正确
  </Accordion>

  <Accordion title="环境变量未生效">
    永久设置环境变量后需要重新打开终端

    ```bash theme={null}
    # 重新加载配置
    source ~/.zshrc
    # 验证
    echo $ANTHROPIC_BASE_URL
    ```
  </Accordion>
</AccordionGroup>

## 使用问题

<AccordionGroup>
  <Accordion title="首次启动很慢">
    首次启动时 Claude Code 需要初始化配置，这是正常现象。后续启动会快很多
  </Accordion>

  <Accordion title="VS Code 扩展配置">
    **配置步骤**

    1. 打开配置目录 `~/.claude`（Windows: `C:\Users\你的用户名\.claude`）
    2. 创建 `config.json` 文件
    3. 写入以下内容

    ```json theme={null}
    {
      "primaryApiKey": "any-value"
    }
    ```

    4. 重启 VS Code

    <Info>
      `primaryApiKey` 值可以任意，只要字段存在即可
    </Info>
  </Accordion>

  <Accordion title="无法连接到 Anthropic 服务">
    如果出现以下错误

    ```
    Unable to connect to Anthropic services
    Failed to connect to api.anthropic.com
    ```

    **解决方法**

    运行以下命令跳过初次配置

    **Windows (PowerShell)**

    ```powershell theme={null}
    $f="$env:USERPROFILE\.claude\settings.json"
    $j=Get-Content $f|ConvertFrom-Json
    $j|Add-Member -NotePropertyName 'hasCompletedOnboarding' -NotePropertyValue $true -Force
    $j|ConvertTo-Json|Set-Content $f
    ```

    **macOS/Linux**

    ```bash theme={null}
    echo '{"hasCompletedOnboarding":true}' > ~/.claude/settings.json
    ```

    重启 Claude CLI
  </Accordion>

  <Accordion title="常用命令">
    | 命令                 | 功能说明       |
    | ------------------ | ---------- |
    | `claude`           | 启动交互式 REPL |
    | `claude "问题"`      | 带初始问题启动    |
    | `claude -p "问题"`   | 一次性问答模式    |
    | `claude -c`        | 继续最近会话     |
    | `claude update`    | 更新到最新版本    |
    | `claude --verbose` | 显示详细日志     |
  </Accordion>
</AccordionGroup>

## 错误排查

<AccordionGroup>
  <Accordion title="API 密钥无效">
    * 确认密钥已正确复制（无多余空格）
    * 检查密钥是否在有效期内
    * 验证账户权限是否正常
    * Claude Code 使用 `https://code.rayinai.com`（无 `/v1`）
  </Accordion>
</AccordionGroup>

## 其他问题

<Card title="联系技术支持" icon="headset" href="mailto:support@rayinai.com">
  如果以上方法无法解决问题，请联系技术支持
</Card>