在 settings.json 中自定义权限与环境变量

默认情况下，LingCode 在每次执行 Bash 命令、向项目根目录之外写入文件以及调用任何有副作用的工具之前都会弹出确认提示。这是合理的安全默认值——你肯定不希望一个新的 agent 悄悄在你的主目录里跑 rm -rf。

但用了 LingCode 一周之后，你会发现同样的提示反复出现：ls、git status、cat package.json、npm test。这些命令根本不需要每次审批。每次浪费 2–3 秒，一天乘以五十次，注意力就这样被零散打断。

解决方案不是某个隐藏菜单——而是一个你自己拥有和编辑的 JSON 文件。它有两个位置：

• ~/.claude/settings.json — 你的用户级配置，适用于这台 Mac 上的所有项目。
• <repo>/.claude/settings.local.json — 项目级配置，仅在该仓库内生效，并覆盖用户级配置。

本教程涉及三个顶层键：permissions.allow、permissions.deny 和 env。（还有第四个键 hooks，它有专属教程，参见 添加自定义钩子。）

在终端中执行：

mkdir -p ~/.claude
touch ~/.claude/settings.json
open -e ~/.claude/settings.json

如果文件是全新空文件，粘贴以下骨架并保存：

{
  "permissions": {
    "allow": [],
    "deny": []
  },
  "env": {}
}

LingCode 会在下次弹出权限提示时自动读取该文件，无需重启。

allow 和 deny 中的每一项都是匹配工具调用的字符串。两种常见格式：

• "Bash(<command pattern>)" — 匹配 Shell 命令。模式支持精确命令或前缀通配符。
• "<ToolName>" — 匹配该工具的任意调用，无论参数是什么。适合无条件信任的只读工具。

示例：

{
  "permissions": {
    "allow": [
      "Bash(ls:*)",
      "Bash(cat:*)",
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(npm test:*)",
      "Read",
      "Glob",
      "Grep"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo:*)"
    ]
  }
}

Bash(ls:*) 允许所有以 ls 开头的调用——ls、ls -la、ls src/ 均可。Bash(git status) 则是精确匹配。

两个文件会合并，项目配置覆盖用户配置。建议这样划分：

• 用户级（~/.claude/settings.json）：在任何仓库都安全的命令——ls、cat、git status、git diff、git log、pwd、which。这些与具体项目无关。
• 项目级（<repo>/.claude/settings.local.json）：该代码库专属的命令——npm test、cargo build、./scripts/build.sh、xcodebuild build。不同仓库需要不同的白名单。

如果项目配置文件中包含个人工作流相关的内容，应将其加入 gitignore。如果你想与团队共享一份基础白名单，可以在仓库根目录提交 .claude/settings.json（不带 .local）——LingCode 也会读取它，项目配置和本地配置会在此基础上叠加。

env 块用于设置 LingCode（及其运行的命令）可见的环境变量。常见用途：

• 按项目设置 provider 密钥——该仓库使用与默认不同的 API 密钥。
• 工具开关——DEBUG=1、NODE_ENV=development、NO_COLOR=1。
• 构建路径——JAVA_HOME、ANDROID_HOME（如果你的 shell rc 尚未导出它们）。

{
  "env": {
    "NODE_ENV": "development",
    "NO_COLOR": "1",
    "PYTHONDONTWRITEBYTECODE": "1"
  }
}

只读检查（随处安全）

"Bash(ls:*)",
"Bash(cat:*)",
"Bash(head:*)",
"Bash(tail:*)",
"Bash(pwd)",
"Bash(which:*)",
"Bash(file:*)",
"Bash(stat:*)"

Git 只读

"Bash(git status)",
"Bash(git status:*)",
"Bash(git diff:*)",
"Bash(git log:*)",
"Bash(git branch:*)",
"Bash(git show:*)",
"Bash(git remote -v)"

Node / npm 项目

"Bash(npm test:*)",
"Bash(npm run lint:*)",
"Bash(npm run typecheck:*)",
"Bash(npx tsc --noEmit:*)",
"Bash(node --version)"

Swift / Xcode 项目

"Bash(swift build:*)",
"Bash(swift test:*)",
"Bash(xcodebuild build:*)",
"Bash(xcodebuild test:*)",
"Bash(xcrun simctl list)"

