TokenFlashTokenFlash

Claude Code 接入

基于官方安装方式和第三方 provider 接入能力,把 Claude Code 接到 TokenFlash。

这篇指南基于 Claude Code 官方文档整理,适合想在终端中直接使用 TokenFlash 的开发者。内容分为三块:安装、接入、日常使用。

Claude Code 界面示例

Claude Code 在终端中的典型工作界面

先理解 Claude Code 是什么

Claude Code 是 Anthropic 的编码 Agent。它能直接在终端里:

核心功能

功能说明
代码生成根据自然语言描述生成完整的代码实现
文件编辑直接读取、修改、创建项目中的文件
终端操作执行 shell 命令、运行测试、管理依赖
项目理解自动索引项目结构,理解代码关系和上下文
Git 操作提交代码、创建分支、解决合并冲突
调试排错分析错误日志,定位并修复 bug
重构优化大规模代码重构、性能优化建议

与传统的代码补全工具不同,Claude Code 拥有对整个项目的全局理解能力,能够跨文件分析和修改代码,就像一位经验丰富的工程师坐在你旁边。

系统要求

项目最低版本推荐版本
Node.jsv22.0.0v22.x LTS
npmv10+最新稳定版
操作系统macOS 12+ / Ubuntu 20.04+ / WSL2最新稳定版
内存4 GB8 GB+
磁盘空间500 MB1 GB+

提示

Claude Code 不支持原生 Windows(cmd / PowerShell),必须通过 WSL2 使用。

这篇文章会带你完成什么

你做完这篇后,应该能完成这几件事:

  1. 在本地安装 Claude Code
  2. 用 TokenFlash 的 Base URLAPI Key 接入
  3. 在你的项目目录里启动 Claude Code
  4. 执行第一次问答和第一次代码修改任务

安装方式

如果你还没有准备 Node 环境,先看 Node.js 开发环境准备

官方更推荐原生安装脚本,但如果你想和 CodexOpenCode 统一走 Node 环境,也可以直接用 npm。

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

安装后验证:

claude --version

如果能看到版本号,说明工具本身已经安装成功。

如果安装遇到权限错误(EACCES):

# 方法一:使用 sudo(macOS/Linux)
sudo npm install -g @anthropic-ai/claude-code

# 方法二:修改 npm 全局目录权限
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @anthropic-ai/claude-code

各平台安装说明

macOS

# 如果使用 Homebrew 管理的 Node.js
brew install node@22
npm install -g @anthropic-ai/claude-code

Ubuntu / Debian

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
npm install -g @anthropic-ai/claude-code

Windows (WSL2)

# 1. 先在 PowerShell 中安装 WSL2
wsl --install

# 2. 重启电脑后进入 WSL Ubuntu
wsl

# 3. 在 WSL 中安装 Node.js 和 Claude Code
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
npm install -g @anthropic-ai/claude-code

接入 TokenFlash

Claude Code 支持第三方 provider,这是接入 TokenFlash 的关键。TokenFlash 的 API 客户端会与 Anthropic Messages 协议进行转换,所以你只需要配置 Base URL 和 Key 即可。

了解渠道信息

配置项
Base URLhttps://tokenflash.cn
API Key 格式sk-xxxxxxxxxxxxxxxx
协议Anthropic Messages

分组与当前倍率:

分组名称倍率说明
Claude分组0.6(6 折)Claude 模型推荐分组
default1.0(原价)不建议用于已有专用分组的模型

三种配置方式

这里列出三种配置方式,选择一种即可。

方式一:环境变量(推荐) — 优先级最高,最简单直接

# 永久写入配置(bash)
echo 'export ANTHROPIC_BASE_URL=https://tokenflash.cn' >> ~/.bashrc
echo 'export ANTHROPIC_AUTH_TOKEN=sk-你的API密钥' >> ~/.bashrc
source ~/.bashrc

# 或如果你用 zsh(macOS 默认)
echo 'export ANTHROPIC_BASE_URL=https://tokenflash.cn' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN=sk-你的API密钥' >> ~/.zshrc
source ~/.zshrc

临时测试(当前终端有效):

