配置指南

Cursor Crane 使用多个配置文件来管理设置。大多数选项都可以直接在应用内设置界面中修改，TOML 文件主要用于手动编辑和高级自定义。

应用程序启动后，它会自动在以下位置创建配置文件：

• 文件夹~ 用户根目录

  • 文件夹Library

    • 文件夹Application Support

      • 文件夹com.expressionloss.CursorClaw 自动创建

        • 文件夹conf

          • conf.toml
          • commandSequences.toml
          • mouseControlKeyLayout.toml
          • shortcuts.toml
          • inputModeNanoFlavorShortcuts.toml

在应用内修改 conf 文件夹位置

您可以直接在应用中修改配置目录：

1. 打开 Settings > General。
2. 找到配置目录位置区域。
3. 点击 Select Config Directory。
4. 选择新的目录（例如 iCloud Drive 下的某个文件夹）。

如果将该目录移动到 iCloud Drive，配置文件可以在同一 Apple ID 的设备之间同步。

进行更改后，您可以在应用设置中重新加载配置，或重启应用程序。

哪个文件控制什么？

文件	存储内容
conf.toml	通用行为与模式偏好（布局、手势、鼠标/网格/输入行为等）
commandSequences.toml	命令与触发键的按键序列
shortcuts.toml	应用激活、命令快捷键和触发键快捷键
inputModeNanoFlavorShortcuts.toml	输入模式 Nano action 的快捷键
mouseControlKeyLayout.toml	调整鼠标控制的按键绑定

如果某项设置在应用界面中可见，建议优先在应用内修改。

conf.toml

conf.toml 用于控制应用行为偏好。

完整示例

version = 1

[general]
keyboardLayout = "usQWERTY"

[hintGenerator]
generatorType = "fingerFriendly"
minimumHintLength = 2
maximumHintLength = 4
predictionLength = 1
startByLeft = true

[gesture]
naturalPanDirection = false
treatRotateAsMouseButtonWhenNotHoldingFingers = false
treatPinchAsMouseButtonWhenNotHoldingFingers = false

[regularMode]
accurateMovementMode = "bisectionGrid"
defaultDistanceX = 200
defaultDistanceY = 200
autoSwitchToTextModeOnTextFieldFocus = false

[gridMode]
gridType = "proportional"
nineSquareGridKeySide = "left"

[scrollMode]
useDirectionKeysForScroll = true

[scrollMode.supplementaryWindows]
previousWindowLimit = 1
favoriteWindowLimit = 1
windowLimit = 1
priority = ["favoriteWindows", "previousWindows"]

[elementMode.supplementaryWindows]
previousWindowLimit = 1
favoriteWindowLimit = 1
windowLimit = 1
priority = ["favoriteWindows", "previousWindows"]

[textMode]
shortcutStyle = "nano"
autoExitWhenTextFieldLosesFocus = false
allowFindNextPreviousWithoutActiveQuery = true

[findMode]
recognitionSpeed = "accurate"
screenshotScale = "x2"

字段说明

