Codex 插件 DSH 实战：会话归档、配置体检与模型切换

Codex 做的最有价值的一件事，是把对话补全、代码生成和执行终端命令放进同一个交互闭环里。但很多人在连续使用几周后会遇到同一个问题：会话历史越攒越多，配置项散落在不同文件里，换一台机器也不知道哪些设置要带走。于是社区里出现了以 DSH 为代表的一类插件项目，目标是尽量还原 Codex 原生交互体验，同时把会话归档、配置校验、模型切换这些本地管理工作做成独立可复用工具。本文以一个最小可运行的 DSH 插件为案例，从配置目录结构讲到归档和校验实现，再讲第三方模型接入和安装排错。整个过程中不修改 Codex 主程序，不依赖任何内部接口，只使用公开的本地配置文件和会话数据，适合想把 Codex 用得更顺手、又不想动核心程序的开发者。

1. 先搞懂 Codex 把配置和会话存在哪里，插件才知道要管什么

做插件的第一件事不是写代码，而是确认数据放在哪里。如果连配置文件和会话目录都找错，后面所有功能都会建立在错误的地基上。很多 DSH 插件项目早期版本频繁失效，问题往往不在插件本身，而是 Codex 升级后目录结构或配置字段发生了变化。

1.1 为什么是“配置目录 + 会话 JSON + 外部命令”而不是改主程序

在常见安装方式里，Codex 的用户级数据主要落在用户主目录下，而不是项目目录里。这样做的好处是全局配置和认证信息可以跨项目复用，坏处是用户很难直观看到这些文件，出了问题也不知道去哪里排查。

开发 DSH 这类插件时，最稳妥的边界是三条：

• 只读取 Codex 写出的配置文件和会话数据。
• 只调用 Codex 对外提供的命令和标准输入输出。
• 把插件自己的产物写到独立目录，例如 ~/.dsh/，避免污染 Codex 原生目录。

之所以强调“不修改主程序”，是因为直接改安装目录里的二进制文件或内部脚本，会在 Codex 升级时被覆盖，也会让其他协作者无法复用你的插件。通过外部脚本读配置、做归档、生成模板，才是可维护的做法。这里说的“还原 Codex”，指的是交互体验、输出风格和操作习惯尽量贴近原生，而不是破解、修改或绕过 Codex 的限制。

1.2 常见目录结构与关键文件说明

不同操作系统的用户目录路径不同，但相对结构类似。下面是一个常见布局，落地时要以自己机器上的实际路径为准。

text复制~/.codex/
├── config.toml          # 主配置：模型、组织、模型提供方
├── auth.json            # 认证信息，敏感，不要提交到 Git
├── sessions/            # 会话记录目录
│   ├── 2025-01-01/      # 按日期或项目生成的子目录
│   │   └── abc123.json
│   └── ...
└── logs/                # 运行日志目录

其中 config.toml 是插件最需要关注的文件，因为大量“配置改了不生效”“模型不支持”“组织设置加载失败”的问题都出在这里。sessions/ 目录里的 JSON 文件则是会话归档功能的输入数据。

正因为这些文件路径和字段名在不同版本里可能有差异，插件写代码时不能写死绝对路径，应该优先从环境变量读取，再用用户目录做兜底。例如 CODEX_HOME 环境变量如果有值，就优先用它，否则回退到 ~/.codex。

1.3 插件的运行边界：只读配置、调用公开命令、写独立目录

一个成熟的管理插件应该把职责分清楚。归档功能只读会话数据，校验功能只读配置，模型切换功能只修改插件推荐的配置片段，而不会去改动 Codex 的认证文件。如果插件需要帮助用户生成新的配置文件，也应该先生成到 ~/.dsh/templates/，让用户确认后再覆盖。

这样做有三个直接好处：

• 插件出错时不会连累 Codex 本身无法启动。
• 用户可以在 ~/.dsh/ 里找到插件的产物，方便回滚和排查。
• 插件可以放心运行在 CI、定时任务或团队脚本里，不需要特殊权限。

2. 用 Python 搭一个不侵入 Codex 主程序的 DSH 插件骨架

这一章的目标是快速搭建一个最小可运行的 DSH 插件骨架。它不做复杂界面，而是通过命令行子命令完成归档和体检。

2.1 为什么选择 Python

