配置

宿主设置在 ~/.crystal/config.json。提供商和模型定义在 ~/.crystal/providers.json。即使该文件缺失，内置的 DeepSeek 和 OpenAI 目录仍然可用。你的定义覆盖它。改完文件后重启。在 TUI 中编辑提供商定义尚不可用。不读取 <workspace>/.crystal/config.json。

providers.json	读取什么
存在	操作者目录。忽略旧的 config.json.providers
缺失	旧字段，包括 apiKey 和 apiKeyEnvironment

保存偏好不会改写已存在的 providers.json。该文件缺失且 config.json 仍有 providers 对象时，保存把它复制到 providers.json，并保留原字段。之后的编辑属于 providers.json。

顶层字段：

字段	含义
provider	活动提供商名称
model	活动模型 id（必须存在于该提供商下）
approval	default、edit、review、audit 或 full
approvalModel	可选审查者。enabled、provider、model，以及可选的 thinkingEffort。省略表示关闭。enabled: false 保留已存储的提供商、模型和档位但不使用
compactionModel	可选摘要者。enabled、provider、model，以及可选的 thinkingEffort（default、off，或该模型列出的档位）。省略表示关闭，摘要使用会话模型。enabled: false 保留已存储的提供商、模型和档位但不使用。模型不需要 imageInput。打开它需要目录中的模型；缺少凭据或未知模型会被拒绝，已保存的值保持不变
imageModel	describe_image 的可选视觉模型。provider、model，以及可选的 thinkingEffort。省略表示该工具不存在。模型必须有 imageInput。思考能力留在模型条目上
thinkingEffort	宿主思考档位：default、off（none 相同），或模型列出的 effort token。max 和 maximum 是不同的 token。Token 以小写存储并原样发送
contextSelections	已保存的本地上下文预算，嵌套映射，例如 {"openai": {"my-model": 272000}}。/context 写入此映射；旧的扁平形式 {"openai/my-model": 272000} 仍可读取，并在下次保存时改写为嵌套。缺失或不支持的选择使用该模型最低的已声明预算
tierSelections	已保存的服务层级 token，嵌套映射，例如 {"openai": {"my-model": "flex"}}。/tier 写入此映射。缺失的选择，或模型不再列出的 token，会省略该字段
speedSelections	已保存的速度 token，形状与 tierSelections 相同。/speed 写入此映射
skills	启用 skill 工具和可用技能引导（默认 true）
ruleFiles	OpenCode 兼容的规则文件。global 和 project 各自默认为 true，关闭前省略。不影响 instructions.md 或 .crystal.md
externalTools	启用操作者工具集发现（默认 true）
plugins	启用操作者插件发现（默认 true）
workspaceTrust	目录中第一次交互会话前询问（默认 true；打开时省略）。不适用于 crystal run
externalToolApproval	工具集作者声明的按来源信任：home 和 project，各自为 author 或 host（默认 Home 为 author，Project 为 host）
estimatedTokens	在 Thinking 和 Writing 期间于进度行显示每 token 四字符的活动估计（默认 false）
verboseResults	成功结果面板的父开关（默认 true；打开时省略）。关闭会隐藏屏幕上已有的每个成功结果，包括 read、search、skill、edit、write、bash 和后台 bash。不隐藏 Tool 卡片；那些跟随 verboseCalls。失败保持。此开关关闭时，verboseTools 和 verboseCommands 不绘制结果。crystal run 不读取它
verboseCalls	显示 Tool 卡片（默认 true；打开时省略）。关闭会隐藏屏幕上已有的每张 Tool 卡片：read、search、edit、write、bash、后台 bash，以及 Apply Patch 等外部工具。成功和失败结果保持。独立于 verboseResults、verboseTools 和 verboseCommands。crystal run 不读取它
verboseTools	verboseResults 打开时，显示 read、search 和 skill 结果面板（默认 true；打开时省略）。Edit 和 write 结果保持。verboseResults 关闭时没有可见效果
verboseCommands	verboseResults 打开时，显示 bash、bash_start、bash_status、bash_logs 和 bash_stop 的完整输出（默认 true；打开时省略）。关闭时保留隐藏行提示和最后一行。verboseResults 关闭时没有可见效果
verboseApprovals	显示策略和授权自动放行卡片（默认 true；打开时省略）。关闭会隐藏屏幕上已有的那些卡片。审查允许卡片跟随 verboseReview。询问覆盖层保持
verboseReview	显示审查允许卡片（默认 true；打开时省略）。关闭会隐藏屏幕上已有的那些卡片，包括 Outcome 和理由。独立于 verboseApprovals。询问覆盖层、审查者 Deny 文本和 crystal run 保持
verboseThinking	在交互记录中显示 Thinking 面板（默认 true；打开时省略）。关闭会隐藏活动和已恢复的卡片。档位、进度行和导出保持。crystal run --show-thinking 是分开的
exportDirectory	导出根：省略或 home 表示 {home}/exports，workspace 表示 <workspace>/.crystal/exports，或任何绝对/~ 路径
customStatusLine	启用有序的自定义状态行（默认 false；现有自适应状态行仍是默认）
statusLine	仅在启用 customStatusLine 时使用的有序自定义字段。加载时检查内置名称。额外名称在匹配插件字段名时保留，即使该插件尚未加载
compactionThreshold	触发压缩的所选上下文预算比例（大于 0，至多 1；默认 0.8）
showCompactionSummary	手动 /compact 之后打印摘要（默认 true；打开时省略）。/compact summary 切换它；on 或 off 设置它
showAutomaticCompactionSummary	自动压缩之后打印同一摘要（默认 false；关闭时省略）。/compact auto 切换它（automatic 相同）；on 或 off 设置它。不改变 /compact
microCompaction	每次模型调用前可选地移除旧的成功工具结果。省略表示关闭。对象含 enabled（默认 false）、protectTurns（至少 1，默认 2）、protectTokens（非负，默认 40000）和 minimumTokens（非负，默认 20000）。无效值会停止启动。/compact micro 切换它；on 或 off 设置它。不总结
bashTimeoutSeconds	内置 bash 的每命令超时。省略保持 600 秒。至多 4,294,967 的正整数替换它。null 或 "unlimited" 禁用该计时器；取消回合仍会停止命令
backgroundBashTimeoutSeconds	bash_start 后台任务超时。省略保持 10800 秒（3 小时）。至多 4,294,967 的正整数替换它。null 或 "unlimited" 禁用该计时器；bash_stop 和会话关闭仍会停止任务
retry	工作回合和压缩的重试策略。对象含 enabled（默认 true；false 禁用重试）、maximumRetries（0–100，默认 5）、initialDelaySeconds（0–3600，默认 2）、backoffFactor（1–100，默认 2）、jitterFactor（0–1，默认 0.25）和 maximumDelaySeconds（0–86400，默认 30；没有 Retry-After 时的退避上限）。无效值会停止启动。工作重试发布 RetryScheduled
approvalRetry	Review 和 Audit 审批审查者的同一对象形状。独立于 retry。审查者重试是静默的；重试耗尽后回退到你的审批提示

