从零开始使用 AI 编程客户端

00 / OVERVIEW

新手先看这里

你只需要准备一个 FlareDeep 账号，以及一台可以联网的 Windows、macOS 或 Linux 电脑。

应该选择哪个客户端？

先认识四个名词

如何打开终端

• Windows：点击开始菜单，搜索“PowerShell”，打开“Windows PowerShell”或“终端”。
• macOS：按 Command + Space，搜索“Terminal”或“终端”。
• Linux：在应用列表打开“Terminal”，多数桌面也可按 Ctrl + Alt + T。

01 / CREDENTIALS

获取 API Key 和模型 ID

1. 登录控制台

   打开 FlareDeep 登录页。没有账号时先前往注册页面创建账号。

2. 创建 API Key

   登录后进入“API Key”页面，点击创建。名称可以填写“我的电脑”或客户端名称，方便以后识别。

3. 立即保存密钥

   复制新生成的完整 API Key，暂时保存在本机安全位置。后面的配置需要使用它。

   不要截图或公开 API Key。任何拿到密钥的人都可能消耗你的额度。

4. 确认渠道和模型 ID

   Claude Code 使用 Claude 渠道；Codex CLI 使用 GPT（Codex）渠道。GPT 渠道就是 Codex CLI 对应的渠道。模型 ID 使用平台提供或管理员告知的完整名称。

本文中的 YOUR_FLAREDEEP_API_KEY 和 YOUR_MODEL_ID 都是占位符，必须替换成你自己的内容。

02 / ANTHROPIC

Claude Code 完整教程

Claude Code 使用 Anthropic 原生协议。配置地址必须是 https://flaredeep.cn，不要自行添加 /v1。

1. 安装 Claude Code

   Windows：打开 PowerShell，粘贴：

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

   macOS / Linux：打开终端，粘贴：

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

   等待命令结束。安装过程需要联网，通常需要几十秒到几分钟。

2. 确认安装成功

   关闭当前终端并重新打开，然后运行：

   claude --version

   看到版本号即表示安装成功。出现“找不到命令”时，请查看页面下方的常见问题。

3. 创建配置文件

   Windows：在 PowerShell 依次运行下面两行，第二行会打开记事本：

   New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude"
   notepad "$env:USERPROFILE\.claude\settings.json"

   macOS / Linux：在终端运行：

   mkdir -p ~/.claude
   nano ~/.claude/settings.json

   将下面内容完整粘贴到文件中，把 YOUR_FLAREDEEP_API_KEY 替换为你的密钥：

   {
     "env": {
       "ANTHROPIC_BASE_URL": "https://flaredeep.cn",
       "ANTHROPIC_AUTH_TOKEN": "YOUR_FLAREDEEP_API_KEY"
     }
   }

   保存文件。macOS/Linux 使用 nano 时，按 Ctrl + O 保存，再按 Ctrl + X 退出。

4. 在项目目录启动

   先用 cd 进入你的项目文件夹，再运行 Claude Code：

   # Windows 示例
   cd "C:\Users\你的用户名\Documents\my-project"
   claude
   
   # macOS / Linux 示例
   cd ~/Documents/my-project
   claude

   第一次进入项目时，Claude Code 可能询问是否信任当前目录。确认目录是你自己的项目后再继续。

5. 发送第一条任务

   在输入框中输入一条不会修改文件的简单任务，例如：

   请阅读这个项目，并用中文说明它的主要功能。不要修改文件。

   能正常返回项目说明，且没有出现 401、404 或登录提示，即表示接入成功。

更新与诊断

# 检查安装和环境
claude doctor

# 更新到当前版本
claude update

03 / OPENAI

Codex CLI 完整教程

Codex CLI 通过自定义 model provider 使用 FlareDeep 的 GPT（Codex）渠道和 Responses API。这里的 Base URL 必须包含 /v1。

1. 安装 Codex CLI

   Windows：打开 PowerShell，粘贴：

   powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

   macOS / Linux：打开终端，粘贴：

   curl -fsSL https://chatgpt.com/codex/install.sh | sh

   已经安装 Node.js 的用户也可以运行 npm install -g @openai/codex。

2. 确认安装成功

   关闭终端并重新打开，然后运行：

   codex --version

   看到 Codex 版本号后继续下一步。

3. 保存 FlareDeep API Key

   Windows PowerShell：替换密钥后运行：

   [Environment]::SetEnvironmentVariable(
     "FLAREDEEP_API_KEY",
     "YOUR_FLAREDEEP_API_KEY",
     "User"
   )

   关闭 PowerShell 并重新打开，使环境变量生效。

   macOS（默认 zsh）：

   echo 'export FLAREDEEP_API_KEY="YOUR_FLAREDEEP_API_KEY"' >> ~/.zshrc
   source ~/.zshrc

   Linux（常见 bash）：

   echo 'export FLAREDEEP_API_KEY="YOUR_FLAREDEEP_API_KEY"' >> ~/.bashrc
   source ~/.bashrc

4. 创建 Codex 配置文件

   Windows：在 PowerShell 运行：

   New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex"
   notepad "$env:USERPROFILE\.codex\config.toml"

   macOS / Linux：在终端运行：

   mkdir -p ~/.codex
   nano ~/.codex/config.toml

   粘贴下面配置，把 YOUR_MODEL_ID 替换为控制台显示的模型名称：

   model = "YOUR_MODEL_ID"
   model_provider = "flaredeep"
   
   [model_providers.flaredeep]
   name = "FlareDeep"
   base_url = "https://flaredeep.cn/v1"
   env_key = "FLAREDEEP_API_KEY"
   wire_api = "responses"

   保存文件。注意 TOML 中的英文双引号和下划线不能删除。