Codex 本身是 Node 生态的产物，但插件不一定要用 Node 写。这里选择 Python，原因是处理 JSON、TOML、文件路径和命令行参数足够直接，而且大多数开发机默认具备 Python 3 环境。

重点在于版本：Python 3.11 开始内置 tomllib，可以直接解析 TOML 配置；如果仍然使用 Python 3.10 或更低版本，运行时需要安装 tomli 兼容包。为了避免插件在别人机器上直接报 ModuleNotFoundError，代码里要做兼容处理。

学习环境的插件可以只支持本机路径，但生产环境或团队共享的插件必须考虑：

• 用户机器是 Windows、macOS 还是 Linux，路径分隔符不同。
• 用户是否设置了 CODEX_HOME，不能一律假设是 ~/.codex。
• Python 版本不一致时，是升级 Python 还是在插件里做依赖兼容。

2.2 项目目录结构

DSH 插件建议采用下面的目录结构，保持命令和实现分离。

text复制dsh-plugin/
├── dsh.py                 # 入口命令
├── requirements.txt       # 依赖：Python 3.10 以下需要 tomli
├── commands/
│   ├── __init__.py
│   ├── archive.py         # 会话归档
│   └── doctor.py          # 配置体检
└── config/
    └── dsh.json           # 插件自身配置：路径、保留天数等

dsh.py 只负责解析子命令和分派逻辑，commands/ 下的每个模块只做一件事。这样后续要加“配置切换”“统计报表”时，不需要重写入口。

2.3 命令入口与最小运行闭环

dsh.py 最小实现如下：

python复制import argparse
import sys
from commands import archive, doctor

def main():
    parser = argparse.ArgumentParser(prog="dsh")
    subparsers = parser.add_subparsers(dest="command", required=True)

    doctor_parser = subparsers.add_parser("doctor", help="检查 Codex 配置")
    doctor_parser.add_argument("--config", help="指定 config.toml 路径")

    archive_parser = subparsers.add_parser("archive", help="归档会话历史")
    archive_parser.add_argument("--days", type=int, default=30, help="只处理最近 N 天")
    archive_parser.add_argument("--project", help="按项目关键字过滤")
    archive_parser.add_argument("--dry-run", action="store_true", help="只预览不复制")

    args = parser.parse_args()

    if args.command == "doctor":
        doctor.run(args)
    elif args.command == "archive":
        archive.run(args)

if __name__ == "__main__":
    sys.exit(main())

这里的关键是 --dry-run 参数。归档操作涉及文件复制，如果代码有 bug，很容易把用户原始会话目录弄乱。先提供预览模式，让用户看到“将要归档哪些文件”，确认无误后再真正执行，这是文件处理类插件的基本素养。

运行闭环很简单：

bash复制python dsh.py doctor --config ~/.codex/config.toml
python dsh.py archive --days 30 --dry-run
python dsh.py archive --days 30

只要能看到帮助信息、体检结果和归档预览，这个骨架就算跑通了。接下来的章节再逐个填充逻辑。

3. 先做两个最重要的插件能力：会话归档和配置体检

DSH 插件的基础功能不需要追求多，先把两个高价值动作做扎实：把散落的会话历史归档成按日期组织的目录，以及把配置里的未知字段和明显错误提前暴露出来。

3.1 会话归档：按日期和项目重排历史记录

Codex 的会话目录会随着使用时间变得越来越长，直接打开 JSON 文件翻找历史既不高效也容易看错。归档插件的思路是：读取会话 JSON 里的时间戳和关键字段，把文件复制到 ~/.dsh/archive/YYYY-MM-DD/ 下，还可以根据项目关键字再分一层。

这里不要直接移动原文件，而是复制。原因是原始目录是 Codex 自己维护的，移动后可能导致 Codex 无法找到历史会话。归档目录只作为备份和检索副本。

python复制import json
import shutil
from datetime import datetime
from pathlib import Path

