# Codex 官方桌面端接入 TikBit：给 AI 的操作指令

> 创业沙拉 | TikBit
>
> 使用方法：把本文件发给能操作你电脑的 AI，再发送：“请按这份文档，把我的 OpenAI Codex 官方桌面客户端接入 TikBit。先检查环境、备份，再配置和验收。密钥由我在本机安全输入。”

本文面向从 OpenAI 官方渠道安装的 **Codex 桌面客户端**。Windows、macOS 分别处理。目标是让桌面客户端中的本地任务通过 TikBit 调用模型；不能据此推定云端任务、ChatGPT 网页或其他 OpenAI 产品也会切换。

执行前，请核对已安装的桌面版本是否支持自定义 provider；完成配置后，按本文步骤验证实际对话和文件工具调用。

## 一、执行目标与必要信息

你是负责本机配置的 AI。请按顺序完成环境检查、备份、配置、密钥接入、重启和验收；不要只回复教程。

| 项目 | 配置值或要求 |
| :---: | :---: |
| 服务地址 Base URL | `https://tikbit.ai/v1` |
| 实际对话接口 | `POST https://tikbit.ai/v1/responses` |
| 协议 | `responses` |
| Provider 标识 | `tikbit` |
| 密钥环境变量 | `TIKBIT_API_KEY` |
| 模型 | 优先使用服务方为该用户确认的模型 ID；未指定时可先核验 `gpt-5.6-sol` |
| API 密钥 | 用户自己的 TikBit API 密钥，通过本机隐藏输入获取 |

`gpt-5.6-sol` 是接入候选，不代表每把密钥都有权限，也不表示当前最新模型。使用精确 API 模型 ID，不能用界面显示名代替。若该模型不可用，核对用户的模型权限后再选择，不猜型号。

请先自动识别操作系统、应用版本与配置路径。只有缺密钥、模型权限不明、公司设备权限拦截或必须由用户操作时才询问。

## 二、先识别实际运行环境并备份

1. 找到 **Codex 桌面应用** 的安装位置和版本，记录它实际使用的引擎；`codex --version` 只代表命令行版本，不能当作桌面版本。不要为了配置应用直接升级或替换现有 CLI。
2. 确认应用实际使用的配置目录。默认候选为 Windows `%USERPROFILE%\.codex\config.toml`、macOS `~/.codex/config.toml`；若应用启动环境设置了 `CODEX_HOME`，优先核对其实际值。终端的 `CODEX_HOME` 不一定等于桌面应用的值。
3. 检查用户级配置、启用的 profile、项目 `.codex/config.toml` 及启动参数是否覆盖 `model` / `model_provider`。先报告冲突来源，再针对实际生效项修改。组织托管策略不允许自定义 provider 时停止，不绕过策略。
4. 在本机非同步目录建立带时间戳的备份，记录将修改的文件、字段和环境变量旧状态。配置文件可能含其他服务的密钥，备份需限制访问，不上传、不贴到对话中。
5. 保留 `auth.json`、系统凭据库、历史对话、MCP、Skills、项目授权和其他 provider。此次接入不需要清空 `.codex` 或先执行 `codex logout`。
6. 如果负责执行的 AI 就在这个 Codex 桌面应用里，先把操作进度与恢复说明保存到本机。完成文件修改后再让用户重启；不要在未交接时结束自己的宿主进程。

不要改 TikBit Obsidian 插件的私有运行目录。此任务针对官方桌面应用自己的配置。

## 三、合并最小配置

以下是最终需要生效的 TOML 结构。**把字段合并到已有文件，不能用这几行覆盖整个配置。**

```toml
model = "gpt-5.6-sol"
model_provider = "tikbit"

[model_providers.tikbit]
name = "TikBit"
base_url = "https://tikbit.ai/v1"
wire_api = "responses"
env_key = "TIKBIT_API_KEY"
requires_openai_auth = false
```

执行要求：

- `model` 换成已确认可用的精确模型 ID。
- `model`、`model_provider` 是顶层字段，放在第一个表头之前，或使用理解 TOML 的编辑方式。不能直接追加到文件末尾，让它们落入其他表中。
- 已有 `[model_providers.tikbit]` 就更新原表，不重复创建表头或键。若同名配置原本指向其他服务，使用另一个唯一 provider 标识并同步修改顶层引用。
- `base_url` 以 `/v1` 结尾，不填 `/v1/responses`，也不填 `/v1/chat/completions`。
- 保留 `wire_api = "responses"`，不要改为旧的 `chat`。仅支持 Chat Completions 的通道不满足此接入要求。
- `env_key` 的值是变量名 `TIKBIT_API_KEY`，不是密钥本身；`requires_openai_auth = false` 不表示免认证，请求仍需 TikBit 密钥。
- 不把密钥写入 `config.toml`，不覆盖全局 `OPENAI_API_KEY`，不把 TikBit 密钥塞进原有 OpenAI 登录凭据。
- 初次接入不额外设置超大上下文、特殊推理档位、WebSocket、Fast 模式或实验功能；先让基础对话和工具调用成功。
- 不降低沙箱权限、不关闭审批，不设置自动放行来解决网络或认证问题。

