> ## Documentation Index
> Fetch the complete documentation index at: https://openidea.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# 设置项

> OpenIDEA 的设置保存在哪里、全局文件与项目文件如何合并、有哪些设置页，以及常用配置键和默认值。

大多数设置在设置窗口中修改最方便（参见[设置](https://openidea.sh/zh/guide/settings.md)）。本页介绍设置窗口背后的文件，方便你手动编辑、共享或用脚本处理。

## 文件与层级

设置由三层合并而成，后一层覆盖前一层：

1. 内置默认值。
2. 全局文件，即配置目录中的 `settings.toml`：
   * macOS：`~/Library/Application Support/ai.l0ng.openidea/settings.toml`
   * Windows：`%APPDATA%\ai.l0ng.openidea\settings.toml`
   * Linux：`~/.config/ai.l0ng.openidea/settings.toml`
3. 项目文件 `<项目>/.openidea/settings.toml`，在设置页选中 **此项目** 并保存时写入。

每个文件只保存与下层不同的值。表（table）按键逐个合并；而单个值或数组会整个替换下层的值（例如在项目中设置 `files.exclude`，会替换全局的整个列表）。

有些设置在项目文件中会被忽略：`mcpServer` 和导入的配色方案（`editor.customSchemes`）只能全局配置。项目信任状态永远不会从设置文件中读取。

## 文件格式

文件为 TOML 格式。键名使用下文列出的 camelCase 名称，并按节（section）分组：

```toml theme={null}
keymap = "intellij-windows"

[appearance]
theme = "dark"
zoom = 110

[editor]
fontFamily = "JetBrains Mono"
fontSize = 14

[files]
exclude = ["**/.git", "**/node_modules", "**/target", "**/dist"]
```

* OpenIDEA 写入文件时会保留你的注释和格式。
* 如果某个文件无法解析，或者某个值类型不对，整个文件都会被忽略，并在[日志](https://openidea.sh/zh/reference/data-directories.md)中记录警告。其他层仍然有效。
* 窗口加载设置时才会读取这些文件。手动编辑后，请重启 OpenIDEA（或重新打开项目）以确保生效。

## 设置页

| 分组 | 页面 |
| - | - |
| 外观与行为 | 外观；系统设置（语言和地区、日期格式、HTTP 代理、更新）；通知 |
| 按键映射 | 按键映射 |
| 编辑器 | 常规（自动导入、外观、痕迹导航、代码补全、代码折叠、编辑器标签页、装订区域图标、内联补全、后缀补全、富文本复制、智能键、粘滞行）；代码编辑；字体；配色方案；代码样式；检查；自然语言（拼写）；文件和代码模板；文件编码；实时模板；文件类型；嵌入提示；TODO；Vim |
| 插件 | 插件 |
| 版本控制 | 提交；确认；目录映射；问题导航；日志；搁置；Git；GitHub |
| 项目结构 | 项目结构 |
| 构建、执行、部署 | CMake；Gradle；Maven；控制台；调试器（数据视图、单步执行）；Python 调试器；运行/调试；运行目标；部署（选项） |
| 语言和框架 | 语言服务器；Go（构建标签、Go 模块）；Java；Markdown；Node.js；PHP；Python 解释器；Prettier；oxfmt；Ruff；Ruby；Rust；TypeScript；插件格式化工具 |
| 工具 | 智能体（聊天）；终端；保存时操作；外部工具；SSH 配置；MCP 服务器 |
| 安全 | 项目信任 |

已安装的插件可以添加设置页，带有可配置项的文件图标主题也会各自添加一页。插件的设置保存在 `[plugins.<plugin-id>]` 下。

## 常用配置键

### 顶层

| 键 | 默认值 | 说明 |
| - | - | - |
| `keymap` | macOS 上为 `intellij-macos`，其他系统为 `intellij-windows` | 当前快捷键方案：`intellij-macos`、`intellij-windows`、`vscode-macos`、`vscode-windows`、`eclipse-macos`、`eclipse-windows`，或自定义方案的 id。 |
| `keymapOverrides` | 空 | 在内置方案之上，操作 id → 快捷键列表；空列表表示解除绑定。参见[键位映射](https://openidea.sh/zh/guide/keymap.md)。 |
| `customKeymaps` | 空 | 你创建的方案：`name`、`parent`、`overrides`。 |

### `[general]`

除特别说明外，对应 设置 › 外观与行为 › 系统设置。

| 键 | 默认值 | 说明 |
| - | - | - |
| `reopenLastProject` | `true` | **启动时重新打开项目**。 |
| `openProjectIn` | `"ask"` | 已有项目打开时，**打开…** 把新项目放在哪里：`ask`（询问）、`new`（新窗口）、`same`（当前窗口）或 `attach`（附加到当前项目）。 |
| `defaultProjectDirectory` | `""` | 打开和克隆对话框的初始文件夹；为空时使用系统默认位置。 |
| `saveOnIdle` / `idleSeconds` | `false` / `15` | **IDE 空闲以下时长时保存文件**，单位为秒。 |
| `confirmExit` | `true` | **退出 IDE 前确认**。 |
| `closeWithoutWelcome` | `false` | **关闭窗口，而不是显示欢迎屏幕**。 |
| `closeTabsWithWindow` | `false` | **关闭窗口时关闭所有编辑器标签页**。 |
| `powerSaveMode` | `false` | **文件 › 省电模式**：不自动弹出提示，也不做后台高亮。 |
| `autoCheckUpdates` | `true` | **自动检查更新**（更新页）。 |
| `updateSource` | `"auto"` | **更新源**：`auto`、`github` 或 `cnb`。 |
| `dateFormat.overrideSystem` | `false` | **覆盖系统日期和时间格式**（日期格式页）。 |
| `dateFormat.pattern` | `"dd.MM.yyyy"` | 日期格式，可用 `dd`、`MM`、`MMM`、`yy`、`yyyy`。 |
| `dateFormat.use24Hour` | `true` | 使用 24 小时制。 |
| `dateFormat.pretty` | `true` | 显示“今天”“昨天”“5 分钟前”这类相对时间。 |

### `[appearance]`

除特别说明外，对应 设置 › 外观与行为 › 外观。

| 键 | 默认值 | 说明 |
| - | - | - |
| `theme` | `"light"` | `light`（Islands 浅色）、`dark`（Islands 深色）、`dark-hc`（高对比度）、`solarized-light`、`solarized-dark`、`one-light`、`one-dark`，或以 `plugin:<plugin-id>/<theme-id>` 表示的插件主题。 |
| `syncWithOs` | `false` | **与操作系统同步**。 |
| `preferredLightTheme` / `preferredDarkTheme` | `"light"` / `"dark"` | 与操作系统同步时使用的主题。 |
| `accent` | `"#3871e1"` | **强调色**。 |
| `fileIconTheme` | `""` | 插件提供的文件图标主题，写作 `<plugin-id>/<theme-id>`；为空时使用内置图标。 |
| `zoom` | `100` | **缩放**，百分比（50 到 300）。 |
| `useCustomFont` | `false` | **使用自定义字体：**，启用 `uiFontFamily` 和 `uiFontSize`。 |
| `uiFontFamily` / `uiFontSize` | `"Inter"` / `13` | 界面字体。 |
| `uiFontFallback` | `""` | **UI 备用字体**。 |
| `contrastScrollbars` | `false` | **使用对比度滚动条**。 |
| `redGreenVision` | `false` | **针对红绿色觉缺陷调整颜色**。 |
| `compactMode` | `false` | **紧凑模式**。 |
| `showMainToolbar` / `showStatusBar` | `true` / `true` | **显示主工具栏**、**显示状态栏**。 |
| `navigationBar` | `"statusBar"` | **导航栏**：`top`、`statusBar` 或 `hidden`。 |
| `mainMenuStyle` | `"hamburger"` | **主菜单**：`hamburger`（汉堡按钮）或 `merged`（与主工具栏合并）。 |
| `ideAntialiasing` / `editorAntialiasing` | `"greyscale"` | `subpixel`、`greyscale` 或 `none`。 |
| `locale` | `"en"` | **语言**（语言和地区页）：`en`、`zh`、`ko`、`fr`、`pl`、`pt`、`es`。 |

### `[editor]`

| 键 | 默认值 | 说明 |
| - | - | - |
| `fontFamily` / `fontSize` / `lineHeight` | `"JetBrains Mono"` / `13` / `22` | 编辑器 › 字体。 |
| `ligatures` | `false` | **启用连字**。 |
| `fallbackFont` | `""` | **备用字体**。 |
| `fontWeight` / `boldFontWeight` | `400` / `700` | **主字重**、**粗体字重**。 |
| `colorScheme` | `"theme-default"` | 编辑器配色方案；`theme-default` 跟随界面主题，也可以是主题 id 或导入的方案。 |
| `semanticHighlighting` | `false` | **语义高亮**（配色方案 › 语言默认值）。 |
| `rainbowBrackets` | `false` | **彩虹括号**（配色方案 › 语言默认值）。 |
| `tabSize` / `insertSpaces` | `4` / `true` | 默认制表符宽度，以及是否用空格缩进。 |
| `softWrap` | `true` | 对匹配 `general.softWrapFiles` 的文件软换行（默认 `*.md; *.txt; *.rst; *.adoc`）。 |
| `showWhitespace` | `false` | **显示空白**。 |
| `stickyScroll` | `true` | **滚动时显示粘滞行**。 |
| `inlayHints` | `true` | 显示嵌入提示。 |
| `formatOnSave` | `false` | 保存时重新格式化代码（工具 › 保存时操作）。 |

`[editor.general]`、`[editor.appearance]`、`[editor.completion]`、`[editor.tabs]`、`[editor.codeStyle]`、`[editor.encodings]` 等子表保存对应编辑器页面的选项。

### `[files]`

| 键 | 默认值 | 说明 |
| - | - | - |
| `autoSave` | `true` | **切换到其他应用程序或内置终端时保存文件**。 |
| `syncOnFocus` | `true` | **切换回 IDE 窗口时同步外部更改**。 |
| `exclude` | `["**/.git", "**/node_modules", "**/target"]` | **排除模式**（编辑器 › 文件类型）：在项目树中隐藏、搜索和索引时跳过的 glob 模式。 |
| `ignoredNames` | 内置列表 | **忽略文件和文件夹**：在各处都隐藏的名称，例如 `.DS_Store`。 |
| `trimTrailingWhitespace` | `true` | 保存时移除行尾空格。 |
| `ensureFinalNewline` | `true` | 保存的文件都以换行符结尾。 |
| `localHistoryDays` | `5` | **本地历史记录保留时长**，按有改动的天数计算。 |
| `localHistoryMaxMb` | `512` | **每个项目的最大本地历史记录大小**，单位 MB。 |

### `[notifications]`

| 键 | 默认值 | 说明 |
| - | - | - |
| `balloons` | `true` | **显示气球通知**。 |
| `sound` | `false` | **播放声音**。 |
| `groups.<group-id>.display` | `"balloon"` | 每个分组的弹出方式：`balloon`、`sticky` 或 `none`。 |
| `groups.<group-id>.log` | `true` | 同时在通知工具窗口中列出。 |

### `[terminal]`

对应 设置 › 工具 › 终端。

| 键 | 默认值 | 说明 |
| - | - | - |
| `shellPath` | `""` | shell 命令行；为空时启动登录 shell。 |
| `startDirectory` | `""` | 起始目录；为空时为项目根目录，相对路径相对于项目根目录。 |
| `env` | 空 | 额外的环境变量。 |
| `tabName` | `"Local"` | 新标签页的名称。 |
| `useEditorFont` | `true` | 使用编辑器字体；关闭后使用 `fontFamily`、`fontSize`、`lineHeight`。 |
| `overrideIdeShortcuts` | `true` | 让 shell 接收同时也是 IDE 快捷键的按键。 |
| `escapeToEditor` | `false` | 按 Escape 把焦点移回编辑器，而不是发给 shell。 |
| `optionAsMeta` | `false` | 把 Option 键当作 Meta 键（macOS）。 |
| `copyOnSelection` / `pasteOnMiddleClick` | `false` / `true` | 剪贴板行为。 |
| `cursorShape` / `cursorBlink` | `"block"` / `true` | `block`、`underline` 或 `bar`。 |

### `[proxy]`

对应 设置 › 外观与行为 › 系统设置 › HTTP 代理。IDE 自身的下载、更新程序和 HTTP 客户端都会使用；配置手动代理时，IDE 启动的进程会获得 `HTTP_PROXY`、`HTTPS_PROXY` 和 `NO_PROXY` 环境变量。

| 键 | 默认值 | 说明 |
| - | - | - |
| `mode` | `"auto"` | `none`（直连）、`auto`（使用系统的 `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`）或 `manual`。 |
| `kind` | `"http"` | `http` 或 `socks`。 |
| `host` / `port` | `""` / `80` | 代理地址。 |
| `noProxy` | `""` | 直连的主机，逗号分隔；`*` 匹配任意字符。 |
| `authenticate` / `login` | `false` / `""` | 代理认证。密码保存在已保存的密码中，不写入 `settings.toml`。 |

### 其他配置节

| 键 | 说明 |
| - | - |
| `[actionsOnSave]` | `optimizeImports`、`cleanup`（工具 › 保存时操作）。 |
| `[mcpServer]` | `enabled`：在 127.0.0.1 上把 IDE 的工具提供给智能体（工具 › MCP 服务器，仅全局）。参见 [MCP Server](https://openidea.sh/zh/guide/mcp.md)。 |
| `[agents]` | 智能体任务标题栏显示哪些信息（工具 › 智能体 › 聊天）。 |
| `[languages]` | 各语言的解释器、SDK 和选项，例如 `[languages.java]`、`[languages.python]`、`[languages.go]`。 |
| `[languageServers]` | 按名称配置各语言服务器的启动和协议选项，或在这里定义新的服务器。 |
| `[tools]` | 放在自定义位置的语言服务器和调试适配器，按命令名配置。 |
| `[vcs]`、`[console]`、`[debugger]`、`[run]` | 版本控制、控制台、调试器和运行/调试页面。 |
| `[inspections]`、`[spelling]` | 编辑器 › 检查、编辑器 › 自然语言 › 拼写。 |
| `[ssh]`、`[deployment]`、`runTargets`、`[cmake]` | SSH 配置、部署、运行目标、CMake。 |
| `[projectStructure]` | 源代码、测试、资源和排除文件夹（项目结构）。 |
| `externalTools` | 工具 › 外部工具中的条目。 |
| `[plugins.<plugin-id>]` | 插件声明的设置。 |

完整的配置键和默认值见源码：[`crates/ide-core/src/settings.rs`](https://github.com/l0ng-ai/openidea/blob/main/crates/ide-core/src/settings.rs) 及同目录下的其他 `*_settings.rs` 文件。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.