def run(args):
    home = Path.home()
    source_dir = Path.home() / ".codex" / "sessions"
    target_root = Path.home() / ".dsh" / "archive"

    if not source_dir.exists():
        print("[DSH] 会话目录不存在，请检查 CODEX_HOME 路径")
        return

    files = list(source_dir.rglob("*.json"))
    print(f"[DSH] 找到 {len(files)} 个会话文件")

    for session_file in files:
        try:
            data = json.loads(session_file.read_text(encoding="utf-8"))
        except json.JSONDecodeError:
            print(f"[DSH] 跳过损坏文件: {session_file}")
            continue

        timestamp = data.get("timestamp", session_file.stat().st_mtime)
        if isinstance(timestamp, str):
            timestamp = datetime.fromisoformat(timestamp).timestamp()
        day = datetime.fromtimestamp(timestamp).strftime("%Y-%m-%d")

        project = data.get("project", "unknown")
        if args.project and args.project not in str(project):
            continue

        target_dir = target_root / day / project
        target_dir.mkdir(parents=True, exist_ok=True)
        target_file = target_dir / session_file.name

        if args.dry_run:
            print(f"[DSH] 预览归档: {session_file} -> {target_file}")
        else:
            shutil.copy2(session_file, target_file)

    if args.dry_run:
        print("[DSH] 以上为预览结果，未执行真实归档")

需要特别说明的是，会话 JSON 的字段结构不是一成不变的。有的版本里时间字段叫 timestamp，有的版本里可能用 created_at，项目字段也可能不存在。上面代码把所有字段都做了兜底，读取失败就跳过，避免单一字段缺失导致整个归档流程中断。实际项目里，建议在 config/dsh.json 中增加一个字段映射配置，让用户可以根据自己的版本调整。

3.2 配置体检：识别未知配置项和常见拼写错误

Codex 在读取配置文件时，如果遇到不认识的设置项，通常只会提示一条类似 unrecognized configuration setting 的警告，然后继续启动。用户很容易忽略，直到发现某个配置不生效才回头排查。DSH 插件的 doctor 命令要做的事，就是把这些警告前置。

python复制import os
import sys
import tomllib

KNOWN_KEYS = {
    "model",
    "model_provider",
    "model_providers",
    "organization",
    "org_id",
    "api_base_url",
    "env_key",
    "temperature",
    "top_p",
}

def run(args):
    config_path = args.config
    if not config_path:
        config_path = os.path.join(Path.home(), ".codex", "config.toml")

    if not os.path.exists(config_path):
        print(f"[DSH] 未找到配置文件: {config_path}")
        sys.exit(1)

    with open(config_path, "rb") as f:
        config = tomllib.load(f)

    for key in config:
        if key not in KNOWN_KEYS:
            print(f"[DSH] 发现未知配置项: {key}")

    model = config.get("model")
    provider = config.get("model_provider")

    if model:
        print(f"[DSH] 当前模型: {model}")
    if provider:
        print(f"[DSH] 当前提供方: {provider}")

    provider_config = config.get("model_providers", {}).get(provider, {})
    base_url = provider_config.get("base_url", "")
    if base_url and not base_url.endswith("/v1"):
        print(f"[DSH] warning: base_url 可能不是标准路径: {base_url}")

    print("[DSH] 配置体检完成")

这段代码的价值不在于它覆盖了多少字段，而在于把“模糊的警告”变成“明确的输出”。当你看到 codex is ignoring 1 unrecognized configuration setting 这类提示时，运行 python dsh.py doctor，插件会把未知字段列出来，省去一段段翻 TOML 的功夫。

3.3 参数说明和运行输出预期

归档命令和体检命令都需要一些参数，参数的默认值要兼顾安全和易用。

预期运行结果大致如下：

text复制[DSH] 找到 128 个会话文件
[DSH] 预览归档: ~/.codex/sessions/2025-06-01/demo.json -> ~/.dsh/archive/2025-06-01/demo/
[DSH] 以上为预览结果，未执行真实归档

如果归档过程中有 JSON 文件损坏，输出里会明确出现“跳过损坏文件”，而不是整个命令失败。这种宽容式处理非常必要，因为会话文件由程序自动写入，总会出现异常中断留半截的情况。

注意：不要只验证插件能启动，还要验证它遇到空目录、损坏 JSON、缺少字段时的行为。归档工具最重要的特性不是快，而是永远不会弄丢或弄乱原始数据。

4. 接入 DeepSeek 等兼容模型时，配置怎么写、模型不支持怎么查

Codex 的核心是模型交互，因此 DSH 插件绕不开模型配置问题。很多用户实际需要的是把默认模型切换成其他兼容服务，或者在多个服务之间切换，这时最容易碰到“模型不支持”“请求失败”“组织设置加载失败”等问题。

4.1 model provider 配置结构

