> ## Documentation Index > Fetch the complete documentation index at: https://platform.stepfun.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # 配置文件 使用 `config.toml` 设置默认模型、权限、上下文压缩、界面和 MCP 服务器。临时启动参数不会自动改写配置文件。 ## 配置文件位置 | 级别 | 默认位置 | 作用 | | -- | ---------------------------- | ------------- | | 全局 | `~/.stepcode/config.toml` | 对所有项目生效 | | 项目 | `<项目>/.stepcode/config.toml` | 覆盖全局设置，需要项目信任 | 项目配置按字段覆盖全局配置：嵌套对象逐键合并，数组整体替换。代理、项目信任默认值等标为“仅全局”的配置不接受项目级覆盖。 全局配置在首次运行时自动创建。写入使用临时文件加改名的原子替换方式，并保留文件头注释块。TOML 不支持 `null`，不支持的表达会被剥离；取消可选值时应删除对应配置项。 ## 完整示例 以下是可作为起点的配置，不必一次填写所有可选项： ```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}} theme = "step-blue" defaultProvider = "step" defaultModel = "step-3.7-flash" permissionPreset = "bypass" autoResume = true [telemetry] enabled = true ``` 示例使用默认 Bypass 权限模式；需要逐项审批时，将 `permissionPreset` 改为 `"ask"`。 ## 顶层字段 ### 模型与思考 | 字段 | 说明 | | -------------------------------- | -------------------------------- | | `defaultProvider`、`defaultModel` | 默认平台和模型，可在 `/model` 中按 Ctrl+S 保存 | | `defaultThinkingLevel` | 默认思考级别 | | `modelThinkingLevels` | 按 `provider/modelId` 设置单个模型的思考级别 | | `thinkingBudgets` | 各思考级别的 token 预算 | | `hideThinkingBlock` | 隐藏思考块展示，默认 `false` | | `showCacheMissNotices` | 显示缓存未命中和压缩成本提示，默认 `false` | 客户端级别包括 `off`、`minimal`、`low`、`medium`、`high`、`xhigh` 和 `max`。模型能使用哪些级别，以及实际执行档位，取决于供应商和模型，不表示每个模型支持全部级别。 ### 界面 | 字段 | 默认值 | 说明 | | ------------------------ | ----------- | ----------------------------------------------------- | | `theme` | `step-blue` | 主题名称 | | `statusTips` | `true` | 显示工作行提示 | | `quietStartup` | `false` | 精简启动信息 | | `collapseChangelog` | `false` | 折叠更新日志 | | `doubleEscapeAction` | `tree` | 空输入框连续按 Esc 的动作：`tree`、`fork`、`none` | | `treeFilterMode` | `default` | `default`、`no-tools`、`user-only`、`labeled-only`、`all` | | `editorPaddingX` | `0` | 输入框水平内边距，范围 0–3 | | `outputPad` | `1` | 输出水平留白，取 0 或 1 | | `autocompleteMaxVisible` | `5` | 补全菜单显示数量，范围 3–20 | | `showHardwareCursor` | `false` | 显示终端硬件光标 | | `externalEditor` | 未设置 | 外部编辑器；未设置时依次读取 `VISUAL`、`EDITOR` | ### 会话、网络与 Shell | 字段 | 默认值 | 说明 | | ----------------------------- | --------------- | --------------------------------------------------------- | | `sessionDir` | 未设置 | 自定义会话存储目录 | | `transport` | `auto` | 模型传输方式：`auto`、`sse`、`websocket`、`websocket-cached`，需供应商支持 | | `steeringMode`、`followUpMode` | `one-at-a-time` | 流式期间消息投递方式 | | `httpProxy` | 未设置 | 出站代理，仅全局 | | `httpIdleTimeoutMs` | 300,000 | HTTP 空闲超时，单位毫秒；0 关闭 | | `websocketConnectTimeoutMs` | 15,000 | WebSocket 连接超时，单位毫秒；0 关闭 | ### Shell 与命令 | 字段 | 默认值 | 说明 | | -------------------- | --- | -------------------------------------------------------------- | | `shellPath` | 未设置 | 自定义 Shell 路径，支持 `~` 展开，适用于 Windows Cygwin 等场景 | | `shellCommandPrefix` | 未设置 | 在每条 Shell 命令前执行的内容，例如启用 alias | | `npmCommand` | 未设置 | npm 调用命令，argv 形式，例如 `["mise", "exec", "node@20", "--", "npm"]` | ### 项目与权限 | 字段 | 默认值 | 说明 | | --------------------- | -------- | ---------------------------------------- | | `permissionPreset` | `bypass` | `ask`、`read-only`、`bypass` 或 `autopilot` | | `defaultProjectTrust` | `ask` | 未信任项目的资源加载策略，仅全局 | | `enableAnalytics` | `false` | 可选使用分析开关，与反馈及其他服务设置分别管理 | 项目信任决定是否加载项目配置、扩展和资源，不是文件访问沙箱。 ## 分节配置 ```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}} [compaction] enabled = true reserveTokens = 16384 keepRecentTokens = 20000 contextProjection = "off" [branchSummary] reserveTokens = 16384 skipPrompt = false [retry] enabled = true maxRetries = 3 baseDelayMs = 2000 [thinkingBudgets] minimal = 1024 low = 4096 medium = 10240 high = 32768 [images] autoResize = true blockImages = false [terminal] showImages = true imageWidthCells = 60 clearOnShrink = false showTerminalProgress = false hyperlinks = "auto" images = "auto" trueColor = "auto" [markdown] codeBlockIndent = " " mermaid = "streaming" ``` * `[compaction]` 的 `enabled = false` 只关闭自动压缩；`reserveTokens` 为预留窗口，`keepRecentTokens` 为保留的近期消息量。 * `[branchSummary].skipPrompt = true` 时切换分支不再询问，默认不生成摘要。 * `[retry]` 的 `baseDelayMs = 2000` 采用指数退避，等待 2、4、8 秒。`provider.maxRetries` 保持默认 `0`；设为正值会使 SDK 重试先于 Step 处理配额耗尽错误，可能等待至配额重置。`provider.timeoutMs` 可设置单请求超时。 * `[thinkingBudgets]` 配置各思考级别的 token 预算。 * `[images].autoResize = true` 将图片压缩到 2,000 px 以内。 * `[images].blockImages = true` 阻止向模型发送图片；`[terminal].showImages` 只控制显示。 * `[terminal].images` 可指定 `kitty`、`iterm2`、`auto` 或 `false`，应与终端能力匹配。 * `[terminal].imageWidthCells` 是行内图片的终端列宽；`clearOnShrink` 控制收缩时清理空行；`showTerminalProgress` 控制 OSC 9;4 进度指示；`hyperlinks` 可取 `true`、`false` 或 `"auto"`。 * `[markdown].mermaid` 可取 `streaming`、`final` 或 `off`。 * `[warnings].anthropicExtraUsage` 默认 `true`，控制 Claude Pro/Max 额外用量提示。 ## MCP 服务器 在全局配置中添加服务器： ```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}} [mcp_servers.local-tools] command = "node" args = ["/absolute/path/to/mcp-server.js"] env = { LOG_LEVEL = "info" } startup_timeout_sec = 30 tool_timeout_sec = 300 ``` 将示例路径替换为实际服务器脚本。传输、鉴权和工具过滤见 [MCP](/docs/zh/step-code/customization/mcp)。 ## 工具与资源数组 | 字段 | 作用 | | ---------------------------------------- | ------------------------------------------------------------------------------- | | `defaultTools` | 内置工具白名单：`read`、`bash`、`powershell`、`edit`、`write`、`grep`、`find`、`ls`；空数组只保留扩展工具 | | `enabledModels` | Ctrl+P 循环选择的模型集合，支持 glob，例如 `["claude-*", "gpt-4o"]` | | `packages` | 安装和加载的资源包 | | `extensions`、`skills`、`prompts`、`themes` | 额外资源路径，支持 glob、排除和精确选择 | | `enableSkillCommands` | 将 Skills 注册为 `/skill:<名称>`，默认 `true` | 资源数组可填写文件或目录，支持 glob、`!` 排除以及 `+path` / `-path` 精确控制。全局相对路径按 `~/.stepcode/agent` 解析，项目相对路径按项目 `.stepcode` 解析。工具启动参数见[内置工具](/docs/zh/step-code/reference/tools)。 ## TUI 相关设置 | 字段 | 默认值 | 说明 | | ------------------------ | ------------ | ------------------------- | | `tuiMode` | `regular` | 可选实验性 `fullscreen` | | `fullscreenExitOutput` | `transcript` | 退出时显示转录，或选择 `resume-hint` | | `fullscreenScrollbar` | `auto` | 可选 `always`、`hidden` | | `fullscreenCopyOnSelect` | `true` | 选中即复制；关闭后可用 Ctrl+X | ## 废弃项 | 项目 | 说明 | | ------------------------------------------------- | ------------------------------- | | `~/.stepcode/agent/settings.json` | 已退役，不再读写；旧设置手动迁移到 `config.toml` | | `~/.stepcode/agent/step-settings.json` | 已退役 | | `~/.stepcode/agent/auth.json`、`agent/models.json` | 旧位置，已上提到 `~/.stepcode` 根目录 | | `.step-harness` | 已退役，不再写入；启动时仅读取旧凭据做一次性迁移 | ## 下一步 * [平台与模型](/docs/zh/step-code/configuration/models) * [环境变量](/docs/zh/step-code/configuration/environment) * [数据路径](/docs/zh/step-code/configuration/data-paths)