设置文件

Warp 将您的偏好设置存储在一个名为 settings.toml 的纯文本文件中。您可以直接在任何文本编辑器中编辑它，将其签入版本控制，或使用脚本生成它。更改会立即生效——无需重新启动。

设置文件与图形设置面板协同工作。您在任一位置所做的更改都会反映在另一位置。

主要功能

• 热重载 — Warp 监视 settings.toml 的更改，并在您保存文件时立即应用它们。
• 错误恢复 — 如果文件包含无效的 TOML 或无法识别的值，Warp 会显示警告横幅，并对受影响的设置回退到默认值。修复文件后，横幅会自动清除。
• 自动迁移 — 当您升级到包含设置文件的 Warp 版本时，Warp 会自动将您现有的偏好设置迁移到 settings.toml 中。
• 与设置UI的双向同步 — 在 Warp 设置面板中（macOS 上为 ⌘+,，Linux/Windows 上为 Ctrl+,）所做的更改会写入 settings.toml，手动编辑该文件也会反映在面板中。
• 代理驱动的编辑 — 使用自然语言（例如，“将我的字体大小增加到 16”）请求 Warp 的代理为您更改设置。捆绑的 modify-settings 技能会自动处理文件更新。

打开您的设置文件

有几种方法可以打开 settings.toml：

• 在 Warp 应用中，前往 设置，然后点击面板底部的 打开设置文件。
• 直接在任何编辑器中打开适用于您平台和 Warp 发布通道的下方路径中的文件。

文件位置

根据您的平台和 Warp 发布通道，settings.toml 位于：

• macOS
  • 稳定版 — ~/.warp/settings.toml
  • 预览版 — ~/.warp-preview/settings.toml
• Linux
  • 稳定版 — ~/.config/warp-terminal/settings.toml
  • 预览版 — ~/.config/warp-terminal-preview/settings.toml
• Windows
  • 稳定版 — %LOCALAPPDATA%\warp\Warp\config\settings.toml
  • 预览版 — %LOCALAPPDATA%\warp\WarpPreview\config\settings.toml

有关所有其他 Warp 文件（主题、标签配置、键绑定、日志、本地数据库等）的位置，请参阅文件和文件夹位置。

设置文件格式

该文件使用 TOML v1.1 语法。设置被组织成节（TOML 表），这些节将相关选项分组——例如，[appearance.text] 包含字体设置，[agents.profiles] 包含代理权限设置。

以下是一个显示结构的最小示例：

# Appearance settings
[appearance.text]
font_name = "JetBrains Mono"
font_size = 14.0
line_height_ratio = 1.3

[appearance.themes]
theme = "dracula"

# Terminal behavior
[terminal.input]
syntax_highlighting = true
honor_ps1 = false

# Agent permissions
[agents.profiles]
agent_mode_execute_readonly_commands = true

节如何映射到TOML表

设置文件中的每个节都对应一个方括号中的 TOML 表头。子节使用点分隔路径：

• [general] — 顶层通用设置，如会话恢复和标签页位置
• [appearance] — 视觉设置，包含子节，如 [appearance.text]、[appearance.themes]、[appearance.cursor]
• [agents] — 代理和AI设置，包含子节，如 [agents.profiles]、[agents.warp_agent.input]
• [terminal] — 终端行为设置，包含子节，如 [terminal.input]

有关所有可用设置的完整列表，请参阅所有设置参考。

设置如何应用

设置面板与文件之间的关系

Warp 设置面板（macOS 上为 ⌘+,，Linux/Windows 上为 Ctrl+,）和 settings.toml 代表相同的底层配置。在设置面板中更改一个开关会将其新值写入 settings.toml。手动编辑 settings.toml 会在下次读取文件时更新设置面板。

错误横幅

当 settings.toml 包含错误时，Warp 会在工作区顶部显示一个可关闭的警告横幅。该横幅包含一个打开设置文件按钮，您可以直接跳转到文件并解决问题。保存更正后的文件后，横幅会自动消失。

常见配置

更改主题和字体

[appearance.themes]
theme = "cyber_wave"

[appearance.text]
font_name = "Fira Code"
font_size = 15.0
ligature_rendering_enabled = true
font_weight = "normal"

配置代理权限

[agents.profiles]
agent_mode_coding_permissions = "always_allow_reading"
agent_mode_execute_readonly_commands = true
agent_mode_command_execution_allowlist = [
  "cat(\\s.*)?",
  "echo(\\s.*)?",
  "find .*",
  "grep(\\s.*)?",
  "ls(\\s.*)?",
  "which .*",
]

启用Vim键绑定

[text_editing]
vim_mode_enabled = true
vim_status_bar = true

从旧设置迁移

当您升级到包含设置文件的 Warp 版本时，Warp 会自动将您现有的偏好设置迁移到 settings.toml 中。无需任何操作——您的自定义设置将保留，并且该文件将成为所有设置的单一事实来源。

故障排除

“您的设置文件包含错误”横幅

当 settings.toml 包含无效的 TOML 语法或无法识别的值时，会显示此横幅。点击横幅中的 打开设置文件 以打开文件并查找：

• 引号缺失 — 字符串值必须用双引号括起来：font_name = "Hack"，而不是 font_name = Hack。
• 方括号缺失 — 节标题需要方括号：[appearance.text]。
• 值类型错误 — 检查数字是否为数字（font_size = 13.0），布尔值是否为 true/false，以及枚举值是否为有效字符串。

重置为默认值

删除 settings.toml（或重命名它）并重新启动 Warp。Warp 会对所有设置回退到内置默认值。下次您通过设置面板更改设置时，该文件将重新创建。

# Uncomment the two lines that match your platform and Warp release
# channel, then run them to back up and delete settings.toml.

# Stable (macOS)
# cp ~/.warp/settings.toml ~/.warp/settings.toml.bak
# rm ~/.warp/settings.toml

# Stable (Linux)
# cp ~/.config/warp-terminal/settings.toml ~/.config/warp-terminal/settings.toml.bak
# rm ~/.config/warp-terminal/settings.toml

# Preview (macOS)
# cp ~/.warp-preview/settings.toml ~/.warp-preview/settings.toml.bak
# rm ~/.warp-preview/settings.toml

# Preview (Linux)
# cp ~/.config/warp-terminal-preview/settings.toml ~/.config/warp-terminal-preview/settings.toml.bak
# rm ~/.config/warp-terminal-preview/settings.toml

设置未应用

确认您正在编辑适用于您的平台和 Warp 发布通道的正确文件（请参阅上方的文件位置）。如果您运行多个 Warp 发布通道，每个通道都有其自己的设置目录。

相关页面

• 所有设置参考 — 包含每个可用设置的描述、类型和默认值的完整列表
• 文件和文件夹位置 — Warp 在 macOS、Windows 和 Linux 上存储所有配置、数据和状态文件的位置
• 自定义 Warp — 所有自定义选项概述
• 自定义主题 — 创建并加载自定义 YAML 或 Base16 主题
• 键盘快捷键 — 自定义键绑定
• 设置同步 (Beta) — 跨机器同步设置