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

┌─────────────────────────────────────────────────────────────┐
│                  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)                                 │
└─────────────────────────────────────────────────────────────┘

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             → 跨会话消息传递

# 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

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

# 全局安装
npm install -g @enderfga/openclaw-claude-code
# 启动独立服务（暴露 OpenAI 兼容 API）
claude-code-skill serve

# 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/

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

# 重启 Gateway
openclaw gateway restart
# 验证插件加载
openclaw plugins list | grep -i claude
# 运行诊断
openclaw plugins doctor

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
  }'

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
});

// 定向通信——让 planner 给 coder 发需求
await manager.sessionSendTo('planner', 'coder',
  'The auth module needs rate limiting');
// 广播——monitor 向所有会话发警报
await manager.sessionSendTo('monitor', '*', 'Build failed!');

// 先规划，再执行
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 去执行

┌─────────────────────────────────────────────────┐
│                 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     │
└─────────────────────────────────────────────────┘

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

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',
  }
);

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',
});

// 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_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"
});

用户故事：
1. 作为用户，我想快速生成安全的随机密码
2. 作为用户，我想自定义密码长度（4-128 字符）
3. 作为用户，我想选择字符类型（大小写、数字、符号）
4. 作为用户，我想排除容易混淆的字符（如 i, l, 1, o, 0, O）
MVP 功能（P0 优先级）：
✅ 生成随机密码
✅ 自定义长度
✅ 选择字符类型
✅ 排除相似字符
✅ 密码强度评估
验收标准：
- 使用密码学安全的随机数生成器（不用 Math.random()）
- 支持命令行参数
- 彩色输出
- 完整的单元测试（覆盖率 > 80%）

技术选型：
- 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. 可测试性：所有函数可独立单元测试

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

// 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);
}

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);
}

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 };
}

#!/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();

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

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);
    });
  });
});

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 字节)