从安装 Codex 开始使用智算

如何使用

第一次使用的用户请按顺序完成这三步：先安装 Codex，再安装 CCSwitch，最后导入智算的 API 配置。不要一上来直接复制配置文件，容易填错路径、模型或 Base URL。

1. 先安装 Codex

Codex 支持通过命令行安装。普通用户可以先按下面方式安装；如果 Windows 直接安装失败，再使用 WSL 环境安装。

npm install -g @openai/codex

• Windows：先安装 Node.js，再打开 PowerShell 或终端执行上面的安装命令。若提示权限或环境不兼容，建议使用 WSL 后再安装。
• macOS：打开终端执行上面的安装命令。若提示没有 npm，请先安装 Node.js。
• 安装完成后，在终端输入 codex。能打开 Codex 界面，就说明第一步完成。

2. 再安装 CCSwitch

Codex 能打开以后，再安装下面的 CCSwitch。CCSwitch 会帮你把智算的模型、API Key 和 Base URL 写进 Codex 配置里。

3. 最后导入智算

1. 登录智算控制台，创建或复制你的 API Key。
2. 进入本站 API 页面，点击 一键导入 CCSwitch。
3. 浏览器弹出打开 CCSwitch 的确认时，选择允许。
4. 导入成功后，关闭并重新打开 Codex，再开始使用。

长上下文与压缩历史

Codex 连续使用很久以后，会把大量历史、工具调用结果、日志和文件摘要带进下一次请求。这样会让 input_tokens 和 cache_read_tokens 变高，表现为首 token 变慢、任务总耗时变长、费用增加。缓存命中可以减少重复上传，但缓存读取本身仍然会计费，也仍然会消耗上游处理时间。

推荐操作方式

1. 当前会话工作一段时间后，先发送下面的“压缩历史”提示词。
2. 复制 Codex 生成的总结，打开一个新的 Codex 会话。
3. 在新会话开头粘贴总结，再继续提出下一步需求。

请把当前会话压缩成一份可以带到新会话继续工作的交接说明，要求包括：
1. 项目目标和当前进度
2. 已经修改过的文件和关键改动
3. 已经验证过的命令或结果
4. 仍然存在的问题
5. 下一步最应该做什么
6. 需要避免重复踩坑的注意事项

请尽量简洁，但不要遗漏继续工作必需的信息。

哪些情况会明显变慢

• 同一个 Codex 会话连续使用很多轮，没有总结或新建会话。
• 把完整报错日志、完整接口返回、完整构建输出反复粘贴给 Codex。
• 让 Codex 一次性读取或分析大量无关文件。
• 一个问题已经进入反复试错，但仍继续沿用旧会话全部历史。

首选方式：CCSwitch 一键导入

CCSwitch 是一个可视化配置工具，可以帮你管理 Codex 的模型、API Key 和 Base URL。新用户建议按下面流程操作：先安装 CCSwitch，再回到智算控制台点击一键导入。

1. 下载 CCSwitch

优先从官方入口下载。版本更新时，以 GitHub Releases 页面显示的最新版为准。

2. 安装 CCSwitch

• Windows：双击 .msi 安装包，按提示下一步完成安装。若系统安全提示拦截，请确认文件来自上面的官方 GitHub Release 后再继续。
• Windows 便携版：下载 Portable zip，解压到固定目录，例如 D:\Tools\CC-Switch，然后运行里面的 CCSwitch 程序。
• macOS DMG：打开 .dmg 文件，把 CCSwitch 拖到 Applications，再从启动台或应用程序目录打开。
• macOS Homebrew：已经安装 Homebrew 的用户可以执行 brew tap farion1231/ccswitch，然后执行 brew install --cask cc-switch。
• macOS 备用：解压 zip 后打开 CCSwitch。如果提示无法验证开发者，在系统设置的隐私与安全里允许打开。
• Linux deb：在下载目录执行 sudo dpkg -i CC-Switch-*.deb。AppImage 需要先执行 chmod +x CC-Switch-*.AppImage，再双击或命令行运行。

3. 创建智算 API Key

• 登录智算控制台，进入 API 密钥 页面。
• 点击创建 API Key，复制生成的密钥。密钥通常只完整显示一次，请先保存到安全位置。
• 不要把 API Key 发到群聊、截图、公开代码仓库或给陌生人。

4. 使用一键导入

• 保持 CCSwitch 已经安装并能正常打开。
• 回到智算控制台的 API 页面，点击 一键导入 CCSwitch。
• 浏览器询问是否打开 CCSwitch 时，选择允许或打开。
• 导入后在 CCSwitch 里确认 provider 是 智算，模型默认使用 gpt-5.6-luna，也可以按需切换 gpt-5.6、gpt-5.6-sol、gpt-5.6-terra 或旧版 5.5 模型。
• 如果 Codex 已经在运行，导入完成后请关闭并重新打开 Codex，让新配置生效。

5. 开启快速回复

CCSwitch 导入完成后，建议先确认自己正在使用哪个 API Key，再为这个 Key 打开快速回复。快速回复是一个显式开关，不需要在提示词里写“快速回答”，也不需要更换 Base URL。

