dcode 如何在会话中切换模型并持久化模型配置？

dcode 如何在会话中切换模型并持久化模型配置？

【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents

在 deepagents 仓库的终端编码产品deepagents-code（命令名为dcode）里，模型不只是启动时定死的一次性选择：你既可以在一次交互会话中随时切换主模型、临时附加请求级参数，也可以把某个模型持久化为config.toml里的默认值，让后续会话直接沿用。本文针对这个场景给出操作路径：会话内切换、会话级参数、默认模型持久化，以及切换后如何确认生效。

前提是你已经能运行 dcode。文档给出的安装方式是（该命令会从官方脚本安装 dcode，请自行确认脚本来源后再执行）：

curl -LsSf https://langch.in/dcode | bash dcode

如果需要使用非内置的模型提供方，安装时可以用环境变量选择 extras（OpenAI、Anthropic、Gemini 默认已包含在安装器中）：

DEEPAGENTS_CODE_EXTRAS="nvidia,ollama" curl -LsSf https://langch.in/dcode | bash

用 /model 在会话中切换模型

/model是 dcode 的公开斜杠命令，描述为 "Switch models or edit model settings"（见 COMMANDS.md）。在 TUI 交互界面中直接输入/model会打开模型选择界面（Model Selector）；也可以用 Ctrl+N 在“显示名称”和“原始 spec”两种展示模式之间切换。

如果已经知道目标模型的 spec，可以直接指定而不经过选择界面：

/model provider:model-name

源码注释中的直接切换示例是/model claude-sonnet-4-5（app.py）。create_model会接受显式的限定 spec（provider:model），也可以对裸模型名自动检测 provider，都没有时回落到默认值（见 profiles-models.md）。切换会经过 allowlist 校验：被拒绝的模型不会复制已存储凭据到环境变量，也不会触发 provider profile 的副作用。

切换目标提供方需要凭据时，先通过/auth（别名/connect）连接并管理提供方凭据；各 provider 对应的 API key 环境变量名定义在 model_config.py 的PROVIDER_API_KEY_ENV中。

附加 --model-params：只对当前会话生效

/model支持在切换命令里附加请求级参数，参数是一个 JSON 对象（app.py 中的_extract_model_params_flag负责解析，非法 JSON 或未闭合括号会报对应错误）：

/model provider:model-name --model-params '{"key": "value"}'

这些参数按请求浅合并进model_settings，不会改动共享的模型对象（profiles-models.md）。注意它的生效范围仅限当前会话：源码对同时使用两个标志的报错文案是 "Model params are applied per-session, not persisted"（app.py）。

持久化默认模型：/model --default

会话内的直接切换不会写入配置文件；想跨会话固定某个模型，使用--default标志。命令用法（源码给出的提示文案）：

Usage: /model --default provider:model /model --default --clear

• /model --default provider:model：把该模型持久化为默认模型，同时切换当前会话使用的模型；
• /model --default --clear：清除已持久化的默认值。

从实现看，--default作用域持久化的是[models].default配置项，即 agent 自身运行的默认模型（app.py 的注释）。该配置写入用户级配置文件~/.deepagents/config.toml（该路径见 EXTENSIONS.md、THREAT_MODEL.md）。

约束：--model-params不能与--default组合使用，因为前者只按会话生效、不会持久化。

如何确认切换和持久化已生效

1. 当前会话：切换成功后，TUI 底部（footer）的/model区域显示当前模型；按 Ctrl+N 可在名称与原始 spec 之间切换展示，用于核对切到的具体是哪个 provider 的哪个模型。
2. 持久化值：/model --default的写入作用于默认配置路径，写入会刷新进程内的配置代（config generation），当前进程即可读到新值；如果你之后手动编辑了~/.deepagents/config.toml，在运行中的 TUI 里用/reload重新加载配置（config-layering.md 说明了对默认路径的写入与/reload都会推进配置代，解析失败的候选值会保留上一次可用快照并给出提示）。
3. 恢复会话时：每次父 agent 模型调用成功后，ConfigurableModelMiddleware会把解析出的模型 spec 和当次会话的运行时model_params写入 checkpoint，供恢复线程（如/threads恢复、-r续接）沿用（profiles-models.md 的 "Runtime switching and session state" 一节）。也就是说，会话内切换的模型在恢复同一线程时会被记住；但会话级--model-params属于运行时覆盖，新开线程不会继承它。

限制与回退行为

• 运行时通过runtime.context请求的模型替换走create_model解析；如果解析失败，默认回落到构造时的模型（设置strict_model_resolution时不回退），失败的那次调用不会产生 checkpoint 更新（profiles-models.md）。
• --model-params是会话级的，无法通过--default持久化；需要跨会话固定的参数应写入config.toml中 provider/model 层级的配置，生效优先级为：SDK provider profile 默认值 <config.toml的 provider/model 参数与凭据接线 <--model-params（profiles-models.md 的 "dcode construction and precedence"）。
• /model --default只能持久化主模型默认值；rubric/goal 评分模型（/rubric model、/goal model）的选择写入线程状态，文档中明确说明它们目前"没有持久化配置键"（app.py），不属于本场景的持久化范围。

下一步可以阅读 openwiki/concepts/profiles-models.md 了解 provider profile、harness profile 与重试预算在模型解析中的完整职责划分，以及 openwiki/workflows/run-dcode-session.md 了解线程恢复（resume）与 SQLite checkpoint 的行为细节。

【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents