macos-tools/CLAUDE-PERMISSIONS-GUIDE.md

Claude Code 全局权限管理 - 快速入门指南

什么是这个系统？

这是一个全局的 Claude 执行权限管理系统，确保 AI 助手只在安全的范围内执行操作。

核心特性

✅ 一次配置，全局生效 - 不用每个项目都设置 ✅ Git 仓库限制 - 只在 Git 仓库中工作 ✅ 危险操作拦截 - 自动阻止 rm -rf /、sudo rm -rf 等 ✅ 安全运维白名单 - 允许所有常规 Git、Docker、K8s 操作 ✅ 智能确认 - 危险操作需要用户确认 ✅ 自动备份 - 重要操作前自动备份 ✅ 审计日志 - 记录所有命令执行

---

🚀 3 分钟快速开始

1. 添加到 PATH（一次性）

# 添加到 ~/.zshrc
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

2. 初始化系统（一次性）

# 初始化全局权限系统
claude-permissions init

3. 在项目中使用

# 进入你的项目
cd ~/work/my-project

# 如果还不是 Git 仓库，先初始化
git init

# 完成！现在 Claude 可以在此项目中安全工作了

---

工作原理

┌──────────────────────────────────────┐
│     Claude 想执行命令                 │
│     例如: rm -rf /tmp/old-data       │
└───────────────┬──────────────────────┘
                │
                ▼
┌──────────────────────────────────────┐
│  ❶ 检查是否在 Git 仓库中？            │
│     ✗ 不是 → 拒绝执行                │
│     ✓ 是   → 继续                    │
└───────────────┬──────────────────────┘
                │
                ▼
┌──────────────────────────────────────┐
│  ❷ 是否是危险操作？                   │
│     ✓ 是 (如 rm -rf /) → 拒绝执行    │
│     ✗ 否 → 继续                      │
└───────────────┬──────────────────────┘
                │
                ▼
┌──────────────────────────────────────┐
│  ❸ 是否需要用户确认？                 │
│     ✓ 是 (如 rm -rf dir) → 请求确认  │
│     ✗ 否 → 允许执行                  │
└───────────────┬──────────────────────┘
                │
                ▼
┌──────────────────────────────────────┐
│  ❹ 记录审计日志 + 执行命令             │
└──────────────────────────────────────┘

---

安全策略概览

❌ 永远不允许（自动拒绝）

rm -rf /                     # 删除根目录
rm -rf ~                     # 删除用户目录
dd if=/dev/zero              # 磁盘擦除
sudo rm -rf                  # 强制删除系统文件
git push --force origin main # 强推主分支
docker system prune -a --volumes  # 删除所有 Docker 资源
kubectl delete namespace kube-system  # 删除 K8s 系统命名空间
curl ... | bash              # 直接执行网络脚本
sudo shutdown                # 关闭系统

✅ 明确允许（自动执行）

# Git 操作
git status, git add, git commit
git push origin <feature-branch>  # 非主分支
git pull, git fetch, git diff

# Docker 操作
docker ps, docker build, docker run
docker compose up/down/restart
docker logs, docker exec

# Kubernetes 操作
kubectl get, kubectl logs, kubectl describe
kubectl apply, kubectl create
kubectl delete pod/deployment

# 开发工具
npm install/run/test
pip install
python, pytest
make

# 文件操作
ls, cat, grep, mkdir
cp, mv, rm <single-file>

⚠️ 需要确认（请求用户许可）

rm -rf <directory>           # 递归删除目录
docker system prune -a       # 删除所有未使用资源
kubectl delete namespace     # 删除命名空间
git push --force             # 强推到非主分支
sudo <command>               # 需要 root 权限

---

实际使用示例

示例 1: 日常开发（全部允许）

# 你在项目中
cd ~/work/my-app
git init  # 如果还没有

# Claude 可以安全地执行：
git checkout -b feature/new-feature   ✓
npm install express                   ✓
git add .                             ✓
git commit -m "Add feature"           ✓
git push origin feature/new-feature   ✓
docker build -t myapp .               ✓
kubectl apply -f deployment.yaml      ✓

示例 2: 危险操作被拦截

# Claude 尝试：
docker system prune -a --volumes

# 系统响应：
✗ 拒绝执行：危险操作
命令: docker system prune -a --volumes
ℹ 此操作已被全局安全策略阻止
ℹ 如果确实需要执行，请手动运行

示例 3: 需要确认的操作

# Claude 执行：
rm -rf /tmp/build-cache

# 系统提示：
⚠ 需要确认的操作
命令: rm -rf /tmp/build-cache
原因: 递归删除目录

是否继续执行? (yes/no): yes

ℹ 已创建备份: ~/.claude-code/backups/files_20251230_231500.tar.gz
✓ 权限检查通过

示例 4: 非 Git 仓库被拒绝

# 在 /tmp 中
cd /tmp

# Claude 尝试创建文件
touch test.txt

# 系统响应：
✗ 当前目录不在 Git 仓库中
ℹ 根据安全策略，Claude 只能在 Git 仓库中工作
ℹ 请先初始化 Git 仓库: git init

