OpenClaw + Claude Code 插件：打通 AI 全链路开发的完整实战指南

[一、引言：API 补全时代结束了，编码 Agent 时代来了](#一、引言：API 补全时代结束了，编码 Agent 时代来了)

[二、系统架构全景：五大引擎 + Council 编排](#二、系统架构全景：五大引擎 + Council 编排)

[2.1 架构总览](#2.1 架构总览)

[2.2 五大引擎对比](#2.2 五大引擎对比)

[2.3 源码结构一览](#2.3 源码结构一览)

[三、安装部署：三种方式，从零到可用只要 5 分钟](#三、安装部署：三种方式，从零到可用只要 5 分钟)

[3.1 前置依赖](#3.1 前置依赖)

[3.2 方式 A：一键安装（推荐）](#3.2 方式 A：一键安装（推荐）)

[3.3 方式 B：独立安装（不依赖 OpenClaw）](#3.3 方式 B：独立安装（不依赖 OpenClaw）)

[3.4 方式 C：手动安装（完全控制）](#3.4 方式 C：手动安装（完全控制）)

[3.5 连接第三方客户端](#3.5 连接第三方客户端)

[四、27 个工具 API 分类精讲](#四、27 个工具 API 分类精讲)

[4.1 会话管理工具（Session Tools）------ 最基础最常用](#4.1 会话管理工具（Session Tools）—— 最基础最常用)

[4.2 跨会话通信工具（Inbox / Messaging）](#4.2 跨会话通信工具（Inbox / Messaging）)

[4.3 Team 工具（Agent Teams）](#4.3 Team 工具（Agent Teams）)

[4.4 Council 工具（多智能体委员会）------ 最强大的功能](#4.4 Council 工具（多智能体委员会）—— 最强大的功能)

[4.5 Ultra 工具（高级编排）](#4.5 Ultra 工具（高级编排）)

[4.6 成本追踪工具](#4.6 成本追踪工具)

[4.7 模型与配置工具](#4.7 模型与配置工具)

[五、Council 多智能体系统：让 AI 团队帮你干活](#五、Council 多智能体系统：让 AI 团队帮你干活)

[5.1 Council 是什么？](#5.1 Council 是什么？)

[5.2 工作原理](#5.2 工作原理)

[5.3 启动一个 Council](#5.3 启动一个 Council)

[5.4 混合引擎 Council------最强配置](#5.4 混合引擎 Council——最强配置)

[5.5 Council 完整生命周期](#5.5 Council 完整生命周期)

[5.6 Council 系统提示与日志](#5.6 Council 系统提示与日志)

[六、实战案例：用 Council 开发密码生成器 CLI](#六、实战案例：用 Council 开发密码生成器 CLI)

[6.1 Council 团队配置](#6.1 Council 团队配置)

[6.2 协作过程实录](#6.2 协作过程实录)

[Round 1: 需求分析与架构设计](#Round 1: 需求分析与架构设计)

[Round 2-3: 核心代码实现](#Round 2-3: 核心代码实现)

[Round 4: 测试验证](#Round 4: 测试验证)

[Round 5: 文档与最终审查](#Round 5: 文档与最终审查)

[6.3 最终交付物](#6.3 最终交付物)

[6.4 运行效果](#6.4 运行效果)

[6.5 质量指标](#6.5 质量指标)

结语

一、引言：API 补全时代结束了，编码 Agent 时代来了

朋友，你是不是也经历过这样的场景：用 Claude API 写了一段代码，然后手动粘贴到项目里，再手动跑测试，发现报错，又复制错误信息发回给 API......如此反复，一个下午就这么过去了。

问题的本质是什么？ 传统的 LLM API 给你的是"补全"（completions）------它只负责生成文本，不负责执行。而真正的开发工作需要的是：读文件、改文件、跑命令、看结果、再调整------一个完整的反馈循环。

这就是 OpenClaw + Claude Code 插件 要解决的问题。它不是给你一个更聪明的聊天机器人，而是给你一个完全托管的编码 Agent：

|-----------|------------------------|
| 传统 API 调用 | OpenClaw + Claude Code |
| 返回文本补全 | 返回完整的编码 Agent |
| 需要手动粘贴/执行 | 自动文件编辑 + 工具调用 |
| 无状态，每次重新来 | 7 天持久会话，跨重启恢复 |
| 单模型单次调用 | 多引擎多模型路由 + 热切换 |
| 无协作能力 | Council 多智能体并行协作 |

打个比方：传统 API 像是给你一个能说话的顾问，你得自己动手干活；而 OpenClaw + Claude Code 像是给你一整个开发团队------架构师、工程师、测试员、文档专家------他们自己协调、自己干活，你只需要审查和拍板。

💡 核心要点 ：openclaw-claude-code 插件把 Claude Code CLI 的能力包装成干净的、基于工具的 API。你的 Agent 获得持久会话、实时流式传输、多模型路由、多引擎支持和多 Agent Council 编排------全部无需自己构建编排层。

二、系统架构全景：五大引擎 + Council 编排

在深入细节之前，先看全貌。理解架构是用好任何工具的前提。

2.1 架构总览

复制代码

┌─────────────────────────────────────────────────────────────┐
│                  OpenClaw / 你的代码                          │
│                       │ tool calls                           │
│                       ▼                                      │
│              Plugin Entry (index.ts)                         │
│              ┌────────┼────────┐                             │
│              ▼        ▼        ▼                             │
│        SessionManager  Proxy   HTTP Server                   │
│        ┌──┬──┬──┬──┐  Handler  (:18796)                     │
│        ▼  ▼  ▼  ▼  ▼    │                                   │
│     Claude Codex Gemini  │  Anthropic ↔ OpenAI               │
│     Engine Engine Engine │  格式转换                          │
│        │     │     │     ▼                                   │
│     Council  Inbox  Ultraplan                                │
│     (git worktree per agent)                                 │
└─────────────────────────────────────────────────────────────┘

这张架构图透露了几个关键设计决策：

分层解耦 ：Plugin Entry（index.ts）是唯一入口，暴露 27 个工具 + proxy 路由。所有引擎通过统一的 ISession 接口驱动，引擎可以热插拔。

多引擎并行：不是只能用 Claude，Codex、Gemini、Cursor、甚至自定义 CLI 都能接入。这意味着你可以在同一个 Council 里混合使用不同厂商的模型。

内置 HTTP 代理 ：端口 18796 上运行的 OpenAI 兼容代理服务器，让任何支持 OpenAI 格式的客户端（LobeChat、Open WebUI、ChatGPT-Next-Web）都能直接连接。

2.2 五大引擎对比

|------------|--------------------------------|---------------|-----------------------|-----------|
| 引擎 | 源文件 | 会话类型 | 核心特点 | 适用场景 |
| Claude | persistent-session.ts | 持久（有状态子进程） | 完整多轮对话，原生 Agent Teams | 主力开发、复杂任务 |
| Codex | persistent-codex-session.ts | 一次性（One-shot） | 上下文通过工作目录传递 | 快速实现、代码生成 |
| Gemini | persistent-gemini-session.ts | 一次性（One-shot） | 创意方案生成 | 头脑风暴、替代方案 |
| Cursor | persistent-cursor-session.ts | 一次性（One-shot） | IDE 集成 | 编辑器内使用 |
| Custom | persistent-custom-session.ts | 可配置 | 任何 CLI 工具 | 自研工具接入 |

关键区别在于：Claude 引擎维护一个持久子进程，对话历史完整保留；而 Codex/Gemini/Cursor 是每条消息一次性的，上下文依赖工作目录而非对话历史。选哪个？如果你需要多轮深度对话，选 Claude；如果只是快速生成一段代码，Codex 或 Gemini 更快更便宜。

2.3 源码结构一览

复制代码

index.ts                     → Plugin entry：27 个工具 + proxy 路由
models.ts                    → 集中式模型注册表：定价、别名、引擎
types.ts                     → 共享类型、ISession 接口
constants.ts                 → 共享常量：超时、限制、阈值
logger.ts                    → 结构化 Logger 接口
base-oneshot-session.ts      → 一次性引擎的抽象基类
persistent-session.ts        → Claude Code 引擎
persistent-codex-session.ts  → Codex 引擎
persistent-gemini-session.ts → Gemini 引擎
persistent-cursor-session.ts → Cursor Agent 引擎
persistent-custom-session.ts → 自定义引擎
session-manager.ts           → 多会话编排 + Council 管理
circuit-breaker.ts           → 引擎故障跟踪 + 指数退避
inbox-manager.ts             → 跨会话消息传递

每个文件职责单一、边界清晰。这种设计让你在需要扩展新引擎时，只需要实现 ISession 接口即可。

三、安装部署：三种方式，从零到可用只要 5 分钟

3.1 前置依赖

在安装插件之前，确保你的环境满足以下条件：

bash 复制代码

# 1. Node.js 22+（必须）
node -v
# 期望输出: v22.x.x 或更高

# 2. Claude Code CLI（核心依赖）
npm install -g @anthropic-ai/claude-code
claude --version

# 3. OpenClaw（如果使用插件模式）
openclaw --version

# 4. 配置 Anthropic API Key
export ANTHROPIC_API_KEY=sk-ant-xxxxx

⚠️ 注意：通过 OpenClaw 使用 Claude Code 需要 API Key 付费，不能使用 Pro/Max 订阅额度。这是 Anthropic 的政策限制------订阅额度仅适用于 Claude Code CLI 直接使用、claude.ai、Claude Desktop 和 Claude Cowork，第三方工具一律走 API 计费。

3.2 方式 A：一键安装（推荐）

最简单的方式，一条命令搞定注册 + 重启：

bash 复制代码

curl -fsSL https://raw.githubusercontent.com/Enderfga/openclaw-claude-code/main/install.sh | bash

这个脚本做了三件事：通过 npm 安装插件包、在 openclaw.json 中注册插件、自动重启 Gateway。

3.3 方式 B：独立安装（不依赖 OpenClaw）

如果你不用 OpenClaw，插件也能独立运行：

bash 复制代码

# 全局安装
npm install -g @enderfga/openclaw-claude-code

# 启动独立服务（暴露 OpenAI 兼容 API）
claude-code-skill serve

启动后你就有了一个运行在 http://127.0.0.1:18796 的 OpenAI 兼容接口，任何支持 OpenAI 格式的客户端都能直接连。

3.4 方式 C：手动安装（完全控制）

适合需要精细控制或排查问题的场景：

bash 复制代码

# Step 1: 创建目标目录
mkdir -p ~/.openclaw/extensions/openclaw-claude-code

# Step 2: 下载并解压插件包
cd /tmp
npm pack @enderfga/openclaw-claude-code
tar -xzf enderfga-openclaw-claude-code-*.tgz
cp -r package/* ~/.openclaw/extensions/openclaw-claude-code/

# Step 3: 进入插件目录安装依赖
cd ~/.openclaw/extensions/openclaw-claude-code
npm install --production --ignore-scripts

# Step 4: 验证文件结构
ls -la ~/.openclaw/extensions/openclaw-claude-code/

然后编辑 ~/.openclaw/openclaw.json，添加插件白名单：

XML 复制代码

{
  "plugins": {
    "allow": [
      "openclaw-claude-code"
    ],
    "entries": {
      "openclaw-claude-code": {
        "enabled": true
      }
    }
  }
}

最后重启并验证：

bash 复制代码

# 重启 Gateway
openclaw gateway restart

# 验证插件加载
openclaw plugins list | grep -i claude

# 运行诊断
openclaw plugins doctor

3.5 连接第三方客户端

插件内置的 HTTP 代理服务器兼容 OpenAI API 格式，你可以用各种客户端连接：

|------------------|-----------------------------|--------------|
| 客户端 | API Base URL | API Key |
| LobeChat | http://127.0.0.1:18796/v1 | 任意值或留空 |
| Open WebUI | http://127.0.0.1:18796/v1 | not-needed |
| ChatGPT-Next-Web | http://127.0.0.1:18796/v1 | 任意值 |

测试连接：

bash 复制代码

curl http://127.0.0.1:18796/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true
  }'

💡 核心要点：三种安装方式任选其一。生产环境推荐一键安装；想脱离 OpenClaw 独立使用就选方式 B；需要完全控制就选手动安装。关键是确保 Node.js 22+ 和 Claude Code CLI 已就绪。

四、27 个工具 API 分类精讲

插件的核心价值在于它暴露的 27 个工具 API。它们分为 7 大类，覆盖了从会话管理到多智能体编排的完整链路。

4.1 会话管理工具（Session Tools）------ 最基础最常用

|-------------------|---------|--------------------------------------------|
| 工具名 | 功能 | 关键参数 |
| session_start | 启动新会话 | name, cwd, engine, model, effort |
| session_send | 发送消息到会话 | name, message, effort |
| session_status | 查询会话状态 | name |
| session_list | 列出所有会话 | - |
| session_resume | 恢复会话 | name, model（支持热切换） |
| session_stop | 停止会话 | name |
| session_history | 获取对话历史 | name |

这是最基础的 7 个工具，几乎每次使用都会用到。来看一个完整的工作流：

python 复制代码

import { SessionManager } from '@enderfga/openclaw-claude-code';

const manager = new SessionManager();

// 1. 启动会话------指定引擎、模型和思考深度
await manager.startSession({
  name: 'my-task',
  cwd: '/home/ubuntu/projects/my-app',
  engine: 'claude',       // claude | codex | gemini | cursor | custom
  model: 'sonnet',        // 模型别名，插件内部映射到完整名称
  effort: 'high',         // low | medium | high | max
});

// 2. 发送消息------effort 可以每条消息单独设置
const result = await manager.sendMessage('my-task', 'Fix the failing tests', {
  effort: 'max',          // 这条消息用最深度的思考
});

// 3. 查询状态------实时了解 Token 消耗和成本
const status = manager.getSessionStatus('my-task');
console.log(`Tokens: ${status.tokens}, Cost: $${status.cost}`);

// 4. 恢复会话并热切换模型------不中断上下文
await manager.resumeSession('my-task', {
  model: 'opus',          // 从 Sonnet 热切换到 Opus
});

💡 核心要点 ：effort 参数是省钱利器。简单任务用 low，复杂架构用 max。同一个会话里不同消息可以用不同 effort，灵活控制。

4.2 跨会话通信工具（Inbox / Messaging）

|-------------------|---------------|
| 工具名 | 功能 |
| session_send_to | 向另一个会话发送消息 |
| inbox_check | 检查当前会话的收件箱 |
| inbox_send | 发送消息到指定会话的收件箱 |

这三个工具是多 Agent 协作的通信基础设施。空闲会话立即接收消息；忙碌会话排队等待稍后投递。

python 复制代码

// 定向通信------让 planner 给 coder 发需求
await manager.sessionSendTo('planner', 'coder',
  'The auth module needs rate limiting');

// 广播------monitor 向所有会话发警报
await manager.sessionSendTo('monitor', '*', 'Build failed!');

4.3 Team 工具（Agent Teams）

|-------------|-----------|
| 工具名 | 功能 |
| team_list | 列出当前团队成员 |
| team_send | 向团队成员发送消息 |

Team 工具在所有引擎上都可用。Claude 引擎使用原生 Agent Teams 实现；Codex/Gemini/Cursor 使用跨会话消息传递作为虚拟团队层。

4.4 Council 工具（多智能体委员会）------ 最强大的功能

|------------------|------------|------------------------|
| 工具名 | 功能 | 说明 |
| council_start | 启动 Council | 后台运行，立即返回 session ID |
| council_status | 查询状态 | 轮次、共识、Agent 进度 |
| council_abort | 终止 Council | 停止所有 Agent 会话 |
| council_inject | 注入用户消息 | 向所有 Agent 的下一轮提示注入 |
| council_review | 审查输出 | 变更文件、分支、计划、摘要 |
| council_accept | 接受工作 | 清理 worktree/分支/plan.md |
| council_reject | 拒绝工作 | 重写 plan.md 附带反馈 |

Council 是这个插件最核心的差异化能力，下一章我们将深度展开。

4.5 Ultra 工具（高级编排）

|----------------------|--------|---------------------|
| 工具名 | 功能 | 说明 |
| ultraplan_start | 深度规划 | 最长 30 分钟的 Opus 规划会话 |
| ultraplan_status | 查询规划状态 | 轮询完成状态和计划内容 |
| ultrareview_start | 舰队代码审查 | 多个专业 Bug 猎手并行审查 |
| ultrareview_status | 查询审查状态 | 各审查员的发现 |

Ultraplan 本质上是一个专用的 Opus 规划会话，附加了特殊的系统提示指导彻底探索项目，只输出计划不写代码。适合在 Council 之前先让 Opus 花 30 分钟把需求想透。

python 复制代码

// 先规划，再执行
const plan = manager.ultraplanStart(
  'Add OAuth2 support with Google and GitHub providers',
  { cwd: '/path/to/project', model: 'opus', timeout: 1800000 }
);

// 每 30 秒轮询
let planStatus;
do {
  await new Promise(r => setTimeout(r, 30000));
  planStatus = manager.ultraplanStatus(plan.id);
} while (planStatus?.status !== 'completed');

console.log('Plan ready:', planStatus.plan);
// 然后把 plan 传给 Council 去执行

4.6 成本追踪工具

|---------------|----------|
| 工具名 | 功能 |
| cost_report | 获取实时成本报告 |
| cost_reset | 重置成本计数器 |

4.7 模型与配置工具

|----------------|-----------|
| 工具名 | 功能 |
| model_list | 列出可用模型及定价 |
| model_switch | 切换当前会话的模型 |
| tool_toggle | 启用/禁用特定工具 |

五、Council 多智能体系统：让 AI 团队帮你干活

Council 是 OpenClaw + Claude Code 插件的王牌功能。如果说会话管理是让一个人更高效地工作，那 Council 就是让一整个团队协作开发。

5.1 Council 是什么？

一句话：Council 编排多个 AI Agent 在同一代码库上并行工作，使用 git worktree 隔离、基于轮次的执行和共识投票。

从 three-minds 项目移植并适配为直接通过 SessionManager + ISession 运行。

5.2 工作原理

复制代码

┌─────────────────────────────────────────────────┐
│                 Council 启动                      │
│                     │                            │
│    ┌────────────────┼────────────────┐           │
│    ▼                ▼                ▼           │
│ 🏗️ Architect     ⚙️ Engineer      🔍 Reviewer   │
│ (git worktree A) (git worktree B) (git worktree C)│
│    │                │                │           │
│    ▼                ▼                ▼           │
│  Round 1: 各自独立工作                             │
│    │                │                │           │
│    └────────────────┼────────────────┘           │
│                     ▼                            │
│              共识投票 [CONSENSUS: YES/NO]          │
│                     │                            │
│           ┌─────────┴─────────┐                  │
│           ▼                   ▼                  │
│     达成共识 → 完成       未达成 → Round 2...      │
│                                                  │
│  最终: council_review → council_accept/reject     │
└─────────────────────────────────────────────────┘

几个关键机制值得注意：

git worktree 隔离：每个 Agent 在独立的 git worktree 中工作，互不干扰。这意味着 Architect 在设计架构的同时，Engineer 可以在另一个分支写代码，Reviewer 在第三个分支做审查------真正的并行，不是伪并行。

基于轮次的执行：每一轮中，所有 Agent 各自独立工作；轮次结束后进行共识投票。这种设计避免了 Agent 之间的实时干扰，同时保证了信息同步。

共识机制 ：Agent 输出必须包含明确的 [CONSENSUS: YES/NO] 标签。模糊措辞会默认为 NO------设计上宁可多讨论几轮，也不让含糊的结论蒙混过关。

5.3 启动一个 Council

最简用法------使用默认的 3 Agent（Architect + Engineer + Reviewer）：

python 复制代码

{
  "tool": "council_start",
  "args": {
    "task": "Build a REST API with authentication and rate limiting",
    "projectDir": "/tmp/my-api-project",
    "maxRounds": 10
  }
}

自定义 Council------指定角色、引擎、模型：

python 复制代码

const manager = new SessionManager();

const council = manager.councilStart(
  'Build a REST API with authentication',
  {
    agents: [
      {
        name: 'Architect',
        emoji: '🏗️',
        persona: 'System architect focused on scalability',
        engine: 'claude',
        model: 'opus'
      },
      {
        name: 'Engineer',
        emoji: '⚙️',
        persona: 'Implementation engineer focused on code quality',
        engine: 'claude',
        model: 'sonnet'
      },
      {
        name: 'Reviewer',
        emoji: '🔍',
        persona: 'Code reviewer focused on bugs and security',
        engine: 'claude',
        model: 'sonnet'
      },
    ],
    maxRounds: 10,
    projectDir: '/tmp/my-api-project',
  }
);

5.4 混合引擎 Council------最强配置

真正让人兴奋的是，你可以在同一个 Council 里混合不同引擎：

python 复制代码

const council = manager.councilStart('Build a REST API with auth', {
  agents: [
    {
      name: 'Planner',
      emoji: '🟠',
      persona: 'Requirements & architecture',
      engine: 'claude',     // Claude 做规划
      model: 'opus'
    },
    {
      name: 'Generator',
      emoji: '🟢',
      persona: 'Implementation per plan',
      engine: 'codex',      // Codex 做实现
      model: 'o4-mini'
    },
    {
      name: 'Evaluator',
      emoji: '🔵',
      persona: 'Independent verification',
      engine: 'claude',     // Claude 做审查
      model: 'sonnet'
    },
  ],
  maxRounds: 10,
  projectDir: '/tmp/api-project',
});

这就像一个真实的技术团队：CTO 用深度思考做架构（Opus），高级工程师快速出活（Codex），技术经理审查把关（Sonnet）。

5.5 Council 完整生命周期

python 复制代码

// 1. 启动
const council = manager.councilStart('任务描述', config);

// 2. 轮询状态------每 60 秒检查一次
let councilStatus;
do {
  await new Promise(r => setTimeout(r, 60000));
  councilStatus = manager.councilStatus(council.id);
  console.log(`Round ${councilStatus.currentRound}, ` +
              `Consensus: ${councilStatus.consensus}`);
} while (!councilStatus?.completed);

// 3. 中途注入指导（可选但强大）
manager.councilInject(council.id,
  'Please also add input validation');

// 4. 审查结果------看变更文件、分支、计划、摘要
const review = manager.councilReview(council.id);
console.log('Changed files:', review.changedFiles);
console.log('Branches:', review.branches);

// 5a. 满意 → 接受（清理 worktree、分支、plan.md）
manager.councilAccept(council.id);

// 5b. 不满意 → 拒绝（附带反馈，Council 可重试）
manager.councilReject(council.id,
  'Need better error handling');

⚠️ 注意：Council 共识要求 Agent 输出明确的 [CONSENSUS: YES/NO] 标签------模糊的措辞会默认为 NO。此外，收件箱已投递的消息不会保留在收件箱历史中（只有排队的消息会出现）。

5.6 Council 系统提示与日志

Council 系统提示从 configs/council-system-prompt.md 加载，支持热编辑。它包含 9 个章程部分，经过大量多 Agent 协作测试调优。所有 Council 会话的记录保存到 ~/.openclaw/council-logs/council-<timestamp>.md，便于事后分析。

六、实战案例：用 Council 开发密码生成器 CLI

理论说了这么多，来看真实项目。我们用 Council 多智能体协作，从零开发一个生产级的密码生成器 CLI 工具------ PassGen CLI。

6.1 Council 团队配置

5 个 AI Agent，各司其职：

|-------------------|------------|------------------|----------------|
| 角色 | 模型 | 职责 | 为什么选这个模型？ |
| 📊 ProductManager | Sonnet 4.5 | 需求分析、功能定义、验收 | 需求分析不需要最强模型 |
| 🏗️ Architect | Opus 4.5 | 架构设计、技术选型、代码审查 | 架构需要最深度思考 |
| 💻 Developer | Sonnet 4.5 | 代码实现、最佳实践 | 编码能力够用，性价比高 |
| 🧪 QA_Engineer | Sonnet 4.5 | 测试策略、测试用例、质量保证 | 测试用 Sonnet 够了 |
| 📝 TechWriter | Haiku 4.5 | 文档编写、README、使用示例 | 文档类任务 Haiku 就行 |

启动配置：

python 复制代码

council_start({
  task: "设计和实现一个功能完整的 CLI 密码生成器，包括密码学安全随机数、" +
        "自定义字符类型、相似字符排除、强度评估和完整的测试覆盖",
  projectDir: "~/projects/password-generator",
  agents: [
    {
      name: "ProductManager",
      emoji: "📊",
      persona: "产品经理。从用户角度分析需求，定义 MVP 功能和验收标准。",
      engine: "claude",
      model: "claude-sonnet-4.5"
    },
    {
      name: "Architect",
      emoji: "🏗️",
      persona: "软件架构师。设计模块化架构，确保密码学安全性。",
      engine: "claude",
      model: "claude-opus-4.5"
    },
    {
      name: "Developer",
      emoji: "💻",
      persona: "Node.js 开发专家。实现高质量代码，使用 crypto 模块。",
      engine: "claude",
      model: "claude-sonnet-4.5"
    },
    {
      name: "QA_Engineer",
      emoji: "🧪",
      persona: "测试工程师。编写全面的单元测试，覆盖率 > 80%。",
      engine: "claude",
      model: "claude-sonnet-4.5"
    },
    {
      name: "TechWriter",
      emoji: "📝",
      persona: "技术文档专家。编写清晰完整的 README 和使用示例。",
      engine: "claude",
      model: "claude-haiku-4.5"
    }
  ],
  maxRounds: 15,
  agentTimeoutMs: 1800000,
  maxTurnsPerAgent: 30,
  maxBudgetUsd: 8.0,
  defaultPermissionMode: "bypassPermissions"
});

6.2 协作过程实录

Round 1: 需求分析与架构设计

ProductManager 首先从用户视角定义了需求：

复制代码

用户故事：
1. 作为用户，我想快速生成安全的随机密码
2. 作为用户，我想自定义密码长度（4-128 字符）
3. 作为用户，我想选择字符类型（大小写、数字、符号）
4. 作为用户，我想排除容易混淆的字符（如 i, l, 1, o, 0, O）

MVP 功能（P0 优先级）：
✅ 生成随机密码
✅ 自定义长度
✅ 选择字符类型
✅ 排除相似字符
✅ 密码强度评估

验收标准：
- 使用密码学安全的随机数生成器（不用 Math.random()）
- 支持命令行参数
- 彩色输出
- 完整的单元测试（覆盖率 > 80%）

Architect 随即提出了技术架构：

复制代码

技术选型：
- CLI 框架: Commander.js（成熟、零配置）
- 彩色输出: Chalk v4（CommonJS 兼容）
- 核心逻辑: Node.js crypto.randomBytes()（密码学安全）

模块划分：
src/
├── index.js          # CLI 入口，Commander.js 参数解析
└── generator.js      # 核心密码生成逻辑
    ├── generatePassword()     # 主函数
    ├── estimateStrength()     # 强度评估
    ├── getRandomInt()         # 安全随机数
    └── ensureCharacterTypes() # 确保字符类型完整性

核心设计原则：
1. 密码学安全：使用 crypto.randomBytes()，禁用 Math.random()
2. 拒绝采样：避免随机数偏差（模数偏差问题）
3. 可测试性：所有函数可独立单元测试

QA_Engineer 同步制定了 28 个测试用例的测试策略：

复制代码

测试覆盖规划（28 个用例）：
- generatePassword: 12 个（默认/自定义/边界/唯一性/类型确保）
- estimateStrength: 7 个（结构/弱/中/强/熵值/长度/混合）
- 字符集验证: 5 个
- 相似字符排除: 4 个

Round 2-3: 核心代码实现

Developer 根据架构方案开始编码。核心的密码生成函数如下：

python 复制代码

// src/generator.js --- 核心逻辑
const crypto = require('crypto');

// 字符集定义
const CHAR_SETS = {
  lowercase: 'abcdefghijklmnopqrstuvwxyz',
  uppercase: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ',
  numbers: '0123456789',
  symbols: '!@#$%^&*()_+-=[]{}|;:,.<>?'
};

// 容易混淆的相似字符
const SIMILAR_CHARS = {
  lowercase: 'ilo',
  uppercase: 'IO',
  numbers: '01'
};

function generatePassword(options = {}) {
  const {
    length = 16,
    lowercase = true,
    uppercase = true,
    numbers = true,
    symbols = true,
    excludeSimilar = false
  } = options;

  // 验证长度边界
  if (length < 4) throw new Error('Password length must be at least 4');
  if (length > 128) throw new Error('Password length cannot exceed 128');

  // 构建字符池------如果启用了排除相似字符，过滤掉
  let charPool = '';
  if (lowercase) {
    let chars = CHAR_SETS.lowercase;
    if (excludeSimilar) {
      chars = chars.split('')
        .filter(c => !SIMILAR_CHARS.lowercase.includes(c)).join('');
    }
    charPool += chars;
  }
  // uppercase, numbers, symbols 同理...

  if (charPool.length === 0) {
    throw new Error('At least one character type must be selected');
  }

  // 使用 crypto 生成安全随机密码
  const password = Array.from({ length }, () => {
    const randomIndex = getRandomInt(0, charPool.length);
    return charPool[randomIndex];
  }).join('');

  // 确保密码包含每种选中的字符类型
  return ensureCharacterTypes(password, options);
}

这里最值得关注的是 getRandomInt 函数------它使用拒绝采样来确保均匀分布：

python 复制代码

function getRandomInt(min, max) {
  const range = max - min;
  const bytesNeeded = Math.ceil(Math.log2(range) / 8);
  const cutoff = Math.floor((256 ** bytesNeeded) / range) * range;
  const bytes = crypto.randomBytes(bytesNeeded);
  let value = 0;

  for (let i = 0; i < bytesNeeded; i++) {
    value = (value << 8) + bytes[i];
  }

  // 关键：拒绝采样避免模数偏差
  // 如果随机值落在 cutoff 之外，重新生成
  if (value >= cutoff) {
    return getRandomInt(min, max);
  }

  return min + (value % range);
}

⚠️ 为什么不能直接用 Math.random()？因为 Math.random() 使用伪随机数生成器（PRNG），不是密码学安全的。攻击者理论上可以通过分析输出序列预测后续的随机数。crypto.randomBytes() 使用操作系统的熵源，是密码学安全的。

密码强度评估函数：

python 复制代码

function estimateStrength(password) {
  let score = 0;
  const length = password.length;

  // 长度评分（≥8: +1, ≥12: +1, ≥16: +1）
  if (length >= 8) score += 1;
  if (length >= 12) score += 1;
  if (length >= 16) score += 1;

  // 字符类型评分（每种 +1）
  if (/[a-z]/.test(password)) score += 1;
  if (/[A-Z]/.test(password)) score += 1;
  if (/[0-9]/.test(password)) score += 1;
  if (/[^a-zA-Z0-9]/.test(password)) score += 1;

  // 计算熵值 = log2(字符集大小 ^ 长度)
  const charsetSize =
    (/[a-z]/.test(password) ? 26 : 0) +
    (/[A-Z]/.test(password) ? 26 : 0) +
    (/[0-9]/.test(password) ? 10 : 0) +
    (/[^a-zA-Z0-9]/.test(password) ? 32 : 0);

  const entropy = Math.floor(Math.log2(charsetSize ** length));

  // 评级：≤3 Weak(红), ≤5 Medium(黄), >5 Strong(绿)
  let level, color;
  if (score <= 3) { level = 'Weak'; color = 'red'; }
  else if (score <= 5) { level = 'Medium'; color = 'yellow'; }
  else { level = 'Strong'; color = 'green'; }

  return { score, level, color, entropy };
}

CLI 入口（src/index.js）使用 Commander.js + Chalk 实现彩色输出：

python 复制代码

#!/usr/bin/env node
const { Command } = require('commander');
const chalk = require('chalk');
const { generatePassword, estimateStrength } = require('./generator');

const program = new Command();
program
  .name('passgen')
  .description('Generate secure random passwords')
  .version('1.0.0')
  .argument('[length]', 'Password length (default: 16)', '16')
  .option('-x, --exclude-similar', 'Exclude similar chars (i,l,1,o,0,O)')
  .option('-c, --count <number>', 'Generate multiple passwords', '1')
  .option('--no-symbols', 'Disable symbols')
  .action((length, options) => {
    const genOptions = {
      length: parseInt(length, 10),
      lowercase: options.lowercase,
      uppercase: options.uppercase,
      numbers: options.numbers,
      symbols: options.symbols,
      excludeSimilar: options.excludeSimilar
    };

    // 显示配置面板
    displayConfig(genOptions, parseInt(options.count, 10));

    // 生成并显示密码
    for (let i = 0; i < parseInt(options.count, 10); i++) {
      const password = generatePassword(genOptions);
      const strength = estimateStrength(password);
      displayPassword(password, strength, i + 1, parseInt(options.count, 10));
    }
  });

program.parse();

Round 4: 测试验证

QA_Engineer 编写了完整的测试套件（28 个用例）并全部通过：

复制代码

$ npm test

Test Suites: 1 passed, 1 total
Tests:       28 passed, 28 total
Snapshots:   0 total
Time:        0.856 s
Coverage:    > 80% ✅

测试覆盖了所有关键路径：

python 复制代码

describe('Password Generator', () => {
  describe('generatePassword', () => {
    test('generates password with default options', () => {
      const password = generatePassword();
      expect(password).toHaveLength(16);
    });

    test('respects custom length', () => {
      const password = generatePassword({ length: 24 });
      expect(password).toHaveLength(24);
    });

    test('throws on length < 4', () => {
      expect(() => generatePassword({ length: 2 })).toThrow();
    });

    test('excludes similar characters when option is set', () => {
      const password = generatePassword({
        length: 100,  // 长密码增加覆盖
        excludeSimilar: true
      });
      expect(password).not.toMatch(/[iloIO01]/);
    });

    test('ensures all selected character types are present', () => {
      // 多次生成验证
      for (let i = 0; i < 50; i++) {
        const password = generatePassword({ length: 8 });
        expect(password).toMatch(/[a-z]/);
        expect(password).toMatch(/[A-Z]/);
        expect(password).toMatch(/[0-9]/);
      }
    });
  });

  describe('estimateStrength', () => {
    test('rates short password as Weak', () => {
      const result = estimateStrength('abc');
      expect(result.level).toBe('Weak');
    });

    test('rates long complex password as Strong', () => {
      const result = estimateStrength('aB3$xY7!kL9@mN2#');
      expect(result.level).toBe('Strong');
    });

    test('calculates entropy correctly', () => {
      const result = estimateStrength('abcd1234');
      expect(result.entropy).toBeGreaterThan(0);
    });
  });
});

Round 5: 文档与最终审查

TechWriter 编写了完整的 README（包含安装、快速开始、命令参考、安全性说明），Architect 做了最终代码审查，ProductManager 完成验收。

6.3 最终交付物

复制代码

password-generator/
├── src/
│   ├── index.js           # CLI 入口 (4716 字节)
│   └── generator.js       # 核心逻辑 (5128 字节)
├── tests/
│   └── generator.test.js  # 测试套件 (7033 字节)
├── package.json           # 项目配置
├── jest.config.js         # Jest 配置
├── .eslintrc.js          # ESLint 配置
├── .gitignore
└── README.md             # 完整文档 (5189 字节)

6.4 运行效果

6.5 质量指标

|-----------|--------|--------|----|
| 指标 | 目标 | 实际 | 状态 |
| 代码覆盖率 | > 80% | > 80% | ✅ |
| 测试用例数 | - | 28 | ✅ |
| 测试通过率 | 100% | 100% | ✅ |
| ESLint 警告 | 0 | 0 | ✅ |
| 代码行数 | - | ~500 | ✅ |
| 文档完整度 | 100% | 100% | ✅ |

💡 核心要点 ：Council 的价值不在于速度，而在于质量和完整性。5 个 Agent 各自专注自己的领域，产出的代码有架构设计、有安全考量、有完整测试、有详细文档------这是单个 Agent 很难同时做到的。

结语

OpenClaw + Claude Code 插件的核心价值可以用一句话概括：它把 Claude Code CLI 从一个"单兵工具"升级成了一个"AI 研发团队"。

传统的 AI 辅助编程是：你问一个问题，AI 回答一段代码，你复制粘贴，跑测试，发现问题，再问------本质上还是人在主导流程。

而 OpenClaw + Claude Code 的全链路方案是：你描述一个需求，多个 AI Agent 自动分工（架构、编码、测试、文档），在隔离的 git worktree 中并行工作，通过轮次讨论达成共识，最终交付一个完整的、经过多轮审查的代码------你只需要最后审查和拍板。

这不是未来，这是现在就能用的工具。

如果你正在做复杂项目开发、需要多角色协作、希望有完整的测试和文档，那么 OpenClaw + Claude Code Council 值得你花时间学习和尝试。如果你只是写个脚本、修个 bug，那直接用 Claude Code CLI 就够了------选对工具比选好工具更重要。

服务器配置建议 ：Council 模式下多个 Agent 并行运行，内存消耗显著增加。建议至少 8GB RAM （如腾讯云 4C8G 轻量服务器），如果要跑 3+ Agent 并行，16GB 更稳妥。

参考资源：

OpenClaw 官方文档

Claude Code 官方文档

openclaw-claude-code 插件 GitHub