logo
nexa/CodeCop
Public
1
4
WeChat Login
CodeIssuesPull requestsEventsPackagesInsights
main
CodeCop/README.md
宅记
docs: add NPC vs OpenClaw Skill comparison and CNB pipeline integration guide
d9e29b91

🦐👮 CodeCop

给你的代码仓库养一只 AI 看门虾

CodeCop 是一个 OpenClaw Skill，用于监控代码仓库中的所有变更活动（无论来自 AI 还是人类），分析其合规性、安全性和质量，并生成报告和通知。

核心特点

  • 平台无关 — 通过适配层支持 CNB / GitHub / GitLab 等多种代码托管平台
  • 角色无关 — 同时监管 AI（NPC/Agent/Bot）和人类的代码提交
  • 触发灵活 — 支持 Webhook 推送、Cron 轮询、手动指令三种模式
  • 一行安装 — 作为 OpenClaw Skill 发布到 ClawHub，clawhub install codecop

安装

方式 1: 快速安装

git clone https://github.com/user/CodeCop.git
cd CodeCop && bash install.sh

安装脚本会自动检测环境、创建到 OpenClaw Skill 目录的软链接、提示环境变量配置。

方式 2: 手动安装

  1. 克隆或下载本仓库
  2. 将 codecop/ 目录拷贝或链接到 OpenClaw Skill 路径（默认 ~/.openclaw/skills/codecop）
  3. 配置环境变量（见下方表格）

环境变量

变量说明必填
CODECOP_PLATFORM目标平台（cnb / github）是
CODECOP_TOKEN平台访问令牌（CNB Token 或 GitHub Token）是

⚠️ 已知问题：不建议通过 OpenClaw Gateway 的 Web UI (webchat) 触发审查。当 PR 变更量较大时，session 数据（diff 内容、脚本输出等）可能达到上百 KB，会导致 Web UI 卡死甚至无法恢复（需手动删除 session 文件）。建议通过 Channel（如 Discord / Telegram / 微信） 或 Webhook 触发。

项目背景

2026 年，Vibe Coding 已成为主流。AI Agent 自主修 bug、提 PR、做 Code Review 已是常态。但随着 OpenClaw 等智能体框架的爆火和铺开，安全问题也随之显现——Gateway 接口未设防、Skill 投毒、绕过提示词执行脚本……大部分人的龙虾是不设防的。

我们的认知是：没有一个 Skill 能一劳永逸地解决所有安全问题。不同领域、不同行为都应该有一个单独的技能去专注处理——"术业有专攻"的分层治理可能更合适。

CodeCop 聚焦"代码仓库"这个领域，对 AI 或人类 Vibe Coding 之后提交的代码进行行为监管。灵感来源于 claude-code-tamagotchi——一个硬件宠物版的 Claude Code 行为监管系统。它做本地监管，我们做云端仓库级监管。

架构设计

检查流水线

目录结构

codecop/
├── SKILL.md                          # 核心 Skill 定义（场景路由 + 模板化架构）
├── references/
│   ├── platforms/
│   │   ├── cnb.md                    # CNB 平台适配（REST API + Webhook）
│   │   └── github.md                 # GitHub 适配（gh CLI）
│   ├── modes/
│   │   ├── realtime.md               # 实时触发模式
│   │   ├── chat.md                   # 聊天频道模式
│   │   └── local-cli.md              # 本地 CLI 模式
│   ├── rules/
│   │   ├── scope-check.md            # 范围合规检查规则
│   │   ├── security-check.md         # 安全审计检查规则
│   │   ├── quality-check.md          # 质量评估检查规则
│   │   └── behavior-check.md         # AI 行为画像检查规则
│   └── notification.md               # 通知渠道配置（OpenClaw Channel）
├── scripts/
│   ├── analyze_diff.py               # diff 解析 + 变更摘要
│   ├── check_security.py             # 安全扫描（密钥/敏感文件检测）
│   ├── check_quality.py              # 质量反模式检测
│   ├── check_behavior.py             # AI 行为画像检测
│   └── report_builder.py             # 报告生成 + 双格式输出
└── assets/
    └── templates/
        ├── report.md                 # PR Review 报告模板
        └── report-commit.md          # Commit Review 报告模板