# 解决方法：
git init
# 现在 Claude 可以工作了

---

常用命令

# 查看系统状态
claude-permissions status

# 测试命令是否允许
claude-permissions test "git push"

# 查看审计日志（最近 50 条）
claude-permissions logs

# 在当前项目初始化配置（可选）
claude-permissions project-init

# 编辑全局配置
claude-permissions config

# 查看备份
claude-permissions backup

# 查看帮助
claude-permissions help

---

项目级自定义（可选）

某些项目可能需要额外的限制或权限：

# 在项目中创建配置
cd ~/work/critical-project
claude-permissions project-init

# 编辑配置
vim .claude-code/permissions.yml

项目配置示例:

# .claude-code/permissions.yml
project_name: my-critical-project
inherit_global: true  # 继承全局配置

# 额外的危险操作（项目特定）
additional_dangerous_operations:
  - pattern: "npm publish"
    reason: "需要通过 CI/CD 发布"

# 额外的允许操作（项目特定）
additional_allowed_operations:
  custom_scripts:
    - "./deploy.sh dev"
    - "./scripts/migrate.sh"

---

审计和监控

所有命令执行都会记录：

# 查看最近的日志
claude-permissions logs

# 或直接查看文件
tail -f ~/.claude-code/audit.log

日志示例:

[2025-12-30 23:00:00] ALLOWED: git status - Auto-approved
[2025-12-30 23:01:15] CONFIRMED: rm -rf /tmp/old - User approved
[2025-12-30 23:02:30] DENIED: rm -rf / - Dangerous operation

---

故障排查

问题：Claude 无法执行任何命令

原因: 不在 Git 仓库中

解决:

git init

问题：合法命令被拒绝

原因: 可能命中了危险模式

解决:

# 查看日志
claude-permissions logs

# 如果确认安全，手动执行
# 或修改配置
claude-permissions config

问题：无法使用 claude-permissions 命令

原因: PATH 配置问题

解决:

# 添加到 PATH
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 或使用完整路径
~/.config/claude-code/claude-permissions status

---

配置文件位置

~/.config/claude-code/
├── permissions.yml              # 全局配置（核心）
├── permission-checker.sh        # 权限检查器
├── claude-permissions           # 管理工具
└── README.md                    # 详细文档

~/.claude-code/
├── audit.log                    # 审计日志
└── backups/                     # 自动备份

<project>/.claude-code/
└── permissions.yml              # 项目级配置（可选）

---

高级功能

1. 查看系统状态

claude-permissions status

输出：

📊 Claude Code 权限系统状态

全局配置:
  ✓ /Users/username/.config/claude-code/permissions.yml

权限检查器:
  ✓ /Users/username/.config/claude-code/permission-checker.sh

当前项目:
  目录: /Users/username/work/my-project
  ✓ Git 仓库
  ⚠ 项目配置不存在（使用全局配置）

审计日志:
  总记录: 1523
  允许: 1450
  拒绝: 15
  确认: 58

备份:
  备份数: 23
  位置: /Users/username/.claude-code/backups

2. 定期审计

# 查看最近被拒绝的命令
grep "DENIED" ~/.claude-code/audit.log | tail -10

# 按日期统计
grep "2025-12-30" ~/.claude-code/audit.log | wc -l

3. 备份管理

# 查看所有备份
claude-permissions backup

# 手动删除旧备份（30天前）
find ~/.claude-code/backups/ -mtime +30 -delete

---

最佳实践

✅ 推荐

1. 在所有项目中使用 Git

   git init  # 即使是个人项目
   

2. 定期审查日志

   claude-permissions logs | grep "DENIED"
   

3. 关键项目添加额外限制

   cd production-app
   claude-permissions project-init
   

4. 不要禁用安全检查

   • 保持 require_git_repo: true
   • 不要注释危险操作列表

❌ 避免

1. 不要过度放宽权限
2. 不要忽略确认提示
3. 不要在系统目录中使用 Claude
4. 不要禁用审计日志

---

进阶：与 CI/CD 集成

# .github/workflows/claude-check.yml
name: Claude Permissions Check

on: [push]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Verify permissions config
        run: |
          if [ -f .claude-code/permissions.yml ]; then
            echo "✓ 项目权限配置存在"
          fi

---

下一步

1. 开始使用

   claude-permissions init
   cd your-project
   git init
   

2. 阅读详细文档

   cat ~/.config/claude-code/README.md
   

3. 测试权限

   claude-permissions test "your-command"
   

4. 监控日志

   claude-permissions logs
   

---

技术支持

查看配置

# 全局配置
cat ~/.config/claude-code/permissions.yml

# 项目配置
cat .claude-code/permissions.yml

测试和调试

# 测试命令权限
claude-permissions test "git status"
claude-permissions test "rm -rf /"

# 查看详细日志
tail -100 ~/.claude-code/audit.log

---

版本: 1.0.0 创建时间: 2025-12-30 详细文档: ~/.config/claude-code/README.md