在 providers.json 中添加命名端点和模型表，而不是在新的 config.json 配置中。

没有全局上下文窗口。未列出的模型不能被选择。

内置提供商

起步目录（与 providers.json 合并）：

提供商	协议	默认基 URI	起步模型
deepseek	deepseek	https://api.deepseek.com/	deepseek-flash、deepseek-v4-flash（兼容别名）、deepseek-v4-pro
openai	openai	https://api.openai.com/v1/	gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna
gemini	gemini	https://generativelanguage.googleapis.com/v1beta/	gemini-3.8-flash、gemini-3.1-pro-preview
ollama	ollama	http://localhost:11434/	qwen3:8b（选择前先拉取此模型）

内置 DeepSeek V4 模型以 effort low、high 和 max 启用思考。每个都有 1,000,000 token 的上下文窗口。起步 OpenAI 模型使用 400,000 token 窗口，除非你添加，否则不启用思考。Ollama 起步假设 4,096 token 的本地上下文。如果本地模型使用不同的上下文大小，在 providers.json 中设置该大小，并把 Ollama 模型配置成与之匹配。其他本地或云模型 ID 可以加在那里。自动从提供商获取模型列表信息已在计划中，此构建尚不可用。

Anthropic Messages 也是内置协议，但起步目录不为它提供条目，因此 Claude 模型来自 providers.json。见示例：添加 Anthropic（Claude）提供商。

提供商字段