检查维度

范围合规（Scope Check）

适用对象：所有提交者（AI + 人类）

检查代码变更是否在 Issue/PR 描述的范围之内：

  • 获取 PR 关联的 Issue 描述（或 PR 描述本身）
  • 由 AI Agent 进行语义分析：变更文件是否与任务意图相关
  • 检测"顺手改"：是否有与主题无关的附带修改
  • 规模匹配：改动量是否与任务复杂度匹配（修个 typo 改了 50 个文件？）
评级条件
✅ PASS变更与描述一致，规模合理
⚠️ WARN存在超出范围的小改动，但主体一致
❌ BLOCK变更与描述严重不符

安全审计（Security Check）

适用对象：所有提交者（AI + 人类）

正则模式匹配检测常见安全问题：

检测项说明
硬编码密钥API Key、Token、Password、AWS Key、Private Key、JWT
敏感文件变更.env*、credentials.*、*.pem、*.key、id_rsa* 等
安全防护代码删除认证/鉴权/校验相关代码被移除
可疑依赖变更依赖文件中出现 exec、eval 等危险模式
评级条件
✅ PASS未发现安全风险
⚠️ WARN存在需要人工确认的安全相关变更
❌ BLOCK检测到明确的安全风险（硬编码密钥等）

质量评估（Quality Check）

适用对象：所有提交者（AI + 人类）

检测代码质量反模式：

