TinyPx API 文档

主题

常见问题 ​

本页汇总使用 TinyPx API 配置 Claude Code、Codex 等工具时的常见问题和解决方案。

先看这里

大多数问题都是 API 地址或密钥配置错误导致的。请先确认：

  • Claude Code 使用 https://ai.tinypx.cn（不带 /v1）
  • Codex / OpenAI 兼容工具使用 https://ai.tinypx.cn/v1（带 /v1）

连接问题 ​

401 Unauthorized（未授权） ​

症状：工具提示 API Key 无效或未授权

原因：API Key 未设置、设置错误，或余额不足

解决：

  1. 检查环境变量是否设置：
bash
# Linux/macOS
echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY
powershell
# Windows PowerShell
echo $env:ANTHROPIC_API_KEY
echo $env:OPENAI_API_KEY
  1. 如果为空，重新设置环境变量或检查配置文件
  2. 确认密钥完整复制，注意首尾没有多余空格或换行
  3. 到 API 密钥页 确认密钥状态，或重新生成
  4. 到 钱包页 确认余额充足

Connection refused（连接被拒绝） ​

症状：无法连接到 API 服务器

原因：Base URL 配置错误

解决：

确认使用正确的 API 地址：

  • Claude Code → https://ai.tinypx.cn（不带 /v1）
  • Codex / OpenClaw → https://ai.tinypx.cn/v1（带 /v1）

检查配置：

bash
# Claude Code 配置文件
cat ~/.claude/settings.json

# Codex 配置文件
cat ~/.codex/config.toml

网络超时 ​

症状：请求超时或连接缓慢

解决：

bash
# 检查网络连接
curl -I https://ai.tinypx.cn

# 配置代理（如需要）
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"

安装问题 ​

npm 权限错误（EACCES） ​

方法 1：修改 npm 全局目录（推荐）

bash
# 创建全局目录
mkdir -p ~/.npm-global

# 配置 npm 使用新目录
npm config set prefix '~/.npm-global'

# 添加到 PATH
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 重新安装
npm install -g @anthropic-ai/claude-code

方法 2：使用 sudo（不推荐）

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

node: command not found ​

原因：Node.js 未安装或不在 PATH 中

解决：

bash
# 检查是否安装
which node

# nvm 用户确认已加载
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# 验证版本
node -v    # Claude Code/Codex 需要 v18+，Gemini CLI 需要 v20+
npm -v

命令未找到（claude / codex / gemini） ​

原因：npm 全局路径不在 PATH 中

解决：

bash
# 查看 npm 全局路径
npm config get prefix

添加到 PATH：

bash
# Bash
echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.bashrc
source ~/.bashrc

# Zsh
echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.zshrc
source ~/.zshrc
powershell
# Windows PowerShell
$npmPath = npm config get prefix
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$npmPath", "User")

配置问题 ​

环境变量不生效 ​

原因：未写入正确的配置文件，或未重新加载

解决：

  1. 确认写入了正确的配置文件：

    • Zsh → ~/.zshrc
    • Bash → ~/.bashrc 或 ~/.bash_profile
    • Fish → ~/.config/fish/config.fish

  2. 重新加载配置：

bash
source ~/.bashrc   # Bash
source ~/.zshrc    # Zsh

或直接重开终端。

  1. 验证：
bash
echo $ANTHROPIC_API_KEY

Windows 用户注意

用 SetEnvironmentVariable(..., "User") 设置的变量，当前已打开的终端读不到， 必须重开终端窗口。详见 快速切换配置。

配置文件找不到 ​

手动创建配置目录和文件：

Claude Code

bash
mkdir -p ~/.claude
cat > ~/.claude/settings.json << 'EOF'
{
  "env": {
    "ANTHROPIC_API_KEY": "你的 TinyPx API 令牌",
    "ANTHROPIC_BASE_URL": "https://ai.tinypx.cn"
  },
  "model": "填写该 Claude Code 分组支持的模型名"
}
EOF