字段	含义
protocol	deepseek、openai、responses、anthropic、gemini 或 ollama
baseUri	绝对 API 基 URI；适配器追加该协议的聊天路径
organization	openai 协议的可选 OpenAI 组织
project	openai 协议的可选 OpenAI 项目
replayReasoningContent	重放提供商推理内容（DeepSeek 总是重放它）；无法重放的推理保留其可读文本（助手文本，或协议的可读推理字段）
tokenLimit	Chat Completions 输出字段：max_tokens 或 max_completion_tokens（responses 和 anthropic 忽略）
apiKeyEnvironment	为此提供商首先检查的环境变量名
apiKey	字面值、{env:NAME} 或 {file:path}
requiresApiKey	缺失密钥是否为错误（默认 true，ollama 除外；未认证端点设为 false）
options	协议特定设置的可选对象。值是 JSON 字符串、数字或布尔。未知名称，以及不适用于 protocol 的名称，会使加载失败。temperature、topP 和 maxTokens 留在模型上
models	可选模型 id 表

提供商名称是字母、数字、连字符或下划线。

所有协议适配器发送常量 User-Agent: Crystal Code，没有版本。responses 用 Authorization: Bearer 认证；anthropic 使用 x-api-key 和 anthropic-version: 2023-06-01。两个适配器都使用直接 HTTP 和 JSON/SSE 处理；不需要提供商 SDK。Gemini 使用 x-goog-api-key 和原生 generateContent SSE。Ollama 使用原生 /api/chat JSON 行，未配置密钥时省略授权。对于 requiresApiKey: false 的提供商，显式提供商密钥或其特定环境变量仍会被使用；跳过 CRYSTAL_API_KEY。

支持 OpenAI 兼容 Chat Completions API 的 Amazon Bedrock 模型可以用 protocol: "openai"、区域性的 https://bedrock-runtime.REGION.amazonaws.com/openai/v1/ 基 URI 和 Bedrock API 密钥配置。此路径使用 bearer 认证。当前适配器不支持 IAM SigV4 凭据。

模型字段

字段	含义
contextWindow	必需的正数，模型最大上下文大小，单位 token。可选本地预算的上限；省略或留空 contextWindows 时用作唯一预算
contextWindows	可选的互不相同的正数 token 预算，不大于 contextWindow，例如 [272000, 1000000]。/context 循环这些值；最低值是初始预算。压缩和状态栏使用所选预算
temperature	可选，0 到 2
topP	可选，0 到 1
maxTokens	可选的正数输出 token 上限
thinking	模型是否接受推理提示
thinkingEfforts	此端点接受的 effort token。Token 以字母开头，然后只用字母、数字、下划线和连字符。max 和 maximum 是不同的 token。宿主以小写存储每个 token 并原样发送
thinkingCanDisable	是否接受 /thinking off（默认 true）。内置 Gemini 3 模型把此项设为 false
serviceTiers	此模型接受的服务层级 token。Token 以字母开头，然后只用字母、数字、下划线和连字符。宿主以小写存储每个 token，且不解释它。列出 default 时会发送它；它不表示未设置。空列表或省略表示此模型没有服务层级
speeds	此模型接受的速度 token，使用相同的 token 规则。端点接受时，fast 和 ultrafast 放在这里。空列表或省略表示此模型没有速度
imageInput	此模型是否可以接收图像（默认 false；所有内置协议都支持）
audioInput	声明的音频输入（默认 false）。存储并对插件可见。宿主不接受或发送音频
videoInput	声明的视频输入（默认 false）。存储并对插件可见。宿主不接受或发送视频

audioInput 和 videoInput 只记录该声明。Crystal Code 存储它们并展示给插件。它不附加、粘贴、持久化或发送音频或视频，这些标志也不注册多模态工具。imageInput 仍是允许图像输入的唯一标志。服务层级和速度只在活动模型列出所选 token 时发送。宿主不选择 JSON 字段，也不把响应与请求比较。Chat Completions 和 OpenAI Responses 把一个集合槽写入 service_tier，并在创建客户端时、保存选择之前，拒绝两者同时出现。Anthropic Messages 分别写入 service_tier 和 speed。DeepSeek、Gemini 和 Ollama 在创建客户端时拒绝任一槽。协议无法发送的已保存组合会在启动时失败。不使用端点地址来决定。

Gemini 和 Ollama 原生适配器接受用户消息中的内联图像。工具图像发送在 Gemini 的 functionResponse 部分和 Ollama 工具消息的 images 数组上。Gemini 工具图像需要接受多模态函数响应的模型。