export ANTHROPIC_BASE_URL=https://tokenflash.cn
export ANTHROPIC_AUTH_TOKEN=sk-你的API密钥
claude

方式二:claude config 命令

claude config set anthropicBaseUrl https://tokenflash.cn
claude config set apiKey sk-你的API密钥
claude config list   # 查看当前配置

配置写入 ~/.claude/settings.json,可手动编辑。

配置文件目录结构:

~/.claude/
├── settings.json          # 全局设置(API Key、Base URL 等)
├── credentials.json       # 认证凭证
├── statsig.json           # 功能标记
└── projects/              # 项目级配置
    └── <project-hash>/
        └── settings.json  # 项目特定设置

方式三:手动编辑 settings.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://tokenflash.cn",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_TOKENFLASH_API_KEY",
    "ANTHROPIC_MODEL": "claude-sonnet-5"
  }
}

文件位置:

  • macOS / Linux:~/.claude/settings.json
  • Windows:C:\Users\你的用户名\.claude\settings.json

模型选择

模型特点适用场景
claude-sonnet-5速度与质量平衡日常开发推荐
claude-opus-4-8最强推理能力复杂架构、疑难 bug
claude-fable-5推理增强复杂推理任务

验证连接

启动 Claude Code

claude

首次启动会显示欢迎界面,在 > 提示符后输入:

你好,请告诉我你是什么模型,以及你的 API 地址是什么?

如果配置正确,Claude 会回复当前模型信息和 API Base URL。

检查模型

/model

显示当前使用的模型信息。

连接检查清单

  • claude --version 正常输出版本号
  • echo $ANTHROPIC_BASE_URL 输出 https://tokenflash.cn
  • echo $ANTHROPIC_AUTH_TOKEN 输出你的 API Key
  • claude 可以正常启动并对话
  • /model 显示的模型名称正确

完整配置流程示例

从零开始,以 macOS 为例:

# 1. 确认 Node.js 版本
node --version          # 应 v22.x.x

# 2. 安装 Claude Code
npm install -g @anthropic-ai/claude-code

# 3. 验证安装
claude --version        # 应 Claude Code v1.x.x

# 4. 配置环境变量
echo 'export ANTHROPIC_BASE_URL=https://tokenflash.cn' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN=sk-你的API密钥' >> ~/.zshrc
source ~/.zshrc

# 5. 验证配置
echo $ANTHROPIC_BASE_URL   # 应 https://tokenflash.cn

# 6. 启动 Claude Code
claude

高级配置

多模型切换

# 启动时指定模型
claude --model claude-opus-4-8

# 运行时切换(在 Claude Code 界面中)
/model claude-sonnet-5

推荐创建别名(写入 ~/.zshrc~/.bashrc):

alias cc-sonnet='claude --model claude-sonnet-5'
alias cc-opus='claude --model claude-opus-4-8'
alias cc-quick='claude --model claude-fable-5'

代理设置

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1

提示

TokenFlash 中转站通常不需要代理。代理主要在使用官方 API 时使用。

超时配置

export CLAUDE_CODE_TIMEOUT=180000   # 请求超时(毫秒)
export CLAUDE_CODE_CONNECT_TIMEOUT=30  # 连接超时(秒)

自定义 System Prompt

在项目根目录创建 CLAUDE.md,Claude Code 会自动读取作为上下文参考:

# 项目说明

这是一个 React + TypeScript 项目。

## 编码规范
- 使用函数式组件和 React Hooks
- 所有函数必须有 TypeScript 类型注解
- 组件文件使用 PascalCase 命名
- 工具函数使用 camelCase 命名

## 测试要求
- 修改代码后运行 npm test 验证
- 新功能必须添加单元测试

你也可以在子目录中创建项目级 CLAUDE.md,Claude Code 在访问该目录时会自动加载:

my-project/
├── CLAUDE.md              # 全局项目说明
├── src/
│   └── CLAUDE.md          # src 目录特定说明
└── tests/
    └── CLAUDE.md          # 测试目录特定说明

权限精细管理

claude config set permissions.allow "Read"
claude config set permissions.allow "Write:src/**"
claude config set permissions.deny "Bash:rm -rf *"
claude config set permissions.deny "Bash:sudo *"

