常见问题与排查清单
从安装失败、401、超时、模型不可用到配置文件不生效，按顺序排查。
先确认命令是否安装成功
再确认 Base URL、API Key 和模型名
最后看网络、代理和客户端配置文件
Q1：codex: command not found / 找不到命令
通常是 npm 全局安装路径没有加入 PATH，或安装没有成功。
- 先运行 codex --version 验证。
- 重新安装：npm install -g @openai/codex。
Q2：Linux / macOS 安装时报权限错误
可以先用：
长期方案是把 npm 全局目录改到用户目录。
Q3：Windows 找不到 .codex 文件夹
在资源管理器中打开“显示隐藏的项目”，因为 .codex 是隐藏目录风格。
Q4：Base URL 到底应该填哪个？
按客户端类型区分：OpenAI Compatible（OpenAI 兼容）客户端填写 https://api.jojokey.com/v1；Claude Code 的 ANTHROPIC_BASE_URL 填写 https://api.jojokey.com。
不要把官网首页地址直接填进 OpenAI 兼容客户端，否则客户端可能请求到错误路径，表现为 401、404、model not found 或一直连不上。
Q5：配置了 Key 但仍提示未认证 / 401
确认两点：
- Key 是否复制完整，没有多余空格。
- auth.json 中变量名是否与 config.toml 的 env_key 一致。
Q6：一直连不上 / 超时 / 网络错误
- 检查 base_url 是否完全一致。
- 如果在公司或校园网络，可能需要代理或放行相关域名。
- 先关闭 stream，使用最小请求排查。
Q7：模型不可用 / model not found
请先打开模型广场确认当前可用模型名。模型名不匹配会直接失败。
Q8：config.toml 写了但好像没生效
最常见原因是 model_provider 和 [model_providers.xxx] 名字不一致。比如前面写 proxy，下面也必须是 [model_providers.proxy]。
Q9：怎么升级 Codex CLI？
Q10：还有哪些高级参数可以查？
Codex CLI 默认从 ~/.codex/config.toml 读取配置，也支持用 -c key=value 临时覆盖。遇到高级问题时，可以先查官方 command line options 与 config reference。
Q：curl 成功但 Agent / SDK 失败怎么办？
优先让 Agent / SDK（智能体 / 开发包）改用 https://api.jojokey.com/v1。如果客户端会自动追加 /v1，则填写 https://api.jojokey.com。排障时请提供请求时间、实际 URL、HTTP 状态码、cf-ray、x-oneapi-request-id、User-Agent（客户端标识）、出口公网 IP、是否 stream（流式）以及最小 curl 复现结果。完整说明见 Agent / SDK 调用指南。