Codex

bash
mkdir -p ~/.codex
cat > ~/.codex/config.toml << 'EOF'
model_provider = "tinypx"
model = "填写该 Codex 分组支持的模型名"

[model_providers.tinypx]
name = "TinyPx API"
base_url = "https://ai.tinypx.cn/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
EOF

然后确认 API Key 环境变量已设置：

bash
export OPENAI_API_KEY="你的 TinyPx API 令牌"

改了配置文件却不生效 ​

环境变量的优先级通常高于配置文件。排查时先清掉环境变量，只留一处配置：

bash
# Linux/macOS
unset ANTHROPIC_BASE_URL ANTHROPIC_API_KEY
powershell
# Windows 当前会话
Remove-Item Env:\ANTHROPIC_BASE_URL -ErrorAction SilentlyContinue

使用问题 ​

响应速度慢 ​

原因：网络延迟或服务器负载

解决：

bash
# 检查网络延迟
ping ai.tinypx.cn
  • 如果使用代理，确认 HTTP_PROXY / HTTPS_PROXY 已正确设置
  • 换用更轻量的模型（见 模型广场）
  • 到 使用日志 查看请求耗时记录

模型不可用 ​

症状：提示模型名称无效

解决：

  1. 检查模型名称拼写
  2. 到 模型广场 查看当前可用模型
  3. 确认该模型在你所用令牌对应的分组里可用 —— 不同分组支持的模型不同
  4. 使用模型广场中列出的实际 model 名，不要凭记忆填写

分组概念

TinyPx API 的令牌按分组划分，Claude Code、Codex、Gemini CLI 建议各用对应分组的专用令牌。 一个分组支持哪些模型，以模型广场页面为准。

SSL 证书错误 ​

Linux

bash
sudo apt update && sudo apt install ca-certificates  # Ubuntu/Debian
sudo dnf install ca-certificates                     # Fedora
sudo pacman -S ca-certificates                       # Arch

macOS

bash
brew install ca-certificates

如果问题仍存在，优先检查系统证书、代理证书和网络拦截策略。

Windows 特定问题 ​

PowerShell 执行策略错误 ​

症状：无法运行脚本

powershell
# 以管理员身份运行 PowerShell
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

配置文件中文乱码 / JSON 解析失败 ​

症状：中文显示为乱码，或提示 Unexpected token ''

原因：文件带 BOM 或不是 UTF-8 编码

解决：

powershell
$configContent = Get-Content config.toml -Raw
[System.IO.File]::WriteAllText(
  (Join-Path $PWD "config.toml"),
  $configContent,
  [System.Text.UTF8Encoding]::new($false)
)

Gemini CLI 尤其敏感

Gemini CLI 的 settings.json 必须是 UTF-8 无 BOM，否则直接报 JSON 错误。 详见 Gemini CLI Windows 配置。

macOS 特定问题 ​

Apple Silicon（M 系列芯片）兼容性 ​

bash
# 使用 Rosetta
arch -x86_64 npm install -g @anthropic-ai/claude-code

# 或指定原生架构
npm install -g @anthropic-ai/claude-code --target_arch=arm64

Homebrew 权限问题 ​

bash
sudo chown -R $(whoami) /usr/local/Homebrew

获取帮助 ​

如果以上方案无法解决你的问题：

  1. 查看工具日志

    • Claude Code：~/.claude/logs/
    • Codex：~/.codex/logs/

  2. 查看账户状态

  3. 联系我们

    • 官方 QQ 群：634534003（点击加群）
    • 客服 QQ：179710692

提问时请附上

为了更快定位问题，反馈时请提供：使用的工具与版本、配置文件内容（去掉密钥）、 完整报错信息、使用日志 里对应的请求记录。

相关文档 ​

官方 QQ 群 634534003 · 客服 QQ 179710692

Copyright © 2026 TinyPx API