对应 settings.json 配置:

{
  "permissions": {
    "allow": ["Read", "Write:src/**", "Bash:npm *", "Bash:git *"],
    "deny": ["Bash:rm -rf *", "Bash:sudo *"]
  }
}

管道输入用法

claude -p 支持非交互模式,适合脚本集成:

# 分析代码
cat src/app.ts | claude -p "分析这段代码的潜在问题"

# 审查 Git diff
git diff HEAD~3 | claude -p "审查这些变更,指出潜在问题"

# 日志分析
cat error.log | claude -p "分析错误日志,找出根因"

权限管理最佳实践

按项目设置权限:

cd my-project
claude config set --project permissions.allow "Read,Write:src/**,Bash:npm *,Bash:git *"

安全建议:

  • 允许 Read 权限(只读是安全的)
  • 允许 Bash:npm *Bash:git *(常用且安全)
  • 谨慎允许 Bash:*
  • 始终禁止 Bash:rm -rf /Bash:sudo *

实用工作流示例

新功能开发:

我需要为用户模块添加一个"忘记密码"功能。请先阅读现有的用户认证代码,
然后设计实现方案,包括 API 接口、前端页面和邮件发送逻辑。

Bug 修复:

用户反馈在提交表单时偶发 500 错误,错误日志如下:
[粘贴日志]
请帮我定位问题并修复。

代码重构:

请将 src/services/ 下所有使用 callback 的代码重构为 async/await 风格,
保持功能不变,添加适当的错误处理。

编写测试:

为 src/components/UserProfile.tsx 编写完整的单元测试,
覆盖正常流程和边界情况,使用 Jest + React Testing Library。

第一次正式使用:一步一步来

1. 进入你的项目目录

cd your-project

2. 启动 Claude Code

claude

3. 先做一个简单问题

请先告诉我这个仓库是做什么的

4. 再做一个低风险任务

请帮我找出这个项目的首页文件在哪里

5. 最后再让它改代码

请帮我在首页加一句欢迎文案

这样最不容易一下子把操作做复杂。

日常怎么用

1. 在项目目录中启动

cd your-project
claude

2. 让它解释代码

帮我解释一下这个仓库的认证流程

3. 让它修改代码

请在这个项目里增加一个登录失败重试提示

4. 常用命令

命令说明
/help显示帮助信息和所有可用命令
/clear清除当前对话上下文
/model查看或切换当前模型
/config查看或修改配置
/cost显示当前会话的 token 使用量和费用
/compact压缩对话上下文(长对话时有用)
/doctor诊断连接和配置问题
/status显示当前状态信息
/quit/exit退出 Claude Code

常见问题

API 连接失败

Error: Failed to connect to API endpoint / ECONNREFUSED / ETIMEDOUT

排查步骤:

# 1. 检查环境变量
echo $ANTHROPIC_BASE_URL   # 应输出 https://tokenflash.cn

# 2. 测试网络连通性
curl -v https://tokenflash.cn
# 返回 401 说明连接正常,问题在 API Key

# 3. 检查 DNS 解析
nslookup tokenflash.cn

# 4. 确认 Base URL
export ANTHROPIC_BASE_URL=https://tokenflash.cn

认证错误

Error: Authentication failed (401) / Invalid API key

排查步骤:

# 1. 确认 API Key 格式
echo $ANTHROPIC_AUTH_TOKEN   # 应以 sk- 开头

# 2. 检查是否有多余空格
echo -n "$ANTHROPIC_AUTH_TOKEN" | wc -c

# 3. 用 curl 直接测试
curl https://tokenflash.cn/v1/messages \
  -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model": "claude-sonnet-5", "max_tokens": 10, "messages": [{"role": "user", "content": "Hi"}]}'

警告

API Key 是从 TokenFlash 平台获取的,不是 Anthropic 官方 Key,两者不通用。

模型不可用

Error: Model not found / Model not available
# 1. 确认模型名称完整
echo $ANTHROPIC_MODEL   # 应输出 claude-sonnet-5 等

# 2. 清除模型配置,使用默认
unset ANTHROPIC_MODEL
claude config remove model