5. 进入项目并启动 Codex

   # 先进入你的项目目录
   cd "你的项目路径"
   
   # 启动 Codex
   codex

   进入后输入 /status，确认 provider 显示为 flaredeep，模型名称与你填写的一致。

6. 发送第一条任务

   请先阅读当前项目，只说明它的目录结构和主要功能，不要修改文件。

   能返回项目说明且 `/status` 显示 flaredeep，即表示配置完成。

更新 Codex CLI

使用官方安装脚本的用户可以重新运行安装命令；npm 用户运行：

npm install -g @openai/codex@latest

04 / DESKTOP

Codex App / ChatGPT Desktop 新手教程

OpenAI 当前将 Codex 桌面入口整合在 ChatGPT Desktop 中。官方提供 Windows 和 macOS 客户端，Linux 暂无官方桌面版本。桌面应用与 Codex CLI 使用同一套 Codex 配置， 因此可以通过 config.toml 接入 FlareDeep。

1. 下载官方应用

   打开 OpenAI 官方桌面应用页面，选择 Windows 或 macOS 版本。

2. 完成安装

   Windows：打开下载的安装程序，按界面提示安装。

   macOS：打开下载的 DMG，将应用拖入 Applications（应用程序）文件夹。

3. 登录 OpenAI 账号

   启动应用后选择登录，使用你的 ChatGPT / OpenAI 账号完成浏览器授权。这一步不能使用 FlareDeep API Key。

4. 准备 API Key 和模型 ID

   登录 FlareDeep 控制台，创建并复制 API Key，同时记下要使用的完整模型 ID。API Key 通常只会完整显示一次，请先妥善保存。

5. 保存 FlareDeep API Key

   Windows：打开 PowerShell，把示例中的密钥替换成自己的，然后运行：

   [Environment]::SetEnvironmentVariable(
     "FLAREDEEP_API_KEY",
     "YOUR_FLAREDEEP_API_KEY",
     "User"
   )

   macOS：打开 Terminal（终端），替换密钥后运行：

   launchctl setenv FLAREDEEP_API_KEY "YOUR_FLAREDEEP_API_KEY"

   macOS 注销或重启电脑后需要重新运行这条命令。设置完成后不要在聊天、截图或公开文件中展示 API Key。

6. 创建 Codex 共用配置文件

   Windows：在 PowerShell 运行：

   New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex"
   notepad "$env:USERPROFILE\.codex\config.toml"

   macOS：在终端运行：

   mkdir -p ~/.codex
   nano ~/.codex/config.toml

   粘贴下面的全部内容，把 YOUR_MODEL_ID 替换为控制台中的完整模型 ID：

   model = "YOUR_MODEL_ID"
   model_provider = "flaredeep"
   
   [model_providers.flaredeep]
   name = "FlareDeep"
   base_url = "https://flaredeep.cn/v1"
   env_key = "FLAREDEEP_API_KEY"
   wire_api = "responses"

   Windows 记事本按 Ctrl + S 保存；macOS 的 nano 按 Control + O、回车，再按 Control + X 退出。

7. 完全退出并重新打开应用

   不要只关闭窗口。Windows 在任务栏托盘中退出应用；macOS 在菜单栏选择退出，或按 Command + Q。重新打开后，新环境变量和配置才会生效。

8. 打开项目并验证接入

   在应用中打开一个本地项目文件夹。只授权你确认安全的目录，不要直接开放整个系统磁盘，然后发送：

   阅读当前项目并说明主要功能。先不要修改任何文件。

   应用能够正常回复，并且 FlareDeep 控制台出现对应调用记录或余额变化，即表示桌面端接入成功。

   如果返回 401，请重新检查环境变量中的 API Key；如果提示模型不存在，请核对 YOUR_MODEL_ID 是否已替换且名称完全一致。

Linux 用户请使用 Codex CLI，目前没有官方 Linux 桌面应用。

05 / TROUBLESHOOTING

常见问题与解决方法

提示“找不到 claude”或“找不到 codex”

1. 关闭当前终端窗口并重新打开。
2. 再次运行 claude --version 或 codex --version。
3. 仍然找不到时，重新运行对应的官方安装命令，并检查安装过程是否出现红色错误。

返回 401 或 Unauthorized

• 确认 API Key 没有多余空格、引号或换行。
• 确认密钥未被禁用、过期或超过额度。
• Windows 修改用户环境变量后，需要重新打开终端。
• 不要把控制台登录密码当作 API Key，两者不是同一个凭据。

返回 404 或路径不存在

• Claude Code：ANTHROPIC_BASE_URL=https://flaredeep.cn。
• Codex CLI：base_url=https://flaredeep.cn/v1。

提示模型不存在

先确认客户端与渠道对应正确：Claude Code 使用 Claude 渠道，Codex CLI 使用 GPT（Codex） 渠道。然后检查配置中的模型 ID 是否与平台提供或管理员告知的名称完全一致。

修改配置后仍然没有生效

• 确认文件名不是 settings.json.txt 或 config.toml.txt。
• 确认文件放在当前用户主目录的 .claude 或 .codex 文件夹。
• 关闭客户端和终端后重新打开。
• JSON 配置必须使用英文双引号，末尾不能多写逗号。

请求超时或连接失败

• 先在浏览器打开 https://flaredeep.cn/health，确认服务可访问。
• 检查电脑时间是否准确，以及防火墙、代理或公司网络是否阻止 HTTPS。
• 稍后重试；若持续失败，记录错误文字并前往 QQ 群反馈。

官方资料