保存为 UTF-8 后，用 TOML 解析器校验；若可调用桌面应用对应引擎的配置读取接口，再核对实际生效字段。错误信息与配置差异必须脱敏。

## 四、让桌面应用真正拿到密钥

这是接入中最容易漏的一步。只在当前终端执行 `export` 或 `$env:...`，不能保证从桌面图标启动的应用拿到密钥。仅在 `auth.json` 中存在密钥，也不能替代本方案的 `env_key`。

### Windows

推荐使用专用的**当前用户级环境变量** `TIKBIT_API_KEY`。由用户在本机隐藏输入；不要让用户把真实密钥粘贴到聊天、脚本源码或命令历史。

AI 可以在用户可交互的 PowerShell 中执行以下输入逻辑；若自身终端不支持交互，应提供本机输入窗口或让用户在独立终端执行，不要假装输入已完成。

```powershell
$tikbitSecure = Read-Host '请输入你的 TikBit API 密钥（不会显示）' -AsSecureString
$tikbitPlain = [System.Net.NetworkCredential]::new('', $tikbitSecure).Password
if ([string]::IsNullOrWhiteSpace($tikbitPlain)) { throw '密钥为空，未保存' }
[Environment]::SetEnvironmentVariable('TIKBIT_API_KEY', $tikbitPlain, 'User')
$env:TIKBIT_API_KEY = $tikbitPlain
Remove-Variable tikbitPlain, tikbitSecure
```

当前用户环境变量是本机持久存储，**不是加密保险箱**，同账号程序可能读取。不要保存到系统级变量或共享配置。

完成后：

1. 用户保存任务后，正常退出 Codex 桌面应用及其托盘实例。不要结束所有 `codex`、Node 或 Electron 进程，以免影响其他工具。
2. 从已读入新变量的进程启动已识别的官方桌面应用。`Start-Process` 默认继承父进程环境，但应先确认目标确实是桌面应用，不能误启动同名 CLI，也不要硬编码可能随升级变化的安装路径。
3. 若从开始菜单启动仍取不到变量，建立“Codex（TikBit）”专用启动器：先从当前用户环境变量读取 `TIKBIT_API_KEY`，仅在内存中传给目标桌面进程，再启动应用。启动器不能包含密钥字面量。打包应用启动行为如不继承变量，应按实际包装方式处理，不能只凭命令执行成功判定。
4. 再次完整退出后，用用户日常使用的入口重开并验收。必要时由用户保存其他工作后注销、重新登录 Windows，再测试普通图标入口。只关窗口再开可能复用原进程，不能算环境刷新。

### macOS

从 Finder、Dock 启动的应用通常不会按终端方式读取 `.zshrc`。不要把“终端里 `echo` 能读到变量”作为桌面应用已接入的证据，更不要打印密钥。

推荐由执行 AI 创建本机专用的“Codex（TikBit）”启动器：

1. 用系统钥匙串保存密钥；通过本机安全输入或系统界面录入，不把密钥字面量放在 shell 命令参数、脚本或聊天中。若实现不了安全的钥匙串录入，可在说明存储方式后使用用户专有目录中的密钥文件，目录权限 `700`、文件权限 `600`，且目录不在 iCloud、Git 或共享盘中。
2. 启动器运行时从钥匙串或受限文件读取密钥，在自身进程中设置 `TIKBIT_API_KEY`，不打印内容、不开启 `set -x`。
3. 确认原 Codex 应用已正常退出后，读取已安装 `.app` 的 `Info.plist` 中 `CFBundleExecutable`，直接启动对应 `Contents/MacOS/` 可执行文件，使其继承变量。不要猜可执行文件名，也不要假定普通 `open -a` 一定把当前终端环境传给应用。
4. 使用用户实际会点击的启动器完成一次“退出 → 重新启动 → 新建对话”复验。说明今后应使用哪个入口；原 Dock 图标不自动保证同样效果。

如果系统提示钥匙串授权，由用户确认。不要修改应用包内容、绕过系统签名或替换应用内的引擎。

## 五、分层验收，必须做到桌面端

测试可能产生少量 API 用量。只发简短请求，失败时不要高并发或无限重试。

### 1. 检查地址、密钥与模型权限

从安全存储把密钥读入测试进程内存；请求头使用 `Authorization: Bearer <密钥>`，不输出请求头，不把密钥拼入 URL。网络请求保持证书校验开启。

可以调用 `GET https://tikbit.ai/v1/models` 检查该密钥返回的模型清单。模型出现在列表中不等于支持 Codex；若平台不提供该清单，应按服务方确认的模型继续验证 Responses，不能仅凭列表接口失败就断言对话不可用。

随后使用同一密钥和目标模型向 `/responses` 发送最小请求：

```json
{
  "model": "gpt-5.6-sol",
  "input": "只回复 OK",
  "stream": true
}
```

检查状态码及 SSE 流，确认收到实际输出且正常完成，没有流中错误；不是只检查 HTTP 200。保留脱敏的时间、模型、完成状态和请求 ID（如有）。密钥仅发送给已确认的 TikBit 地址；遇到跨域重定向先停下核实。