# 3. 访问 TokenFlash 控制台查看可用模型

常见错误:

错误写法正确写法
claude-sonnet-4claude-sonnet-5
claude-4-opusclaude-opus-4-8
claude-4claude-sonnet-5

网络超时

Error: Request timed out / ETIMEDOUT after 30000ms
# 1. 增加超时
export CLAUDE_CODE_TIMEOUT=180000

# 2. 检查代理设置
echo $HTTP_PROXY
echo $HTTPS_PROXY

# 3. 清除代理(如果导致问题)
unset HTTP_PROXY
unset HTTPS_PROXY

与官方 API 的区别

对比项官方 APITokenFlash
Base URLhttps://api.anthropic.comhttps://tokenflash.cn
认证方式x-api-key headerANTHROPIC_AUTH_TOKEN
价格官方定价Claude分组 6 折
计费方式按 token 直接计费通过 TokenFlash 平台
稳定性最高取决于中转站负载
延迟直连最低取决于网络和平台负载
模型可用性第一时间可用可能有短暂延迟

为什么建议先从简单问题开始?

因为非技术用户最容易在第一步就直接让 Agent 做复杂改动。先确认它能理解仓库、能正常响应,再开始真正修改更稳。

其他常见问题

可以在公司内网使用吗?

取决于公司网络策略。如果外网访问受限,可以配置 HTTP 代理:

export HTTP_PROXY=http://your-company-proxy:port
export HTTPS_PROXY=http://your-company-proxy:port

API Key 被泄露了怎么办?

立即在 TokenFlash 控制台重新生成 API Key,并更新本地配置。

费用如何计算?

TokenFlash 按照中转站的渠道定价计费,具体费率请查看 TokenFlash 控制台的费用页面。

支持并发请求吗?

取决于你的 TokenFlash 账户等级和渠道限制,请咨询 TokenFlash 客服了解详情。

配置速查

配置项环境变量命令示例值
API 地址ANTHROPIC_BASE_URLclaude config set anthropicBaseUrlhttps://tokenflash.cn
API 密钥ANTHROPIC_AUTH_TOKENclaude config set apiKeysk-xxx
模型ANTHROPIC_MODELclaude config set modelclaude-sonnet-5
HTTP 代理HTTP_PROXYhttp://127.0.0.1:7890
HTTPS 代理HTTPS_PROXYhttp://127.0.0.1:7890
超时CLAUDE_CODE_TIMEOUT180000(毫秒)

配图示例

Claude Code 终端会话

Claude Code 多步任务场景

说明

建议不要把 Claude Code 和生产应用共用同一个密钥。按工具拆分 API Key,更方便限额管理和排查问题。

官方参考

  1. Claude Code overview
  2. Claude Code setup
  3. Claude Code best practices
  4. TokenFlash API 文档站

一键配置脚本

保存为 setup-claude-code.sh,在 macOS / Linux 上运行:

#!/bin/bash
set -e

echo "配置 Claude Code + TokenFlash..."

if ! command -v node &> /dev/null; then
    echo "Node.js 未安装,请先安装 Node.js 22+"
    exit 1
fi

NODE_VERSION=$(node --version | cut -d'v' -f2 | cut -d'.' -f1)
if [ "$NODE_VERSION" -lt 22 ]; then
    echo "Node.js 版本过低 ($(node --version)),需要 v22+"
    exit 1
fi

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

read -p "请输入你的 TokenFlash API Key: " API_KEY
BASE_URL="https://tokenflash.cn"

SHELL_RC="$HOME/.zshrc"
[ -n "$BASH_VERSION" ] && SHELL_RC="$HOME/.bashrc"

echo "" >> "$SHELL_RC"
echo "# TokenFlash Claude Code" >> "$SHELL_RC"
echo "export ANTHROPIC_BASE_URL=$BASE_URL" >> "$SHELL_RC"
echo "export ANTHROPIC_AUTH_TOKEN=$API_KEY" >> "$SHELL_RC"

echo "配置已写入 $SHELL_RC"
echo "运行 source $SHELL_RC 生效,然后执行 claude 开始使用"

On this page