字段	描述	默认值	可选值
version	配置文件版本号。	1	1
general.keyboardLayout	用于解析可读按键值的实体键盘布局。	usQWERTY	usQWERTY, colemak, colemakDH, dvorak, workman
hintGenerator.generatorType	提示生成算法。	fingerFriendly	fingerFriendly
hintGenerator.minimumHintLength	提示最小长度。	2	整数 >= 1
hintGenerator.maximumHintLength	提示最大长度。	4	整数 >= minimumHintLength
hintGenerator.predictionLength	提示预测字符长度。	1	整数（应用界面限制 0...5）
hintGenerator.startByLeft	优先使用左手起始键。	true	true, false
gesture.naturalPanDirection	是否启用自然滚动/平移方向。	false	true, false
gesture.treatRotateAsMouseButtonWhenNotHoldingFingers	非手势按住状态下将旋转手势当作鼠标按键。	false	true, false
gesture.treatPinchAsMouseButtonWhenNotHoldingFingers	非手势按住状态下将捏合手势当作鼠标按键。	false	true, false
regularMode.accurateMovementMode	鼠标控制模式下精确移动策略。	bisectionGrid	bisectionGrid, nineSquareGrid
regularMode.defaultDistanceX	默认水平移动距离。	200	正整数
regularMode.defaultDistanceY	默认垂直移动距离。	200	正整数
regularMode.holdSpaceToEnterMoveStage	在命令模式中按住空格进入鼠标控制模式。	true	true, false
regularMode.autoSwitchToTextModeOnTextFieldFocus	聚焦文本框时自动进入文本模式。	false	true, false
gridMode.gridType	网格移动类型。	proportional	bisection, nineSquare, proportional
gridMode.hintStyle	网格模式提示样式。	default	default, largeText
gridMode.nineSquareGridKeySide	Grid Mode 和鼠标控制模式共用的内置九宫格按键使用键盘的哪一侧。	left	left, right
scrollMode.useDirectionKeysForScroll	滚动模式下移动键用于滚动。	true	true, false
scrollMode.supplementaryWindows.previousWindowLimit	滚动模式最多包含的之前窗口数量。设为 0 即不包含之前窗口。	1	整数 >= 0
scrollMode.supplementaryWindows.favoriteWindowLimit	滚动模式最多包含的关注窗口数量。设为 0 即不包含关注窗口。	1	整数 >= 0
scrollMode.supplementaryWindows.windowLimit	滚动模式最终最多使用的辅助窗口总数，会在各来源数量上限和去重之后生效。	1	整数 >= 0
scrollMode.supplementaryWindows.priority	辅助窗口来源的优先级顺序。	["favoriteWindows", "previousWindows"]	包含 favoriteWindows 和 previousWindows 的数组
elementMode.supplementaryWindows.previousWindowLimit	元素模式最多包含的之前窗口数量。设为 0 即不包含之前窗口。	1	整数 >= 0
elementMode.supplementaryWindows.favoriteWindowLimit	元素模式最多包含的关注窗口数量。设为 0 即不包含关注窗口。	1	整数 >= 0
elementMode.supplementaryWindows.windowLimit	元素模式最终最多使用的辅助窗口总数，会在各来源数量上限和去重之后生效。	1	整数 >= 0
elementMode.supplementaryWindows.priority	辅助窗口来源的优先级顺序。	["favoriteWindows", "previousWindows"]	包含 favoriteWindows 和 previousWindows 的数组
textMode.shortcutStyle	输入模式快捷键风格。	nano	nano
textMode.autoExitWhenTextFieldLosesFocus	文本框失焦后自动退出输入模式。	false	true, false
textMode.allowFindNextPreviousWithoutActiveQuery	在没有当前查找词时，允许“查找下一个”和“查找上一个”复用选中文本或光标下的词。	true	true, false
findMode.recognitionSpeed	查找模式下 OCR 的速度与精度取舍。	accurate	accurate, fast
findMode.screenshotScale	查找模式在 OCR 前使用的截图倍率。	x2	x1, x2

commandSequences.toml

commandSequences.toml 用于定义命令触发序列（按键串）。

格式

[commandSequences]
'command.moveCursorToElement' = 'f'
'command.moveCursorToElementAndLeftClick' = 'c'
'command.moveCursorToText' = 'sm'
'command.moveCursorToTextAndLeftClick' = 'sc'
'command.moveCursorToTextAndRightClick' = 'SC'
'command.enterTextMode' = 'i'
'command.enterRawInputMode' = 'I'
'command.createTextAreaPortal' = 'O'
'command.enterElementMenuModeForFocusedWindow' = 'XW'
'command.enterElementMenuModeForElementBelowCursor' = 'XE'
'trigger.scrollUp' = 'j'
'trigger.scrollDown' = 'k'
'trigger.scrollLeft' = 'h'
'trigger.scrollRight' = 'l'