根据你的项目类型，将对应的条目加入 permissions.allow，然后在接下来几天里持续补充——每当你发现自己反复批准某条命令时就把它加进去。

宽泛的允许规则是包容性的，而拒绝规则是绝对性的。一份简短、高置信度的拒绝列表：

"permissions": {
  "deny": [
    "Bash(rm -rf:*)",
    "Bash(rm -fr:*)",
    "Bash(sudo:*)",
    "Bash(curl * | sh)",
    "Bash(curl * | bash)",
    "Bash(:(){ :|:& };:)",
    "Bash(dd if=:*)",
    "Bash(mkfs:*)",
    "Bash(:>/dev/sda:*)"
  ]
}

即便设置了 permissions.allow: ["Bash(*)"]，拒绝列表依然会生效。这是最低安全基线——设置一次，永久生效。

编辑完成后，在 LingCode 对话中询问：

Run `git status` and tell me whether you were prompted.

如果白名单生效，LingCode 会直接执行命令并输出结果，不再弹出审批对话框。若仍然弹出提示，可能有两个原因：

• JSON 格式错误。多余的逗号或缺少花括号会导致整个文件被静默丢弃。运行 python3 -m json.tool ~/.claude/settings.json——有格式错误时它会打印解析异常。
• 模式不匹配。"Bash(git status)" 仅精确匹配 git status；LingCode 实际运行的可能是 git status --short。改为 "Bash(git status:*)" 即可。

不要一开始就试图写出完美的白名单。推荐的工作流：

1. 从一个小白名单起步（只读检查 + git status/diff）。
2. 正常使用 LingCode。当你发现自己在一次会话中批准了同一条命令两次时，就把它加进去。
3. 一周后，你会得到一份完全贴合自己实际工作流的个性化白名单——而不是别人猜测的版本。

如果你不想手动整理，这里还有另一篇教程，它会扫描你过去的对话记录，根据你实际批准过的命令来生成白名单：通过白名单减少权限提示。

整套流程——定位文件、理解格式、区分用户级与项目级、验证生效——已被打包成一个技能。将它放入你的技能目录，然后对 LingCode 说"configure settings.json"即可调用：

---
name: update-config
description: Configure the Claude Code harness via settings.json — permissions allow/deny and env vars (NOT hooks; hooks have their own skill). Triggers: 'allow X command', 'add permission to allowlist', 'set DEBUG=true', 'environment variable for Claude Code', 'move permission to user settings', 'configure settings.json', 'permissions config'. Actions: edit ~/.claude/settings.json (user) or .claude/settings.local.json (project), append to permissions.allow / permissions.deny, set env keys. File shape: JSON with permissions, env, hooks. Skip for: theme/model switches (use /config command), hook setup (use add-custom-hooks skill).
---

Configure LingCode by editing settings.json directly. Settings live in
two places that merge:

- User file: ~/.claude/settings.json (applies to every project)
- Project file: <repo>/.claude/settings.local.json (this repo only;
  overrides user file)

For permission changes:
1. Open the relevant file. Create it with skeleton {permissions:
   {allow: [], deny: []}, env: {}} if it doesn't exist.
2. Identify the exact command string the user wants allowed or denied.
   Bash commands use "Bash(<pattern>)" — pattern is literal or
   prefix-glob with ":*".
3. Add to permissions.allow or permissions.deny. Deny always wins.
4. For tools other than Bash, use the tool name directly: "Read",
   "Glob", "Grep".

For env var changes:
1. Add to the env object as "KEY": "value" strings.
2. Long-lived secrets go in settings.local.json (gitignored), not the
   shared settings.json.

After editing, validate with `python3 -m json.tool` and ask LingCode
to run a sample command to confirm the rule took effect. If the
prompt still appears, the most likely cause is a glob mismatch — read
the dialog's exact command string and write the pattern to match it.

Scope user vs project deliberately: read-only universal commands (ls,
cat, git status) belong in the user file; project-specific build and
test commands belong in the project file.

保存为 ~/.lingcode/skills/update-config/SKILL.md——关于确切路径以及技能如何被发现，参见 安装技能。

获取 LingCode →