叶智叶 API 文档
SUPPORT

常见问题

安装或使用开发工具时遇到问题，可按下列现象逐项检查。

#连接问题

#401 Unauthorized（未授权）

先确认密钥已正确设置，并检查当前终端是否能够读取对应环境变量。

bash
# Claude Code
test -n "$ANTHROPIC_API_KEY" && echo "已设置" || echo "未设置"

# CodeX / OpenAI 兼容客户端
test -n "$OPENAI_API_KEY" && echo "已设置" || echo "未设置"

# Gemini CLI
test -n "$GEMINI_API_KEY" && echo "已设置" || echo "未设置"
powershell
if ($env:ANTHROPIC_API_KEY) { "已设置" } else { "未设置" }
if ($env:OPENAI_API_KEY) { "已设置" } else { "未设置" }
if ($env:GEMINI_API_KEY) { "已设置" } else { "未设置" }

如果变量为空，请重新设置 API Key，再关闭并重新打开终端或工具。

#Connection refused（连接被拒绝）

最常见的原因是 API 地址填写错误。Claude Code 使用根地址；CodeX 和 OpenClaw 使用带 /v1 的 OpenAI 兼容地址。

bash
# Claude Code
https://api.ziyelian.site

# CodeX / OpenClaw
https://api.ziyelian.site/v1

#网络超时

先检查基础网络连通性：

bash
curl -I https://api.ziyelian.site

如果当前网络需要代理，请在终端中正确设置 HTTP_PROXY 与 HTTPS_PROXY，然后重新启动工具。

#安装问题

#npm 权限错误（EACCES）

Linux 或 macOS 可把 npm 全局目录调整到当前用户目录：

bash
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

将 PATH 配置写入当前 Shell 的配置文件后，重新加载配置并再次安装。

#node: command not found

bash
node --version
npm --version
which node
echo $PATH

使用 nvm 安装的用户可重新加载 nvm；Windows 用户可重新打开终端，并确认 Node.js 安装目录已加入 PATH。

#命令未找到（claude / codex）

bash
npm config get prefix
npm list -g --depth=0
echo $PATH

确认 npm 全局可执行目录已经加入 PATH，然后重新安装对应 CLI。

#配置问题

#环境变量不生效

临时环境变量只对当前终端有效。需要长期使用时，应写入 Shell 配置文件或使用系统级环境变量。

bash
# zsh
source ~/.zshrc

# bash
source ~/.bashrc

修改后重新打开终端，只检查变量是否设置，不要打印或截图完整密钥。

#配置文件找不到

工具提示找不到配置文件时，可手动创建对应目录和文件。

Claude Code：

bash
mkdir -p ~/.claude
# 创建 ~/.claude/settings.json
{
  "env": {
    "ANTHROPIC_API_KEY": "你的智叶_API令牌",
    "ANTHROPIC_BASE_URL": "https://api.ziyelian.site"
  },
  "model": "自行选择一个该Claude Code分组支持的model（在模型广场查看）"
}

CodeX：

bash
mkdir -p ~/.codex
# 创建 ~/.codex/config.toml
model_provider = "zhiye"
model = "自行选择一个该CodeX分组支持的model（在模型广场查看）"

[model_providers.zhiye]
name = "智叶 API"
base_url = "https://api.ziyelian.site/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

export OPENAI_API_KEY="你的智叶_API令牌"

Windows 中将 ~ 替换为 %USERPROFILE%。

#使用问题

#响应速度慢

常见原因是网络延迟或服务器负载。检查网络与代理配置，也可以在有多个可用模型时 选择响应更快的模型。

bash
curl -I https://api.ziyelian.site

#模型不可用

如果提示模型名称无效，请检查拼写，并以智叶模型广场对应分组为准。

可用模型以智叶实时模型与定价页面展示的模型 ID 为准。

#SSL 证书错误

提示 SSL 证书验证失败时，先更新系统 CA 证书：

bash
# Ubuntu / Debian
sudo apt update && sudo apt install ca-certificates

# Fedora
sudo dnf install ca-certificates

# macOS
brew install ca-certificates

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

#Windows 特定问题

#PowerShell 执行策略错误

powershell
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

#编码问题

配置文件出现中文乱码时，请使用不带 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)
)

macOS 特定问题

优先使用与 CPU 架构匹配的 Node.js 24 LTS。Apple Silicon 使用原生 arm64 环境，不要默认强制 Rosetta 或使用未经包支持的 --target_arch 参数。

bash
uname -m
node -p "process.arch"
brew doctor

Homebrew 权限按 brew doctor 的具体提示排查；不要递归修改整棵 /usr/local/Homebrew 的所有权。日志路径随工具版本变化，用当前 CLI 的帮助或诊断命令定位。

#获取帮助

  • Claude Code 可用 --debug-file 指定诊断文件；Codex 默认日志目录为 $CODEX_HOME/log（通常是 ~/.codex/log/），纯文本 TUI 日志可通过显式设置 log_dir 开启。日志可能包含请求内容，分享前请脱敏。
  • 访问智叶 API 控制台查看服务状态、密钥有效性和余额。
  • 参考 Claude Code 文档 与 CodeX 文档。
重点检查
Claude Code 使用不带 /v1 的 https://api.ziyelian.site；CodeX / OpenAI 工具使用带 /v1 的 https://api.ziyelian.site/v1。

大请求与流式响应

请求体大小与模型上下文分别按字节和 Token 计算。请根据模型说明组织输入，并为上传和响应读取设置合理超时。

  • 413：请求体超过入口允许的大小，请缩减单次上传内容。
  • 408：请求未在允许的时间内完成，请检查上传连接及客户端超时。
  • 上下文超限：按业务需要整理历史消息与附件，保留必要的指令和工具结果。
  • 流式中断：核对客户端连接和协议终止事件。HTTP 200 并不等同于完整生成结束。
  • Responses 接口应区分 response.completed、response.incomplete 与 response.failed。
  • 403 / 503：结合响应正文检查 Key 权限、分组、模型及服务状态。

联系客服时提供北京时间、入口域名、模型名、令牌名称（非令牌内容）、请求 ID 或任务 ID，以及脱敏错误信息。

本页目录连接问题