1. 打开智算控制台，先进入 API 密钥 页面，确认 CCSwitch 或其他客户端正在使用的是哪一个 Key。
2. 在左侧菜单打开 快速回答 页面，页面会列出你账号下的 API Key。
3. 找到正在使用的 Key，把右侧开关切到 快速。如果你有多个客户端分别使用不同 Key，需要分别为对应 Key 开启。
4. 回到 Codex、CCSwitch 或其他客户端继续正常提问。已经打开的 Codex 会话建议重新发起一次请求；如果仍然感觉没有变化，可以关闭并重新打开 Codex。

• 想追求更快响应：开启快速回复，并把推理强度设为 low 或 medium。
• 需要复杂推理或长代码任务：可以继续开启快速回复，但 high 或 xhigh 本身会更慢，这是推理强度带来的正常耗时。
• 关闭后，该 API Key 会恢复普通回答模式；其他 API Key 不受影响。
• 如果客户端里看不到“快速回答”选项，也没有关系。这个开关在智算控制台里设置，设置后对所有平台生效。

6. 导入失败时手动检查

如果一键导入没有反应，或导入后请求失败，请在 CCSwitch 或 Codex 配置里检查下面几项：

model = "gpt-5.6-luna"
model_provider = "智算"
model_reasoning_effort = "xhigh"
disable_response_storage = true

[model_providers."智算"]
name = "智算"
base_url = "https://zhisuanapi.cn/v1"
wire_api = "responses"
requires_openai_auth = true
experimental_bearer_token = "YOUR_API_KEY"

• base_url 必须是 https://zhisuanapi.cn/v1，不能是 https://zhisuanapi.cn/V1。
• experimental_bearer_token 要替换成你自己的 API Key。
• 如果提示模型过载，可以先切换到 gpt-5.5-mini 测试，或稍后重试。

历史记忆迁移（codex）

如果你把 Codex 切换成 API / Provider 登录后，发现以前的本地对话记录看不到，可以用历史同步工具把旧历史重新挂回当前 Codex。新手建议直接复制下面的提示词，让 Codex 帮你安装工具并创建桌面快捷方式。

Windows 版本

先临时关闭电脑上的杀毒软件或安全拦截。该工具是 GitHub 开源项目，若系统提示拦截，请确认来源是下面的 GitHub 地址后再继续。

在这个网站里 https://github.com/GODGOD126/codex-history-sync-tool 装上这个，桌面给我生成快捷方式

Mac 版本

Mac 用户使用下面的工具地址。流程同样是：先让 Codex 安装并创建桌面快捷方式，再完全退出 Codex，最后打开同步工具找回历史。

在这个网站里 https://github.com/CoimgRain/codex-history-sync-tool-mac-account-api-switch 装上这个，桌面给我生成快捷方式。

常见问题

配置生成器

如果 CCSwitch 一键导入不可用，可以用这里生成配置后手动复制。API Key 只在当前浏览器中处理，不会上传。

# CCSwitch / Codex 配置
# 在 CCSwitch 中导入或手动填写时，请确认 base_url 最后的 v1 是小写。
model = "gpt-5.6-luna"
model_provider = "智算"
model_reasoning_effort = "xhigh"
disable_response_storage = true

[model_providers."智算"]
name = "智算"
base_url = "https://zhisuanapi.cn/v1"
wire_api = "responses"
requires_openai_auth = true
experimental_bearer_token = "YOUR_API_KEY"

客户端配置模板

下面模板可以直接复制。只需要把 YOUR_API_KEY 换成你在智算控制台创建的 API Key。

1. Codex Desktop / Codex CLI

配置文件一般是 ~/.codex/config.toml。Windows 用户通常在 %USERPROFILE%\.codex\config.toml。

model = "gpt-5.6-luna"
model_provider = "智算"
model_reasoning_effort = "xhigh"
disable_response_storage = true

[model_providers."智算"]
name = "智算"
base_url = "https://zhisuanapi.cn/v1"
wire_api = "responses"
requires_openai_auth = true
experimental_bearer_token = "YOUR_API_KEY"

2. Cursor

3. Continue

name: 智算
version: 0.0.1
schema: v1

models:
  - name: 智算 GPT-5.6 Luna
    provider: openai
    model: gpt-5.6-luna
    apiBase: https://zhisuanapi.cn/v1
    apiKey: YOUR_API_KEY
    defaultCompletionOptions:
      temperature: 0

4. Cline / Roo Code

5. OpenCode

{
  "$schema": "https://opencode.ai/config.json",
  "model": "智算/gpt-5.6-luna",
  "provider": {
    "智算": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "智算",
      "options": {
        "baseURL": "https://zhisuanapi.cn/v1",
        "apiKey": "YOUR_API_KEY"
      },
      "models": {
        "gpt-5.6": { "name": "GPT-5.6" },
        "gpt-5.6-luna": { "name": "GPT-5.6 Luna" },
        "gpt-5.6-sol": { "name": "GPT-5.6 Sol" },
        "gpt-5.6-terra": { "name": "GPT-5.6 Terra" },
        "gpt-5.5": { "name": "GPT-5.5" },
        "gpt-5.4": { "name": "GPT-5.4" },
        "gpt-5.5-mini": { "name": "GPT-5.5 Mini" },
        "gpt-5.3-codex": { "name": "GPT-5.3 Codex" }
      }
    }
  }
}

