> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bettertoken.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code 如何配置 permissions 和 hooks？

> 使用 /permissions 和 settings.json 配置 Claude Code 的 allow、ask、deny 规则，并添加、验证和排查 hooks。

## 直接答案

在 Claude Code 中运行 `/permissions` 可以查看和管理权限规则；需要持久保存时，把 `allow`、`ask`、`deny` 写入 `settings.json`。Hooks 也写在同一类设置文件中，用于在工具调用前后执行格式化、测试或安全检查。权限规则的优先级是 **deny → ask → allow**，所以 deny 规则不会被 allow 覆盖。

这两项控制的是 Claude Code 在你电脑上的工具行为。接入 BetterToken 只会改变模型 API 的 Base URL、API Key 和路由，不会绕过本地权限或替你运行 hooks。

## Permissions 和 hooks 应该怎么分工？

| 需求              | 使用                             |
| --------------- | ------------------------------ |
| 某条命令可以直接执行      | `permissions.allow`            |
| 每次执行某类操作前都确认    | `permissions.ask`              |
| 禁止读取敏感文件或运行危险命令 | `permissions.deny`             |
| 编辑后自动格式化或测试     | `PostToolUse` hook             |
| 工具调用前做额外检查或阻止操作 | `PreToolUse` hook              |
| 给模型说明团队约定       | `CLAUDE.md`，不是 permission rule |

## 选择正确的配置范围

| 文件                            | 作用范围      | 是否适合提交到仓库 |
| ----------------------------- | --------- | --------- |
| `~/.claude/settings.json`     | 当前用户的所有项目 | 否         |
| `.claude/settings.json`       | 当前项目和团队   | 是         |
| `.claude/settings.local.json` | 当前项目、仅本机  | 否         |

<Warning>
  Permissions、hooks 和环境变量应写入 `settings.json`，不要写进 `~/.claude.json`。后者主要保存 Claude Code 的应用状态和界面信息。
</Warning>

## 配置一组最小权限规则

<Steps>
  <Step title="先用 /permissions 查看现有规则">
    在 Claude Code 中输入：

    ```text theme={null}
    /permissions
    ```

    界面会显示 allow、ask、deny 规则及其来源文件。先确认是否已有团队或管理员规则，再决定添加到用户级还是项目级配置。
  </Step>

  <Step title="添加精细规则">
    下面的项目级示例允许常见测试和 lint，要求每次 `git push` 前确认，并禁止读取 `.env` 文件：

    ```json theme={null}
    {
      "permissions": {
        "allow": [
          "Bash(npm run lint *)",
          "Bash(npm test *)"
        ],
        "ask": [
          "Bash(git push *)"
        ],
        "deny": [
          "Read(./.env)",
          "Read(./.env.*)"
        ]
      }
    }
    ```

    请把命令改成项目中真实存在的脚本。不要为了减少弹窗而直接启用 `bypassPermissions`；官方只建议在隔离容器或虚拟机中使用它。
  </Step>

  <Step title="重新打开 /permissions 验证">
    保存文件后再次运行 `/permissions`，确认每条规则显示在预期的来源下。然后分别触发一条 allow、ask 和 deny 规则，检查行为是否符合预期。
  </Step>
</Steps>

## 添加一个可复制的格式化 Hook

下面的例子会在 Claude Code 使用 `Edit` 或 `Write` 修改文件后运行项目的格式化脚本：

```json theme={null}
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run format"
          }
        ]
      }
    ]
  }
}
```

如果文件中已经有 `permissions`，请把 `hooks` 合并到同一个顶层 JSON 对象中，不要保存成单独的 `.claude/hooks.json`。先在终端中手动确认 `npm run format` 能正常完成，再交给 hook 自动执行。

<Warning>
  Command hook 会以当前系统用户的权限执行命令。只运行你已经检查过的脚本，不要在 hook 中输出 API Key、token、`.env` 内容或其他敏感信息。
</Warning>

## 如何确认 Hook 已生效？

1. 在 Claude Code 中输入 `/hooks`。
2. 找到 **PostToolUse**，确认其中有 `Edit|Write` 和 `npm run format`。
3. 让 Claude 修改一个测试文件。
4. 检查 Hook 输出和文件格式，确认只执行一次且没有报错。

Claude Code 通常会自动读取设置文件的修改。如果配置没有刷新，退出当前会话并重新启动 Claude Code。

## 常见错误与解决方法

| 现象                      | 原因                         | 解决方法                                                                                 |
| ----------------------- | -------------------------- | ------------------------------------------------------------------------------------ |
| 权限规则完全不生效               | 写进了 `~/.claude.json` 或错误目录 | 移到 `~/.claude/settings.json`、`.claude/settings.json` 或 `.claude/settings.local.json` |
| Allow 规则仍被拒绝            | 同一操作命中了 deny 或管理员规则        | 在 `/permissions` 中检查来源；deny 的优先级高于 ask 和 allow                                       |
| Hook 没有运行               | Event 或 matcher 与实际工具名不匹配  | 用 `/hooks` 检查；`PreToolUse` 在执行前触发，`PostToolUse` 在成功后触发，matcher 区分大小写                 |
| Hook 运行但命令失败            | 脚本、工作目录或依赖不正确              | 先在项目目录手动运行同一条命令，再修正 hook                                                             |
| 接入 BetterToken 后仍出现确认弹窗 | API provider 与本地权限是两套配置    | 保留 BetterToken Base URL 配置，另外在 Claude Code 中设置精细 permissions                         |
| 想临时停用全部 hooks           | 需要排除 hook 干扰               | 在设置中添加 `"disableAllHooks": true`；排查完成后删除或改回 `false`                                  |

## 适用于 BetterToken 的边界

BetterToken 负责 Claude Code 的模型 API 接入、模型路由、余额和用量记录。下面这些行为仍由本地 Claude Code 控制：

* 能否读取或修改某个文件
* 是否需要确认 Bash 命令
* Hook 何时运行、运行什么脚本
* Sandbox、MCP 和项目规则

如果问题是 `401`、Base URL 或模型映射，请查看 [Claude Code 接入 BetterToken 指南](/zh/ai-tools/claude-code)。如果问题是命令确认或自动化脚本，请继续在本页的 permissions 与 hooks 中排查。

## 相关文档

* [Claude Code 接入 BetterToken 指南](/zh/ai-tools/claude-code)
* [Claude Code 中的 CLAUDE.md 是什么？](/zh/faq/claude-code/claude-md)
* [Claude Code token 为什么消耗很多？](/zh/faq/token-cost/claude-code-token-usage)
* [Claude Code MCP 和 API Key / Base URL 有什么区别？](/zh/faq/concepts/mcp-vs-api-key-base-url)

## References

* [Claude Code permissions](https://code.claude.com/docs/en/permissions)
* [Claude Code hooks guide](https://code.claude.com/docs/en/hooks-guide)
* [Claude Code hooks reference](https://code.claude.com/docs/en/hooks)
* [Debug Claude Code configuration](https://code.claude.com/docs/en/debug-your-config)