使用空字符串（''）可禁用某个序列。

可用键名

command.*： revertCursorLocation、enterMoveStage、moveCursorToElement、moveCursorToElementAndLeftClick、moveCursorToElementAndDoubleLeftClick、moveCursorToElementAndMiddleClick、moveCursorToElementAndRightClick、dragCursorToElement、moveCursorToText、moveCursorToTextAndLeftClick、moveCursorToTextAndRightClick、dragCursorToText、toggleDrag、enterGridModeAndLeftClick、enterGridModeAndDoubleLeftClick、enterGridModeAndMiddleClick、enterGridModeAndRightClick、enterGridModeAndMoveCursor、enterGridModeAndDragCursor、moveAndFocusToWindow、moveAndFocusToPreviousWindow、enterTextMode、enterRawInputMode、enterScrollMode、enterElementMenuModeForFocusedWindow、enterElementMenuModeForElementBelowCursor、createTextAreaPortal

trigger.*： up、down、left、right、leftClick、rightClick、middleClick、scrollDown、scrollUp、scrollLeft、scrollRight、scrollTop、scrollBottom、zoomIn、zoomOut、rotateClockwise、rotateCounterClockwise、smartZoom、forceClick

shortcuts.toml

shortcuts.toml 用于存储键盘快捷键。

格式

[activate]
key = "m"
modifiers = ["command", "option", "shift"]

[enterRegularModeMouseStage]
key = "f8"
modifiers = []

['commandIdentifier.command.moveCursorToElement']
key = "f"
modifiers = ["control", "option"]

每个快捷键项都是一个 TOML 表，包含：

• key：按键标识符，例如 "a"、"m"、"return"、"space"、"escape"、"left"、"f8"
• modifiers：修饰键数组，支持的值包括 "command"、"control"、"option"、"shift"

如果要移除一个已存储的绑定，直接删除对应的 TOML 记录即可。

为了兼容旧配置，carbonKeyCode / carbonModifiers 仍然可以读取，但新的手动编辑建议统一使用 key + modifiers。

inputModeNanoFlavorShortcuts.toml

inputModeNanoFlavorShortcuts.toml 会把输入模式 Nano action 的快捷键单独存放，而不是写进主快捷键文件里。

格式

['exit']
key = "x"
modifiers = ["control"]

['moveLeft']
key = "b"
modifiers = ["control"]

['scrollCursorToVisibleCenter']
key = "g"
modifiers = ["control"]

这个文件使用与 shortcuts.toml 相同的快捷键值格式。

mouseControlKeyLayout.toml

mouseControlKeyLayout.toml 用于覆盖鼠标控制按键绑定。文件中的可读按键值会按照 general.keyboardLayout 解析，因此同一个字符可以在 QWERTY、Colemak、Dvorak、Workman 等支持的布局中映射到正确的物理按键。

内置九宫格位置已经不再通过这个文件配置，而是会根据 gridMode.nineSquareGridKeySide 自动生成，这个设置同时作用于 Grid Mode 和鼠标控制模式。

你可以先在 Settings > General 中根据 preset 创建这个配置文件，再编辑生成的 TOML 文件做更细的调整。

格式

[primary]
"direction.up" = "i"
"direction.left" = "j"
"mouse.left" = "return"

文件包含 1 组覆盖项：

• primary：主动作（方向、手势、鼠标、滚动、功能）

primary 支持的动作键名： direction.up、direction.left、direction.down、direction.right、gesture.rotateCounterClockwise、gesture.rotateClockwise、gesture.pinchOut、gesture.pinchIn、function.hold、function.undo、mouse.left、mouse.middle、mouse.right、mouse.fourth、mouse.fifth、scroll.up、scroll.down

说明：

• 值使用与 shortcuts.toml 相同的可读按键格式，例如 "a"、"i"、"return"、"tab"、"[" 或 ";"。
• 这是高级配置文件，建议优先在应用内切换布局。