配置指南

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

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

• 文件夹~ 用户根目录

  • 文件夹Library

    • 文件夹Application Support

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

        • 文件夹conf

          • conf.toml
          • commandSequences.toml
          • keyLayout.toml
          • shortcuts.toml

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

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

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

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

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

哪个文件控制什么？

文件	存储内容
conf.toml	通用行为与模式偏好（布局、手势、鼠标/网格/输入行为等）
commandSequences.toml	命令与触发键的按键序列
shortcuts.toml	键盘快捷键（全局激活和各命令快捷键）
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

字段说明

字段	描述	默认值	可选值
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.autoSwitchToTextModeOnTextFieldFocus	聚焦文本框时自动进入文本模式。	false	true, false
gridMode.gridType	网格移动类型。	proportional	proportional, nineSquare
scrollMode.useDirectionKeysForScroll	滚动模式下方向键用于滚动。	true	true, false
scrollMode.useRotateKeyForElementSwitching	滚动模式下旋转键用于切换元素。	true	true, false
textMode.shortcutStyle	文本模式快捷键风格。	nano	nano
textMode.autoExitWhenTextFieldLosesFocus	文本框失焦后自动退出文本模式。	false	true, false

这些设置可在应用中对应页面修改：

• Settings > General
• Settings > Mouse Control
• Settings > Grid Movement
• Settings > Element Jump
• Settings > Input

commandSequences.toml

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

格式

[commandSequences]
'command.moveCursorToElement' = 'f'
'command.moveCursorToElementAndLeftClick' = 'c'
'command.enterTextMode' = 'i'
'trigger.scrollUp' = 'j'
'trigger.scrollDown' = 'k'

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

可用键名

command.*： revertCursorLocation、moveCursorToElement、moveCursorToElementAndLeftClick、moveCursorToElementAndDoubleLeftClick、moveCursorToElementAndMiddleClick、moveCursorToElementAndRightClick、dragToElement、enterGridModeAndLeftClick、enterGridModeAndDoubleLeftClick、enterGridModeAndMiddleClick、enterGridModeAndRightClick、moveAndFocusToWindow、moveAndFocusToPreviousWindow、enterTextMode、enterScrollMode

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

应用内入口：Settings > Command。

shortcuts.toml

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

格式

[activate]
carbonKeyCode = 46
carbonModifiers = 6400

[enterRegularModeMouseStage]
carbonKeyCode = 119
carbonModifiers = 256

['commandIdentifier.command.moveCursorToElement']
carbonKeyCode = 3
carbonModifiers = 4352

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

• carbonKeyCode：macOS Carbon 键码（整数）
• carbonModifiers：Carbon 修饰键位掩码（整数）

常见顶层键名：

• activate
• enterRegularModeMouseStage
• toggleCheatsheets
• commandIdentifier.command.*
• commandIdentifier.trigger.*

应用内入口：Settings > Keyboard Shortcuts。

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 的整数值）。
• 这是高级配置文件，建议优先在应用内切换布局。