### 2. 验收官方桌面应用

使用配置后的桌面入口启动 Codex，选择一个空的本地测试文件夹并**新建对话**，不要复用可能保留旧模型/provider 的历史线程。

依次完成：

1. 普通对话：“只回复 OK。”
2. 文件工具：“在当前测试文件夹创建 `tikbit-test.txt`，内容为 `TikBit connection OK`，再用文件工具读取它并告诉我内容。”
3. 追问：“刚才创建的文件叫什么，内容是什么？”
4. 完整退出应用，再从日常入口重开，新建对话重复一次简短问答。

对照工具执行记录和真实文件内容。模型只在正文中写出一段工具代码、没有实际执行，不算工具调用通过。操作受审批拦截时按正常授权流程处理，不自动关闭审批。

同时核对以下证据：

- 生效配置确实是 TikBit provider 和正确地址。
- 若桌面日志提供目的地址，核对模型请求发往 `tikbit.ai`；只取必要片段并脱敏，不导出全部日志。
- 在 TikBit 控制台核对该用户、该密钥和对应时间的模型调用记录，区分前面的接口测试与桌面测试。控制台记录可能延迟；延迟时标记待核对，不直接判失败。

**不能单凭模型说“我是 TikBit”、模型菜单显示 GPT，或终端测试成功，就宣布桌面端接入成功。**

若登录页仍阻挡进入应用，先检查该桌面版本是否支持自定义 provider 及其登录流程；不要反复清空 `auth.json`，也不要把 TikBit 密钥填入固定直连 OpenAI 的入口。无法确认时保留现状并报告具体版本、页面和错误。

## 六、常见问题

| 现象 | 优先检查 |
| :---: | :---: |
| `Missing environment variable: TIKBIT_API_KEY` | 桌面进程没有继承变量；检查启动器、旧进程、用户环境与配置目录 |
| 401 / Invalid token | 密钥是否有效、是否真的发送，provider 的 `env_key` 与变量名是否一致 |
| 403 | 查看脱敏错误正文，区分账户/模型权限、网关策略和网络拦截，不能一律当作密钥错误 |
| 404 / 路径不存在 | 是否拼成 `/v1/v1/responses` 或 `/v1/responses/responses`；模型 ID 是否存在 |
| 429 / 请求太多 | 暂停请求，遵循服务端 `Retry-After`；核对并发、频率、额度及上游错误，不循环重试 |
| 502 / 503 / 流中断 | 记录时间和请求 ID，核对网关及上游状态；不靠降低沙箱权限修复 |
| 模型不存在 / 无可用渠道 | 检查精确模型 ID、用户分组和可用通道，不擅自换成猜测的模型名 |
| 终端能用、桌面不能用 | 桌面配置目录、引擎版本、启动环境、profile 或旧线程与终端不同 |
| 能聊天、不能操作文件 | 核对 Responses 原生工具调用兼容性、工作目录授权与审批；正文中的工具代码不算调用 |
| 仍使用原模型或原订阅 | 检查实际生效配置、新线程、启动覆盖与调用记录，不先删原登录态 |

向服务方反馈时，只发系统/应用版本、发生时间与时区、模型 ID、脱敏错误和请求 ID，不发送完整 API 密钥。

## 七、恢复原配置

恢复前先正常退出目标桌面应用，保留其他工具进程。

1. 只撤销本次修改的顶层字段和 TikBit provider 项。如果接入后没有其他改动，可以恢复完整备份；若有其他新配置，则按差异恢复，不能覆盖后来新增的内容。
2. `TIKBIT_API_KEY` 原来不存在时移除本次新增值；原来存在时恢复旧值。移除或停用本次专用启动器及其新建密钥存储，不删除其他凭据。
3. 保留原 `auth.json`、历史和项目文件，从原入口重启并验证原来的使用方式恢复。
4. 给用户列明恢复结果和备份位置；用户确认无需保留后再清理含敏感信息的备份。

## 八、执行 AI 的交付格式

完成后只需向用户交付以下信息，不能包含密钥：

```text
状态：接入成功 / 配置完成但待桌面验收 / 未完成并已恢复
系统与桌面版本：
实际配置文件：
Provider / Base URL / 模型：
密钥存储方式及日常启动入口：
普通对话 / 文件工具 / 多轮追问 / 重启后测试：逐项通过或待验收
TikBit 路由证据：对应时间、模型、请求 ID 或控制台记录
备份位置与恢复方法：
未完成项及原因：
```

如果只有终端或配置检查权限，就交付“配置完成但待桌面验收”，并明确让用户执行哪一步；不要写成全流程成功。

## 官方配置文档

以下为执行 AI 应复核的官方文档入口：

- [Codex 高级配置](https://developers.openai.com/codex/config-advanced/)
- [Codex 配置参考](https://developers.openai.com/codex/config-reference/)
- [Codex 桌面设置](https://developers.openai.com/codex/app/settings/)
- [Codex 认证](https://developers.openai.com/codex/auth/)

配置字段以已安装版本为准；通过桌面应用的实际调用结果确认接入状态。