在兼容 OpenAI 接口的服务上，常见配置方式是先在 config.toml 里声明一个 provider，再切换全局模型。下面是一个接入 DeepSeek 的配置示例：

toml复制model = "deepseek-chat"
model_provider = "deepseek"

[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com/v1"
env_key = "DEEPSEEK_API_KEY"

这段配置的含义是：Codex 使用名为 deepseek 的提供方，请求地址是 https://api.deepseek.com/v1，密钥从环境变量 DEEPSEEK_API_KEY 读取。这种方式比把密钥直接写在配置里安全，也方便在团队中分发配置模板。

实际使用前，需要确认两点：

• 当前 Codex 版本对 provider 配置字段的完整要求，不同版本字段名可能不同。
• 目标模型服务商是否提供 OpenAI 兼容接口，以及 base_url 是否要求以 /v1 结尾。

bash复制export DEEPSEEK_API_KEY="your_key_here"

Windows PowerShell 下用：

powershell复制$env:DEEPSEEK_API_KEY="your_key_here"

设置好环境变量后，再运行 python dsh.py doctor，如果插件输出了当前模型为 deepseek-chat、提供方为 deepseek，说明配置文件已经被正确读取。

4.2 “model is not supported”类报错的排查链路

搜索材料里经常出现类似 the 'gpt-5.6-sol' model is not supported when using codex with a chatgpt account 的报错。这类报错的本质是：配置里请求的模型 ID 与当前账号、服务商或环境不匹配。遇到这种报错，不要先怀疑 Codex 坏了，应该按顺序排查。

排查步骤：

1. 查看当前配置里的模型 ID：python dsh.py doctor 输出 model 字段。
2. 确认该模型 ID 是否属于当前服务商。例如把 model 配置成某个不存在的模型名称，服务端就会拒绝。
3. 确认 model_provider 是否指向了正确的提供方。只改 model 不改 model_provider，请求可能仍然发给默认提供方。
4. 确认对应 provider 的 env_key 环境变量是否已经设置。环境变量缺失时，认证信息读取失败也会被误报成模型问题。
5. 确认配置修改后是否重启了终端会话或 Codex 进程。很多配置只在进程启动时读取一次。

下面是这段排查逻辑的表格：

4.3 切换模型后的验证方法

切换模型后，最快的验证方式是发起一次极小请求，问一句“用一句话介绍你自己”，然后观察返回内容以及是否出现报错。如果 DSH 插件提供了 doctor 命令，还可以把模型、提供方、base_url 一并打印出来，作为切换前后的对照。

验证清单：

• doctor 输出是否显示新模型。
• base_url 是否以 /v1 结尾。
• 环境变量是否能被当前终端读取。
• 请求是否成功返回，而不是出现认证、连接或模型不支持错误。
• 确认配置没有出现 unrecognized configuration setting 警告。

5. 安装启动阶段最常见的四类问题，按日志顺序排查

DSH 插件本身安装不难，但安装 Codex 和相关依赖时，很多问题会反复出现。这一章把高频问题归成四类，便于按顺序排查。

5.1 依赖安装顺序与版本核对

插件或命令行工具安装失败，很多时候不是工具本身有问题，而是前置依赖不对。常见依赖包括 Git、Python 运行时、Node.js 运行时。安装前先统一版本，比对顺序如下：

bash复制git --version
python --version
node --version

如果 Python 低于 3.11，插件里用到 tomllib 时会直接报错。解决方案有两种：升级 Python，或者在依赖列表中加入 tomli 并在代码中做兼容导入。

python复制try:
    import tomllib
except ModuleNotFoundError:
    import tomli as tomllib

安装顺序建议是先确认基础环境，再装 Codex，最后安装 DSH 插件和它的 Python 依赖。顺序反了，排错时容易分不清是哪一层的问题。

5.2 登录、组织和账号读不到时的处理

“无法加载组织设置”“登录不上”是高频问题。遇到这类提示，优先看认证文件是否存在且有效。常见 Codex 安装目录下会有 auth.json，里面保存了登录凭证。用户登录状态过期、org_id 配置错误或网络不通都会导致组织设置加载失败。

排查顺序：

1. 确认认证文件存在，且不是空文件。
2. 确认配置里的组织 ID 与当前账号匹配。
3. 确认网络能正常访问模型服务地址。
4. 重新登录并重启 Codex。

这里有一个很容易被忽略的点：如果插件或脚本会读取并重写 config.toml，不要不小心把 org_id 或 organization 字段删掉。配置体检工具可以把这两个字段列入必查列表，发现缺失时输出明确提示。

5.3 安装卡死和启动无响应的处理

在 Windows 环境中，安装卡死经常表现为安装进度条长时间不动或安装器无响应。常见原因有：安装位置目录权限不足、安全软件拦截写文件、磁盘空间不足、旧版本残留导致冲突、下载文件不完整。

处理建议按轻到重排序：

1. 关闭正在运行的 Codex 进程，再重新安装。
2. 以当前用户权限重新运行安装程序，不要用管理员权限强行覆盖。
3. 清理旧版本缓存和临时目录。
4. 检查日志，找到卡住的具体文件写入操作。
5. 如果图形安装器反复失败，改用命令行方式安装，便于看到完整输出。

如果启动后没有任何日志，优先查看日志目录。Codex 这类工具通常会把运行日志写到用户目录下的 logs/ 中。启动无响应不要反复点启动按钮，先看日志最后几行，确认是配置错误、认证失败还是网络超时。

注意：生产环境安装插件不只是“装上能跑”，还要考虑升级、卸载、日志留存和对 Codex 主目录的权限控制。最忌把所有文件都堆在 Codex 目录里，导致升级时被覆盖或清理。

6. 插件开发中容易踩的坑、发布前检查清单和下一步扩展

DSH 插件做到能跑只是开始。真正决定插件能不能长期使用的，是它面对异常情况时的表现，以及发布前有没有做完整检查。

6.1 实际开发 DSH 插件时容易踩的坑

第一个坑是直接把插件文件放进 ~/.codex 目录。这样虽然方便，但 Codex 升级、清理缓存或用户切换目录时，插件会被误删或失去作用。正确做法是把插件放在独立目录，通过命令或配置指向 ~/.codex 中的文件。

第二个坑是手写 TOML 时层级缩进错误。TOML 用缩进表达层级，model_providers 和 [model_providers.deepseek] 必须严格对齐。很多用户复制配置时搞错了缩进，Codex 只提示一个模糊的 unrecognized configuration setting，排查起来非常费劲。

第三个坑是假设会话 JSON 字段固定不变。实际使用中，不同版本可能调整字段名、嵌套结构和时间格式。健壮的插件必须容忍字段缺失、类型不一致和文件损坏。

第四个坑是切换模型时只改 model 字段。模型 ID 和 provider 是两个独立问题，只改一个不会生效。错误写法是只写 model = "deepseek-chat"，却不设置 model_provider = "deepseek"，请求仍然走原提供方。

第五个坑是把 API key 直接写进配置文件或提交到 Git。配置模板应该使用 env_key 或外部环境变量，并在 .gitignore 中排除认证文件和含敏感信息的配置文件。

6.2 发布前检查清单

插件准备发布给其他人使用前，建议对照下面的清单逐项检查。

这份清单既适用于自用，也适用于团队内部共享。发布前跑一遍，可以避免大多数低级问题。

6.3 从归档走向自动化的扩展方向

DSH 插件完成归档和体检之后，可以继续向三个方向扩展。

方向一是增量归档。当前示例每次全量扫描会话目录，数据量变大后效率会下降。可以增加一个 .dsh/index.json 记录已归档文件的哈希，只处理新增和变更文件。

方向二是配置切换。插件可以把多套 provider 配置做成模板，执行 python dsh.py switch deepseek 时自动生成对应的 config.toml 片段，并交给用户确认后替换。这样既能管理多账号，也不会因为误改配置导致 Codex 无法启动。

方向三是统计报表。基于归档后的会话 JSON，可以统计每天使用次数、项目分布、请求时长变化。这些数据对优化提示词、评估模型成本有实际价值，也是把“管理插件”升级成“工作流插件”的必经之路。

回到最开始的问题：DSH 这类插件的价值，不是让 Codex 变成一个完全不同的工具，而是把本地管理工作变得可追踪、可恢复、可复用。先理解它把数据放在哪里，再围绕归档和体检做好基础能力，然后逐步处理模型切换和安装排错，这套思路比单独记几个命令更可靠。如果你正在维护自己的 Codex 配置，建议今天就把 doctor 和 archive --dry-run 跑起来，先看清楚本机现状，再决定要优化什么。