thinkingEffort 是宿主设置，不是模型字段。更换模型从不失败：模型不支持思考时，请求省略推理提示；已存储的档位不在该模型列表中时，请求使用提供商默认值，已存储的选择不变。宿主以小写存储列出的 token 并转发该文本。适配器原样发送 token。max 和 maximum 是不同的 token。openai 和 responses 也用于 OpenRouter 等第三方网关，因此目录值不会被重命名为 xhigh。只在该端点接受该拼写时列出 xhigh、max 或 maximum。Gemini 3 把 token 大写为 thinkingLevel。Gemini 2.5 把 minimal、low、medium 和 high 映射为思考预算，并拒绝任何其他 token。思考打开时，Anthropic 请求摘要后的思考文本，除非该端点把 options.thinkingDisplay 设为 omitted。空的 thinkingEfforts 列表只表示开/关。thinkingCanDisable 为 false 时，档位中不包括 Off。已存储的 Off 选择使用提供商默认值，状态栏显示 Think Default。

示例：添加 OpenAI 兼容提供商

把此条目加到 ~/.crystal/providers.json。把秘密留在此文件之外。把它写在 ~/.crystal/credentials.json 的 openrouter 下。

{
  "openrouter": {
    "protocol": "openai",
    "baseUri": "https://openrouter.ai/api/v1/",
    "replayReasoningContent": true,
    "tokenLimit": "max_tokens",
    "models": {
      "anthropic/claude-sonnet-4": {
        "contextWindow": 200000,
        "temperature": 0.2,
        "maxTokens": 8192,
        "thinking": true,
        "thinkingEfforts": ["low", "medium", "high"]
      }
    }
  }
}

进程环境设置了 OPENROUTER_API_KEY 时，它覆盖该文件。编辑 providers.json 后重启。用 /model openrouter anthropic/claude-sonnet-4 选择模型，或在 config.json 中设置 provider 和 model。CLI --provider 和 --model 为一次运行覆盖该选择；/approval（包括 /approval model 和 /approval thinking）、/thinking、/context、/tier、/speed 和 /model 把它们的值写入 config.json。/context 把每个模型所选预算存在 contextSelections。/tier 和 /speed 把每个模型的 token 存在 tierSelections 和 speedSelections。

示例：添加 Anthropic（Claude）提供商

Anthropic Messages 是内置协议，但起步目录没有 Anthropic 条目，因此通过向 ~/.crystal/providers.json 添加一条来使用 Claude 模型。把密钥写在 ~/.crystal/credentials.json 的 anthropic 下。

{
  "anthropic": {
    "protocol": "anthropic",
    "baseUri": "https://api.anthropic.com/v1/",
    "models": {
      "claude-sonnet-4": {
        "contextWindow": 200000,
        "maxTokens": 8192,
        "thinking": true,
        "thinkingEfforts": ["low", "medium", "high"],
        "imageInput": true
      }
    }
  }
}

ANTHROPIC_API_KEY 为一次进程覆盖该文件。编辑 providers.json 后重启，然后用 /model anthropic claude-sonnet-4 选择模型，或在 config.json 中设置 provider 和 model。同一条目可以到达任何 Anthropic Messages 网关：更改 baseUri 和模型 id 以匹配它。在 thinkingEfforts 中列出端点 token，例如 max 或 xhigh。适配器原样发送该 token，并在思考打开时请求摘要后的思考文本。在此端点上把 options.thinkingDisplay 设为 omitted 可关闭 Anthropic 的 display 字段。summarized 是默认值，且不会写回。该名称只对 anthropic 协议有效。对拒绝采样参数的模型省略 temperature 和 topP。思考 token 计入 maxTokens。

示例：添加 OpenCode Zen 协议端点

一个网关可以把使用不同线路协议的模型归在一个提供商名称下。把此示例放进 providers.json。两个端点的密钥都属于 credentials.json 中的 opencode-zen。OPENCODE_ZEN_API_KEY 为一次进程覆盖该文件。

{
  "opencode-zen": [
    {
      "protocol": "responses",
      "baseUri": "https://opencode.ai/zen/v1/",
      "models": {
        "gpt-5.6-sol": {
          "contextWindow": 1050000,
          "maxTokens": 128000,
          "thinking": true,
          "thinkingEfforts": ["low", "medium", "high", "maximum"],
          "imageInput": true
        }
      }
    },
    {
      "protocol": "anthropic",
      "baseUri": "https://opencode.ai/zen/v1/",
      "models": {
        "claude-sonnet-5": {
          "contextWindow": 1000000,
          "maxTokens": 128000,
          "thinking": true,
          "thinkingEfforts": ["low", "medium", "high", "maximum"],
          "imageInput": true
        }
      }
    }
  ]
}

为 Chat Completions 模型向同一数组添加 protocol: "openai" 对象。每个模型 id 在一个提供商内必须唯一。列出的 effort 按所写发送。maximum 不会被改写为 xhigh 或 max。