配置 (settings.json)

CrabCode 的 JSON 配置文件，控制权限、环境变量、hooks、模型、插件等。

是什么

settings.json 决定 CrabCode 在当前用户/项目下的行为。按以下层级加载，后者覆盖前者：

1. 用户级：~/.crabcode/settings.json
2. 项目级：<repo>/.crabcode/settings.json（提交到 git，团队共享）
3. 本地级：<repo>/.crabcode/settings.local.json（不提交，个人覆盖）
4. 托管/策略级：企业管理员下发，优先级最高

Windows 上用户级路径为 %USERPROFILE%\.crabcode\settings.json。 设置 CRABCODE_CONFIG_DIR 环境变量可改用户级根（默认 ~/.crabcode）。

settings.json 与运行时全局状态（~/.crabcode.json，例如 theme、登录信息、统计计数）是两个不同的文件。本页面只讲 settings.json。

何时会看到这个文档

• /config 命令的"了解更多"链接
• 启动时 settings.json 字段校验失败的提示
• 安装某些 skill 或 plugin 后引导你加配置

字段总览

{
  "$schema": "https://json.schemastore.org/crabcode-settings.json",
  "permissions": {
    "defaultMode": "default",
    "allow": ["Bash(npm test:*)"],
    "deny": ["Bash(rm -rf:*)"],
    "ask":  ["WebFetch"],
    "additionalDirectories": ["~/code/sibling-repo"]
  },
  "env": {
    "DEBUG": "true",
    "ACOSMI_BASE_URL": "https://api-staging.acosmi.com"
  },
  "hooks": {
    "PreToolUse": [{ "matcher": "Bash", "hooks": [/* ... */] }]
  },
  "model": "deepseek-v4-flash",
  "smallModel": "qwen3.6-plus",
  "outputStyle": "default",
  "cleanupPeriodDays": 30
}

{
  "$schema": "https://json.schemastore.org/crabcode-settings.json",
  "permissions": {
    "defaultMode": "default",
    "allow": ["Bash(npm test:*)"],
    "deny": ["Bash(rm -rf:*)"],
    "ask":  ["WebFetch"],
    "additionalDirectories": ["~/code/sibling-repo"]
  },
  "env": {
    "DEBUG": "true",
    "ACOSMI_BASE_URL": "https://api-staging.acosmi.com"
  },
  "hooks": {
    "PreToolUse": [{ "matcher": "Bash", "hooks": [/* ... */] }]
  },
  "model": "deepseek-v4-flash",
  "smallModel": "qwen3.6-plus",
  "outputStyle": "default",
  "cleanupPeriodDays": 30
}

字段矩阵

下方表格按分组列出主要字段、类型与默认值。完整字段以 schema 校验为准（带上 $schema 行后大多数编辑器有补全）。

权限与目录

模型

环境变量

Hooks 与状态栏

MCP 与插件

Git / 工作树 / 编辑器集成

外观与体验

持久化与会话

自动更新与本地搜索

自定义模型 provider

企业策略字段

托管 settings.json（policy 级）专属字段，优先级最高、组员无法覆盖。

env 覆盖矩阵

env 字段里能放哪些变量是有边界的。下表为常用项：

出于安全考虑，重定向类（ACOSMI_BASE_URL 等）、信任根证书类（NODE_TLS_REJECT_UNAUTHORIZED、NODE_EXTRA_CA_CERTS）、项目切换类（API key / token）通过远程托管设置注入时会额外弹安全对话框，本机用户级 settings.json 写入不受此限。

限制与注意

• JSON 严格模式：不允许注释，不允许尾逗号
• 三层合并：本地级（settings.local.json）最适合个人调试，不会污染团队配置
• env 不会被 export：只在 CrabCode 进程内生效，不会影响外面的 shell
• 未知字段会保留：升级 schema 时旧字段不会被静默删除，但不参与校验
• 加载顺序：用户级 → 项目级 → 本地级 → 托管级；同名字段后者覆盖前者；数组类字段按字段语义合并
• 企业策略字段只在托管 settings.json 中生效：在个人 settings.json 写 allowManagedHooksOnly 之类不会生效

相关

• iam
• hooks
• memory
• mcp
• security