快速开始

按下面三步即可完成第一次调用：

• 登录智算，在 API 密钥 页面创建自己的 API Key。
• 在程序或客户端里填写 Base URL：https://zhisuanapi.cn/v1。
• 请求时带上请求头：Authorization: Bearer YOUR_API_KEY。

curl https://zhisuanapi.cn/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-5.6-luna",
    "input": "只回复 ok",
    "store": false
  }'

模型与计费

模型可用性以智算控制台和 /v1/models 返回结果为准。建议从下面模型开始：

查看模型列表

如果客户端支持自动拉取模型，可以调用 /v1/models。

curl https://zhisuanapi.cn/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses API

推荐优先使用 Responses API，适合新版 OpenAI SDK、推理参数和统一输入格式。

curl https://zhisuanapi.cn/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-5.6-luna",
    "instructions": "You are a helpful assistant.",
    "input": "你好，介绍一下你自己。",
    "reasoning": {"effort": "medium"},
    "stream": false,
    "store": false
  }'

如果遇到 Unsupported parameter，先移除报错里提到的参数后重试。

Chat Completions

如果你的工具只支持老格式，就使用 /v1/chat/completions。

curl https://zhisuanapi.cn/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-5.6-luna",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "你好"}
    ],
    "stream": false
  }'

流式输出

把 stream 设置为 true，模型会边生成边返回，适合聊天窗口。

curl https://zhisuanapi.cn/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-5.6-luna",
    "input": "写一段 100 字介绍。",
    "stream": true,
    "store": false
  }'

图片生成

图片生成有两种用法：如果是在 Codex 里使用，用户可以直接在 Codex 中提出生图需求，不需要修改模型设定，继续保持 Codex 的 Base URL 为 https://zhisuanapi.cn/v1，主模型保持 gpt-5.6-luna；如果是自己写 API 请求或使用第三方 GPT 软件，就必须走图片生成接口 /v1/images/generations。

1. 在 Codex 里生图

Codex 的配置不需要改成图片接口，也不要把 model 改成 gpt-image-2。用户直接在 Codex 里说出想生成的图片即可，配置保持下面这样：

model = "gpt-5.6-luna"
review_model = "gpt-5.6-luna"
model_provider = "智算"

[model_providers."智算"]
name = "智算"
base_url = "https://zhisuanapi.cn/v1"
wire_api = "responses"
requires_openai_auth = true

配置好以后，可以在 Codex 里直接提出需求，例如：

帮我生成一张科技感 API 控制台宣传图，适合作为网站首页横幅。

• Codex 主模型仍然是 gpt-5.6-luna，不需要用户修改模型设定。
• 用户可以直接在 Codex 中使用生图，例如让 Codex 生成网站横幅、产品图、插画或宣传图。
• 生图能力作为工具能力触发，不是把 Codex 主模型换成 gpt-image-2。
• 如果当前 Codex 客户端版本没有触发图片工具，可以改用下面的 API 图片接口。

2. 使用 Responses 图片工具

如果你的客户端支持 Responses 工具调用，可以用主模型 gpt-5.6-luna 加上 image_generation 工具。这个方式适合“让模型理解需求后再调用图片工具”的场景。

curl https://zhisuanapi.cn/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-5.6-luna",
    "input": "生成一张科技感 API 控制台宣传图，适合作为网站首页横幅。",
    "tools": [{"type": "image_generation"}],
    "store": false
  }'

3. 直接调用图片生成接口

如果是你自己写代码、使用 curl、或者第三方 GPT 软件支持自定义图片接口，请使用完整地址 https://zhisuanapi.cn/v1/images/generations。

curl https://zhisuanapi.cn/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "未来城市里的智算控制台，干净科技感，电影感光线",
    "size": "1024x1024"
  }'

常见错误

Python / Node SDK

Python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://zhisuanapi.cn/v1",
)

response = client.responses.create(
    model="gpt-5.6-luna",
    input="只回复 ok",
    store=False,
)

print(response.output_text)

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ZHISUAN_API_KEY,
  baseURL: "https://zhisuanapi.cn/v1",
});

const response = await client.responses.create({
  model: "gpt-5.6-luna",
  input: "只回复 ok",
  store: false,
});

console.log(response.output_text);

常见错误

上线检查清单

• Base URL 是否填写为 https://zhisuanapi.cn/v1。
• 请求头是否包含 Authorization: Bearer YOUR_API_KEY。
• 文本模型是否使用 gpt-5.6-luna、gpt-5.5-mini 或控制台展示的可用模型。
• 图片模型是否使用 /v1/images/generations 和 gpt-image-2。
• 不要在代码仓库、截图、群聊里公开 API Key。