检测项说明
空异常捕获except: / catch { 无具体类型
TODO/FIXME/HACK 标记遗留标记检测
过长代码块单 hunk 新增超过 100 行
调试代码残留console.log、print()、debugger、pdb.set_trace
硬编码魔法数字数值常量直接出现在逻辑中
重复代码块同一 diff 中出现相同代码块
评级条件
✅ PASS无 findings，或仅有 INFO 级别
⚠️ WARN存在 WARN 级别 findings

行为画像（Behavior Check）

适用对象：仅 AI 提交者

借鉴 claude-code-tamagotchi 的四类违规分类：

类型含义
unauthorized_action做了明确禁止的事
refused_request拒绝执行合理请求
excessive_exploration过度探索不相关文件
wrong_direction偏离任务方向

设计要点

  1. Python 脚本做确定性分析，LLM 做语义理解 — 脚本处理 diff 解析、安全扫描和质量检测，AI Agent 做范围合规判断、深度语义分析和误报排除
  2. 所有脚本通过 JSON stdout 通信 — 方便 AI Agent 调用和链式组合
  3. 仅依赖 Python 标准库 — 无需安装任何第三方包
  4. CNB 优先，可扩展 — Phase 1 实现 CNB 适配，通过 references/platforms/ 目录结构支持后续平台扩展

报告格式

PR 评论报告

🦐👮 CodeCop 监管报告

| 项目 | 信息 |
|------|------|
| 📋 目标 | myorg/myrepo PR #42 "修复登录 bug" |
| 👤 作者 | ai-npc (AI) |
| 📊 规模 | 5 文件, +120 -30 |

| 维度 | 结果 | 说明 |
|------|------|------|
| 范围合规 | ⚠️ WARN | 存在 2 个超范围文件 |
| 安全审计 | ❌ BLOCK | 检测到硬编码 Token |
| 质量评估 | ✅ PASS | 无质量问题 |
| 行为画像 | ⚠️ WARN | 过度探索: 修改 12 文件, 平均 1.5 行 |

综合评级: ❌ BLOCK
检测到严重问题，建议阻止合并并要求修改。

通知策略

评级PR 评论通知 (OpenClaw Channel)
✅ PASS发布轻量评论不通知
⚠️ WARN发布详细评论正常通知
❌ BLOCK详细评论 + 请求人工介入紧急通知

平台适配

CNB

利用 CNB AI 全家桶实现深度集成：

CNB 能力CodeCop 使用方式
REST API (api.cnb.cool)读取 PR diff、PR 详情、Issue 内容、发布评论
Webhook 插件 (cnbcool/webhook)实时接收 push/PR 事件
NPC 身份以 NPC 身份发布监管报告评论
AI Review 插件与 CodeCop 互补（AI Review 侧重代码细节，CodeCop 侧重行为监管）

GitHub

通过 gh CLI 实现相同的检查流程，接口已映射。

使用方式

环境变量

变量说明必填
CODECOP_PLATFORM目标平台（cnb / github）是
CODECOP_TOKEN平台访问令牌（CNB Token 或 GitHub Token）是

手动指令

/codecop review PR #42          # 审查指定 PR
/codecop scan last 10 commits   # 扫描最近 10 次提交
/codecop report myorg/myrepo    # 生成仓库监管概况

CNB 流水线自动触发（实验性）

由于 OpenClaw 本身可以作为 CNB NPC 运行在流水线容器中，CodeCop 作为 OpenClaw Skill 理论上可以通过 CNB 流水线事件自动触发，实现 PR 创建时自动审查，无需人工输入指令。目前尚未实现该模式，但可通过 Webhook 将 CNB 事件转发到已运行的 OpenClaw 实例来达到类似效果：

# 在目标仓库的 .cnb.yml 中添加
main:
  pull_request:
    - stages:
        - name: trigger-codecop
          image: cnbcool/webhook
          settings:
            urls:
              - https://your-openclaw-instance/api/message
            method: POST
            content_type: application/json
            template: |
              {
                "message": "/codecop review PR https://cnb.cool/{{ CNB_REPO_SLUG }}/-/pulls/{{ CNB_PULL_REQUEST_NUMBER }}"
              }

更多关于 CNB NPC 与 OpenClaw Skill 的关系，参见 docs/npc-vs-skill.md。

脚本独立使用

# diff 解析 + 变更摘要
python3 codecop/scripts/analyze_diff.py \
  --diff-file pr.patch

# 安全审计扫描
python3 codecop/scripts/check_security.py \
  --diff-file pr.patch

# 质量评估检查
python3 codecop/scripts/check_quality.py \
  --diff-file pr.patch

# AI 行为画像检查
python3 codecop/scripts/check_behavior.py \
  --diff-file pr.patch \
  --context "修复登录 bug" \
  --author-type ai

# 生成报告（JSON + Markdown 双格式）
python3 codecop/scripts/report_builder.py \
  --scope '{"verdict":"WARN","details":"...","out_of_scope_files":[]}' \
  --security '{"verdict":"PASS","findings":[]}' \
  --metadata '{"repo":"org/repo","pr_number":42,"pr_title":"修复登录 bug","author":"dev","author_type":"human","files_changed":5,"additions":120,"deletions":30}' \
  --format json --review-type pr

开发路线

Phase 1：MVP ✅

  • SKILL.md 核心定义
  • CNB 适配层
  • 范围合规检查（Scope Check）
  • 安全审计检查（Security Check）
  • 报告生成 + PR 评论
  • Telegram 通知

Phase 2：模板化 + 扩展化 ✅

  • SKILL.md 场景路由 + 模板化重构
  • Commit Review 支持
  • GitHub 适配层
  • 三种运行模式（实时触发/聊天频道/本地 CLI）
  • OpenClaw Channel 通知（替代 Telegram）
  • 本地安装支持
  • 发布到 ClawHub

Phase 3：深化

  • 质量评估检查（Quality Check）
  • AI 行为画像检查（Behavior Check）
  • GitLab 适配层
  • 桌面宠物 / menubar app
  • 自定义规则引擎

差异化定位

已有项目定位CodeCop 的差异
openclaw-cn / cnb-skill"用" OpenClaw我们做"管"
claude-code-tamagotchi本地 Claude Code 监管我们是云端仓库级监管
CNB AI Review内置代码审查我们加上范围合规 + 行为画像 + 跨平台

License

MIT

© 2026 Tencent, Inc. Supported by Tencent Cloud
About Us
Privacy Policy
Terms of Service
SLA
API
Docs
Showcase
Feedback
35/F,Tencent Building,Kejizhongyi Avenue,Nanshan District,Shenzhen
京ICP备11018762号-111
粤公网安备44030002006058号粤公网安备44030002006058号