配置指南

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

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

• 文件夹~ 用户根目录

  • 文件夹Library

    • 文件夹Application Support

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

        • 文件夹conf

          • conf.toml
          • commandSequences.toml
          • keyLayout.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 的快捷键
keyLayout.toml	可以调整键盘格局。这个还没准备好

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

conf.toml

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

完整示例

version = 1

[general]
layout = "ijkl"

[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"

[scrollMode]
useDirectionKeysForScroll = true
useRotateKeyForElementSwitching = true

[textMode]
shortcutStyle = "nano"
autoExitWhenTextFieldLosesFocus = false

[searchMode]
recognitionLanguages = ["en-US"]
recognitionSpeed = "accurate"
screenshotScale = "x2"

字段说明

字段	描述	默认值	可选值
version	配置文件版本号。	1	1
general.layout	方向键布局。	ijkl	wasd, hjkl, ijkl
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
scrollMode.useDirectionKeysForScroll	滚动模式下方向键用于滚动。	true	true, false
scrollMode.useRotateKeyForElementSwitching	滚动模式下旋转键用于切换元素。	true	true, false
textMode.shortcutStyle	输入模式快捷键风格。	nano	nano
textMode.autoExitWhenTextFieldLosesFocus	文本框失焦后自动退出输入模式。	false	true, false
searchMode.recognitionLanguages	搜索模式使用的 OCR 识别语言。	["en-US"]	语言标识符数组，例如 en-US、zh-Hans、ja-JP
searchMode.recognitionSpeed	搜索模式下 OCR 的速度与精度取舍。	accurate	accurate, fast
searchMode.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'
'trigger.scrollUp' = 'j'
'trigger.scrollDown' = 'k'

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

可用键名

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

trigger.*： up、down、left、right、leftClick、rightClick、middleClick、scrollDown、scrollUp、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 相同的快捷键值格式。

keyLayout.toml

keyLayout.toml 用于在当前布局（wasd/hjkl/ijkl）基础上覆盖物理按键映射。

格式

primary = []
additionalDirection = []

文件包含 2 组覆盖项：

• primary：主动作（方向、手势、鼠标、滚动、功能）
• additionalDirection：九宫格附加方向动作

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

additionalDirection 支持的动作键名： nineSquareGrid.topLeft、nineSquareGrid.topCenter、nineSquareGrid.topRight、nineSquareGrid.centerLeft、nineSquareGrid.center、nineSquareGrid.centerRight、nineSquareGrid.bottomLeft、nineSquareGrid.bottomCenter、nineSquareGrid.bottomRight

说明：

• 值使用 macOS 键码（KeyboardCode 的整数值）。
• 这是高级配置文件，建议优先在应用内切换布局。