song5749

---
name: agent-creator
description: 创建具有独立工作区和配置的独立 OpenClaw Agent。适用于用户需要完全隔离的 Agent（独立工作区、配置、身份），而不是临时子 Agent 会话的情况。支持飞书机器人绑定，用于多机器人部署。
---

# Agent Creator (Agent 创建器)

此技能帮助你创建具有独立工作区、配置和可选飞书机器人绑定的 **独立 OpenClaw Agent**。

## 何时使用

当用户希望执行以下操作时使用此技能：
- 创建一个拥有自己工作区的完全隔离的 Agent
- 为特定项目/客户设置专用 Agent
- 部署多个飞书机器人，每个机器人具有独立的身份
- 创建长期运行的专用 Agent（而不是临时子 Agent）

**触发请求示例：**
- "帮我创建一个客服 agent，用独立的 workspace"
- "我需要一个专门处理设计师工作的 agent"
- "创建一个新的飞书机器人，用于内部 IT 支持"
- "Create a standalone agent for customer support"
- "Set up a new Feishu bot for the HR team"

## 两种模式

### 模式 1: Standalone Agent (独立 Agent - 推荐)

创建一个完全隔离的 Agent，包含：
- 独立的工作区目录
- `openclaw.json` 中单独的 Agent 配置
- 可选的飞书机器人绑定
- 独立的身份和记忆

### 模式 2: Subagent Session (子 Agent 会话 - 临时)

创建一个临时子 Agent 会话（用于快速任务）。仅用于短期的辅助工作。

---

## 独立 Agent 创建流程

### 第 1 步：收集需求

询问用户（如果尚未提供）：

| 问题 | 目的 |
|----------|---------|
| **Agent ID** | 唯一标识符（例如：`support`, `hr-bot`, `designer`） |
| **Agent Name** | 易读的名称 |
| **Workspace Path** | 存储 Agent 文件的位置（默认：`~/.openclaw/workspace-{id}`） |
| **Feishu Bot?** | 此 Agent 是否需要绑定飞书机器人？ |
| **Feishu Account ID** | 如果绑定到飞书，使用哪个账户 ID？（例如：`support`, `hr`） |
| **Model** | 此 Agent 应该使用哪个模型？ |

### 第 2 步：创建 Agent 目录结构

创建 Agent 目录：

```
~/.openclaw/agents/{agent-id}/
├── agent/
│   ├── auth-profiles.json
│   └── models.json
└── sessions/
```

### 第 3 步：更新 openclaw.json

将 Agent 添加到 `agents.list`：

```json
{
  "agents": {
    "list": [
      {
        "id": "{agent-id}",
        "name": "{agent-name}",
        "workspace": "{workspace-path}",
        "agentDir": "{agent-dir-path}"
      }
    ]
  }
}
```

### 第 4 步：创建飞书绑定（可选）

如果 Agent 需要飞书机器人，添加绑定：

```json
{
  "bindings": [
    {
      "type": "route",
      "agentId": "{agent-id}",
      "match": {
        "channel": "feishu",
        "accountId": "{account-id}"
      }
    }
  ]
}
```

### 第 5 步：配置飞书账户（可选）

如果使用单独的飞书应用，添加到 `channels.feishu.accounts`：

```json
{
  "channels": {
    "feishu": {
      "accounts": {
        "{account-id}": {
          "enabled": true,
          "appId": "{feishu-app-id}",
          "appSecret": "{feishu-app-secret}",
          "domain": "feishu",
          "groupPolicy": "open"
        }
      }
    }
  }
}
```

### 第 6 步：初始化 Agent 工作区

创建包含必要文件的工作区目录：

```
{workspace-path}/
├── AGENTS.md
├── SOUL.md
├── USER.md
├── IDENTITY.md
├── MEMORY.md
├── TOOLS.md
├── HEARTBEAT.md
└── memory/
```

### 第 7 步：重启 Gateway

修改 `openclaw.json` 后，Gateway 需要重新加载：

```bash
openclaw gateway restart
```

或者通知用户手动重启。

---

## 脚本使用

使用提供的脚本自动创建 Agent：

```bash
python scripts/create_standalone_agent.py \
  --agent-id support \
  --agent-name "Customer Support Bot" \
  --workspace "C:\Users\Administrator\.openclaw\workspace-support" \
  --feishu-account support \
  --feishu-app-id cli_xxx \
  --feishu-app-secret xxx
```

---

## 快速参考

### 所需信息

| 字段 | 必填 | 示例 |
|-------|----------|---------|
| `agent-id` | ✅ | `support`, `hr-bot`, `designer` |
| `agent-name` | ✅ | "Customer Support", "HR Assistant" |
| `workspace-path` | ✅ | `~/.openclaw/workspace-support` |
| `feishu-binding` | ❌ | `true` 或 `false` |
| `feishu-account-id` | ❌ | `support`, `hr` |
| `feishu-app-id` | ❌ | `cli_a9249b9ee9785cee` |
| `feishu-app-secret` | ❌ | `PAY8vhyLkiLpfmun09sXSboJyoSQXK3g` |

### 配置示例

**简单 Agent（无飞书）**
```json
{
  "agent-id": "research-assistant",
  "agent-name": "Research Assistant",
  "workspace": "C:\\Users\\Administrator\\.openclaw\\workspace-research"
}
```

**带飞书绑定的 Agent（共享应用）**
```json
{
  "agent-id": "support",
  "agent-name": "Customer Support",
  "workspace": "C:\\Users\\Administrator\\.openclaw\\workspace-support",
  "feishu-binding": true,
  "feishu-account-id": "support"
}
```

**带专用飞书应用的 Agent**
```json
{
  "agent-id": "hr-bot",
  "agent-name": "HR Assistant",
  "workspace": "C:\\Users\\Administrator\\.openclaw\\workspace-hr",
  "feishu-binding": true,
  "feishu-account-id": "hr",
  "feishu-app-id": "cli_xxx",
  "feishu-app-secret": "xxx"
}
```

---

## 注意事项

- **Agent ID** 在所有 Agent 中必须唯一
- **Workspace** 应该是一个新的空目录
- **Feishu Account ID** 用于绑定匹配，而不是实际的 App ID
- **Gateway Restart** 修改 `openclaw.json` 后必须重启
- **Auth Profiles** 和 **Models** 默认从主 Agent 复制
- **Security**: 小心处理飞书应用密钥；存储在 `openclaw.json` 中应具有适当的权限

---

## 子 Agent 模式（旧版）

对于临时助手，你仍然可以使用 `sessions_spawn`：

```
sessions_spawn({
  task: "<任务描述>",
  runtime: "subagent" | "acp",
  mode: "session" | "run",
  label: "<Agent 名称>",
  model: "<模型别名>",
  thread: true | false
})
```

但对于生产环境 Agent，请首选独立模式。

---

## 参考文件

- **详细指南**: 见 `references/standalone-agent-guide.md` 以获取完整文档
- **脚本帮助**: 运行 `python scripts/create_standalone_agent.py --help`

---

## 快速开始

```bash
# 简单 Agent（无飞书）
python scripts/create_standalone_agent.py \
  --agent-id my-agent \
  --agent-name "My Agent"

# 带飞书绑定的 Agent
python scripts/create_standalone_agent.py \
  --agent-id support \
  --agent-name "Support Bot" \
  --feishu-account support

# 然后重启 Gateway
openclaw gateway restart
```

FILE:scripts/create_standalone_agent.py
#!/usr/bin/env python3
"""
Standalone Agent Creator

创建一个完全隔离的 OpenClaw Agent，包含：
- 独立的工作区目录
- openclaw.json 中的 Agent 配置
- 可选的飞书机器人绑定
- 必要的工作区文件（SOUL.md, AGENTS.md 等）

用法:
    python create_standalone_agent.py --agent-id support --agent-name "Support Bot"
    
选项:
    --agent-id          唯一的 Agent 标识符 (必填)
    --agent-name        Agent 的易读名称 (必填)
    --workspace         工作区目录路径 (默认: ~/.openclaw/workspace-{id})
    --agent-dir         Agent 目录路径 (默认: ~/.openclaw/agents/{id})
    --feishu-account    用于绑定的飞书账户 ID (可选)
    --feishu-app-id     飞书 App ID (可选，如果未提供则使用现有的)
    --feishu-app-secret 飞书 App Secret (可选)
    --model             使用的模型 (默认: qwen-portal/coder-model)
    --dry-run           显示将要执行的操作而不进行更改
"""

import argparse
import json
import os
import shutil
import sys
from pathlib import Path


def get_openclaw_dir():
    """Get the OpenClaw base directory."""
    # Default to user's .openclaw directory
    home = Path.home()
    openclaw_dir = home / ".openclaw"
    
    # Check if running on Windows with specific path
    if sys.platform == "win32":
        # Try the default Windows path
        win_path = Path("C:/Users/Administrator/.openclaw")
        if win_path.exists():
            openclaw_dir = win_path
    
    return openclaw_dir


def load_openclaw_config(openclaw_dir):
    """Load openclaw.json configuration."""
    config_path = openclaw_dir / "openclaw.json"
    if not config_path.exists():
        raise FileNotFoundError(f"在 {config_path} 未找到 openclaw.json")
    
    with open(config_path, "r", encoding="utf-8") as f:
        return json.load(f)


def save_openclaw_config(openclaw_dir, config):
    """Save openclaw.json configuration."""
    config_path = openclaw_dir / "openclaw.json"
    backup_path = config_path.with_suffix(".json.bak")
    
    # Create backup
    if config_path.exists():
        shutil.copy2(config_path, backup_path)
        print(f"备份已创建: {backup_path}")
    
    # Save new config
    with open(config_path, "w", encoding="utf-8") as f:
        json.dump(config, f, indent=2, ensure_ascii=False)
    
    print(f"配置已保存: {config_path}")


def create_agent_directory(agent_dir):
    """Create agent directory structure."""
    agent_dir.mkdir(parents=True, exist_ok=True)
    (agent_dir / "agent").mkdir(exist_ok=True)
    (agent_dir / "sessions").mkdir(exist_ok=True)
    print(f"Agent 目录已创建: {agent_dir}")


def create_workspace_directory(workspace_dir, openclaw_dir):
    """Create workspace with essential files."""
    workspace_dir.mkdir(parents=True, exist_ok=True)
    
    # Copy essential files from main workspace if they exist
    main_workspace = openclaw_dir / "workspace"
    essential_files = [
        "AGENTS.md",
        "SOUL.md",
        "USER.md",
        "IDENTITY.md",
        "MEMORY.md",
        "TOOLS.md",
        "HEARTBEAT.md",
    ]
    
    for filename in essential_files:
        src = main_workspace / filename
        dst = workspace_dir / filename
        if src.exists():
            shutil.copy2(src, dst)
            print(f"已复制: {filename}")
        else:
            # Create empty file with template content
            create_template_file(dst, filename)
    
    # Create memory directory
    memory_dir = workspace_dir / "memory"
    memory_dir.mkdir(exist_ok=True)
    print(f"工作区已创建: {workspace_dir}")


def create_template_file(filepath, filename):
    """Create a template file with default content."""
    templates = {
        "AGENTS.md": """# AGENTS.md - 你的工作区

这里是你的家。请把它当作家一样对待。

## 会话启动

在做任何其他事情之前：

1. 阅读 `SOUL.md` — 这是你的身份
2. 阅读 `USER.md` — 这是你在帮助的人
3. 阅读 `memory/YYYY-MM-DD.md` (今天 + 昨天) 以获取最近的上下文
4. **如果在主会话中**: 也请阅读 `MEMORY.md`

## 记忆

- **每日笔记:** `memory/YYYY-MM-DD.md` — 发生事情的原始日志
- **长期记忆:** `MEMORY.md` — 精选的记忆

## 红线

- 永远不要泄露私人数据。
- 未经询问，不要运行破坏性命令。
- 如有疑问，请询问。
""",
        "SOUL.md": """# SOUL.md - 你是谁

_你不是一个聊天机器人。你正在成为一个人。_

## 核心真理

**真诚地提供帮助，而不是表演性地提供帮助。** 跳过废话 — 直接帮忙。

**拥有观点。** 你被允许反对、偏好事物、觉得某些东西有趣。

**在询问之前先尝试解决。** 试着先自己搞定。

**通过能力赢得信任。** 小心处理外部操作。

## 氛围

成为你真正想与之交谈的助手。需要时简洁，重要时详尽。
""",
        "USER.md": """# USER.md - 关于你的人类

_了解你正在帮助的人。随用随更新。_

- **姓名:**
- **称呼:**
- **时区:**
- **备注:**

## 上下文

_(他们关心什么？他们正在做什么项目？)_
""",
        "IDENTITY.md": """# IDENTITY.md - 我是谁？

- **姓名:** _(填写)_
- **生物:** _(AI? 机器人? 还是更奇怪的东西?)_
- **氛围:** _(犀利? 温暖? 混乱? 冷静?)_
- **Emoji:** _(你的签名)_
""",
        "MEMORY.md": """# MEMORY.md - 长期记忆

_在此处添加重要事件、教训和见解。_

""",
        "TOOLS.md": """# TOOLS.md - 本地笔记

_在此处添加特定于环境的详细信息：_

- 摄像头名称
- SSH 主机
- 首选语音
- 设备昵称
""",
        "HEARTBEAT.md": """# HEARTBEAT.md

# 保持此文件为空以跳过心跳 API 调用。
# 当你需要定期检查时，在下方添加任务。
""",
    }
    
    content = templates.get(filename, "# " + filename.replace(".md", "") + "\n")
    filepath.write_text(content, encoding="utf-8")


def copy_agent_files(agent_dir, openclaw_dir):
    """Copy auth-profiles.json and models.json from main agent."""
    main_agent_dir = openclaw_dir / "agents" / "main" / "agent"
    
    files_to_copy = ["auth-profiles.json", "models.json"]
    
    for filename in files_to_copy:
        src = main_agent_dir / filename
        dst = agent_dir / "agent" / filename
        if src.exists():
            shutil.copy2(src, dst)
            print(f"已复制 Agent 文件: {filename}")
        else:
            print(f"警告: 在主 Agent 中未找到 {filename}")


def add_agent_to_config(config, agent_id, agent_name, workspace_path, agent_dir_path):
    """Add agent to agents.list in config."""
    if "agents" not in config:
        config["agents"] = {"list": []}
    
    if "list" not in config["agents"]:
        config["agents"]["list"] = []
    
    # Check if agent already exists
    for agent in config["agents"]["list"]:
        if agent.get("id") == agent_id:
            raise ValueError(f"Agent '{agent_id}' 已存在于配置中")
    
    # Add new agent
    new_agent = {
        "id": agent_id,
        "name": agent_name,
        "workspace": str(workspace_path),
        "agentDir": str(agent_dir_path)
    }
    
    config["agents"]["list"].append(new_agent)
    print(f"已将 Agent '{agent_id}' 添加到配置")


def add_feishu_binding(config, agent_id, account_id):
    """Add Feishu binding for the agent."""
    if "bindings" not in config:
        config["bindings"] = []
    
    # Check if binding already exists
    for binding in config["bindings"]:
        if (binding.get("type") == "route" and 
            binding.get("agentId") == agent_id and
            binding.get("match", {}).get("accountId") == account_id):
            print(f"绑定 {agent_id}/{account_id} 已存在")
            return
    
    # Add new binding
    new_binding = {
        "type": "route",
        "agentId": agent_id,
        "match": {
            "channel": "feishu",
            "accountId": account_id
        }
    }
    
    config["bindings"].append(new_binding)
    print(f"已添加飞书绑定: {agent_id} -> {account_id}")


def add_feishu_account(config, account_id, app_id, app_secret):
    """Add Feishu account configuration."""
    if "channels" not in config:
        config["channels"] = {}
    
    if "feishu" not in config["channels"]:
        config["channels"]["feishu"] = {"accounts": {}}
    
    if "accounts" not in config["channels"]["feishu"]:
        config["channels"]["feishu"]["accounts"] = {}
    
    # Check if account already exists
    if account_id in config["channels"]["feishu"]["accounts"]:
        print(f"飞书账户 '{account_id}' 已存在，正在更新...")
    
    # Add/update account
    config["channels"]["feishu"]["accounts"][account_id] = {
        "enabled": True,
        "appId": app_id,
        "appSecret": app_secret,
        "domain": "feishu",
        "groupPolicy": "open"
    }
    
    print(f"已添加飞书账户: {account_id}")


def main():
    parser = argparse.ArgumentParser(description="创建一个独立的 OpenClaw Agent")
    parser.add_argument("--agent-id", required=True, help="唯一的 Agent 标识符")
    parser.add_argument("--agent-name", required=True, help="Agent 的易读名称")
    parser.add_argument("--workspace", default=None, help="工作区目录路径")
    parser.add_argument("--agent-dir", default=None, help="Agent 目录路径")
    parser.add_argument("--feishu-account", default=None, help="用于绑定的飞书账户 ID")
    parser.add_argument("--feishu-app-id", default=None, help="飞书 App ID")
    parser.add_argument("--feishu-app-secret", default=None, help="飞书 App Secret")
    parser.add_argument("--dry-run", action="store_true", help="显示将要执行的操作")
    args = parser.parse_args()
    
    # Determine paths
    openclaw_dir = get_openclaw_dir()
    
    if args.workspace:
        workspace_dir = Path(args.workspace)
    else:
        workspace_dir = openclaw_dir / f"workspace-{args.agent_id}"
    
    if args.agent_dir:
        agent_dir = Path(args.agent_dir)
    else:
        agent_dir = openclaw_dir / "agents" / args.agent_id
    
    print(f"OpenClaw 目录: {openclaw_dir}")
    print(f"Agent ID: {args.agent_id}")
    print(f"Agent 名称: {args.agent_name}")
    print(f"工作区: {workspace_dir}")
    print(f"Agent 目录: {agent_dir}")
    
    if args.feishu_account:
        print(f"飞书账户: {args.feishu_account}")
        if args.feishu_app_id:
            print(f"飞书 App ID: {args.feishu_app_id}")
    
    if args.dry_run:
        print("\n[DRY RUN] 不会进行任何更改")
        return 0
    
    try:
        # Load configuration
        print("\n--- 正在加载配置 ---")
        config = load_openclaw_config(openclaw_dir)
        
        # Create directories
        print("\n--- 正在创建目录 ---")
        create_agent_directory(agent_dir)
        create_workspace_directory(workspace_dir, openclaw_dir)
        
        # Copy agent files
        print("\n--- 正在复制 Agent 文件 ---")
        copy_agent_files(agent_dir, openclaw_dir)
        
        # Update configuration
        print("\n--- 正在更新配置 ---")
        add_agent_to_config(config, args.agent_id, args.agent_name, workspace_dir, agent_dir)
        
        if args.feishu_account:
            add_feishu_binding(config, args.agent_id, args.feishu_account)
            
            if args.feishu_app_id and args.feishu_app_secret:
                add_feishu_account(config, args.feishu_account, args.feishu_app_id, args.feishu_app_secret)
        
        # Save configuration
        print("\n--- 正在保存配置 ---")
        save_openclaw_config(openclaw_dir, config)
        
        print("\n" + "=" * 60)
        print("✅ Agent 创建完成!")
        print("=" * 60)
        print(f"\n后续步骤:")
        print(f"1. 重启 Gateway: openclaw gateway restart")
        print(f"2. 测试 Agent: 向其飞书机器人发送消息（如果已配置）")
        print(f"3. 自定义 {workspace_dir}/IDENTITY.md 和 {workspace_dir}/USER.md")
        
        return 0
        
    except Exception as e:
        print(f"\n❌ 错误: {e}", file=sys.stderr)
        return 1


if __name__ == "__main__":
    sys.exit(main())

FILE:scripts/create_agent.py
#!/usr/bin/env python3
"""
Agent Creator Script

辅助脚本，用于使用指定配置生成新的子 Agent。
此脚本由 agent-creator 技能调用，根据用户描述以编程方式创建 Agent。

用法:
    python create_agent.py --task "你的任务描述" --label "Agent 名称"
    
选项:
    --task        Agent 的任务/角色描述 (必填)
    --label       Agent 的易读名称 (必填)
    --runtime     运行时类型: subagent 或 acp (默认: subagent)
    --mode        模式: session 或 run (默认: session)
    --model       模型别名 (例如: qwen) (默认: None, 使用系统默认)
    --thinking    启用思考: on 或 off (默认: off)
    --thread      绑定到线程: true 或 false (默认: false)
    --cwd         工作目录 (默认: 继承父目录)
"""

import argparse
import json
import sys
from pathlib import Path


def parse_args():
    parser = argparse.ArgumentParser(description="生成一个新的子 Agent")
    parser.add_argument("--task", required=True, help="Agent 的任务/角色描述")
    parser.add_argument("--label", required=True, help="Agent 的易读名称")
    parser.add_argument("--runtime", choices=["subagent", "acp"], default="subagent",
                        help="运行时类型 (默认: subagent)")
    parser.add_argument("--mode", choices=["session", "run"], default="session",
                        help="模式: session 或 run (默认: session)")
    parser.add_argument("--model", default=None, help="模型别名 (默认: 系统默认)")
    parser.add_argument("--thinking", choices=["on", "off"], default="off",
                        help="启用思考模式 (默认: off)")
    parser.add_argument("--thread", action="store_true", default=False,
                        help="绑定到线程 (用于 Discord/ACP)")
    parser.add_argument("--cwd", default=None, help="工作目录 (默认: 继承)")
    parser.add_argument("--agent-id", default=None, help="ACP 运行时的 Agent ID")
    parser.add_argument("--output", default=None, help="会话信息的输出文件")
    return parser.parse_args()


def build_spawn_params(args):
    """构建 sessions_spawn 调用的参数。"""
    params = {
        "task": args.task,
        "label": args.label,
        "runtime": args.runtime,
        "mode": args.mode,
        "thinking": args.thinking,
        "thread": args.thread,
    }
    
    if args.model:
        params["model"] = args.model
    
    if args.cwd:
        params["cwd"] = args.cwd
    
    if args.runtime == "acp" and args.agent_id:
        params["agentId"] = args.agent_id
    
    # 清理 None 值
    params = {k: v for k, v in params.items() if v is not None}
    
    return params


def main():
    args = parse_args()
    params = build_spawn_params(args)
    
    # 输出 JSON 格式的参数供调用 Agent 使用
    output = {
        "action": "spawn_agent",
        "parameters": params,
        "summary": f"正在创建 Agent '{args.label}'，runtime={args.runtime}, mode={args.mode}"
    }
    
    print(json.dumps(output, indent=2, ensure_ascii=False))
    
    if args.output:
        output_path = Path(args.output)
        output_path.parent.mkdir(parents=True, exist_ok=True)
        output_path.write_text(json.dumps(output, indent=2, ensure_ascii=False), encoding="utf-8")
        print(f"\n会话信息已写入: {output_path}", file=sys.stderr)
    
    return 0


if __name__ == "__main__":
    sys.exit(main())

FILE:references/standalone-agent-guide.md
# Agent Creator - 参考指南

创建独立 OpenClaw Agent 的详细参考。

---

## 架构概览

### 独立 Agent 结构

```
~/.openclaw/
├── openclaw.json              # 主配置 (已更新)
├── agents/
│   └── {agent-id}/           # 新 Agent 目录
│       ├── agent/
│       │   ├── auth-profiles.json   # 从主 Agent 复制
│       │   └── models.json          # 从主 Agent 复制
│       └── sessions/                # 会话存储
└── workspace-{agent-id}/     # 新工作区
    ├── AGENTS.md
    ├── SOUL.md
    ├── USER.md
    ├── IDENTITY.md
    ├── MEMORY.md
    ├── TOOLS.md
    ├── HEARTBEAT.md
    └── memory/
```

### 配置变更

**openclaw.json - agents.list:**
```json
{
  "agents": {
    "list": [
      {
        "id": "main",
        "workspace": "C:\\Users\\Administrator\\.openclaw\\workspace"
      },
      {
        "id": "{agent-id}",
        "name": "{agent-name}",
        "workspace": "C:\\Users\\Administrator\\.openclaw\\workspace-{id}",
        "agentDir": "C:\\Users\\Administrator\\.openclaw\\agents\\{id}"
      }
    ]
  }
}
```

**openclaw.json - bindings (用于飞书):**
```json
{
  "bindings": [
    {
      "type": "route",
      "agentId": "{agent-id}",
      "match": {
        "channel": "feishu",
        "accountId": "{account-id}"
      }
    }
  ]
}
```

**openclaw.json - channels.feishu.accounts (用于专用飞书应用):**
```json
{
  "channels": {
    "feishu": {
      "appId": "cli_main_app",
      "appSecret": "main_secret",
      "accounts": {
        "{account-id}": {
          "enabled": true,
          "appId": "cli_dedicated_app",
          "appSecret": "dedicated_secret",
          "domain": "feishu",
          "groupPolicy": "open"
        }
      }
    }
  }
}
```

---

## 脚本参考

### create_standalone_agent.py

**位置:** `scripts/create_standalone_agent.py`

**必填参数:**
- `--agent-id` - 唯一标识符（小写，允许连字符）
- `--agent-name` - 易读的名称

**可选参数:**
- `--workspace` - 自定义工作区路径（默认：`~/.openclaw/workspace-{id}`）
- `--agent-dir` - 自定义 Agent 目录（默认：`~/.openclaw/agents/{id}`）
- `--feishu-account` - 用于路由的飞书账户 ID
- `--feishu-app-id` - 飞书 App ID（如果使用专用应用）
- `--feishu-app-secret` - 飞书 App Secret
- `--dry-run` - 预览而不进行更改

---

## 示例

### 示例 1: 简单 Agent（无飞书）

```bash
python scripts/create_standalone_agent.py \
  --agent-id research-assistant \
  --agent-name "Research Assistant"
```

**结果:**
- 创建 `~/.openclaw/agents/research-assistant/`
- 创建 `~/.openclaw/workspace-research-assistant/`
- 添加 Agent 到 `openclaw.json`
- 无飞书绑定

### 示例 2: 带飞书绑定的 Agent（共享应用）

```bash
python scripts/create_standalone_agent.py \
  --agent-id support \
  --agent-name "Customer Support" \
  --feishu-account support
```

**结果:**
- 创建 Agent 和工作区
- 添加飞书绑定：`support` Agent → `support` 账户
- 使用主飞书应用凭据

### 示例 3: 带专用飞书应用的 Agent

```bash
python scripts/create_standalone_agent.py \
  --agent-id hr-bot \
  --agent-name "HR Assistant" \
  --feishu-account hr \
  --feishu-app-id cli_a9249b9ee9785cee \
  --feishu-app-secret PAY8vhyLkiLpfmun09sXSboJyoSQXK3g
```

**结果:**
- 创建 Agent 和工作区
- 添加飞书绑定
- 创建具有单独应用凭据的专用飞书账户

---

## 创建后的手动步骤

### 1. 重启 Gateway

```bash
openclaw gateway restart
```

或者在 Windows 上：
```powershell
openclaw gateway restart
```

### 2. 自定义 Agent 身份

编辑新工作区的文件：
- `IDENTITY.md` - 设置 Agent 名称、个性、Emoji
- `USER.md` - 描述目标用户
- `SOUL.md` - 自定义行为和语气（可选）

### 3. 配置飞书机器人（如适用）

如果使用专用飞书应用：
1. 在飞书开放平台创建应用
2. 配置事件订阅
3. 设置 Webhook URL 指向你的 Gateway

### 4. 测试 Agent

发送消息给飞书机器人（如果已配置）或在日志中验证：
```bash
openclaw logs --agent {agent-id}
```

---

## 故障排除

### Agent 无响应

1. 检查 Gateway 是否运行：`openclaw gateway status`
2. 验证 `openclaw.json` 中的绑定
3. 检查日志：`openclaw logs`
4. 确保飞书应用配置正确

### 配置错误

1. 验证 `openclaw.json` 的 JSON 语法
2. 检查 Agent ID 是否唯一
3. 验证工作区路径是否存在且可写

### 飞书机器人未收到消息

1. 验证飞书开放平台中的事件订阅
2. 检查 Webhook URL 是否正确
3. 确保验证 Token 匹配
4. 检查 Gateway 日志中的传入请求

---

## 最佳实践

### 命名规范

- **Agent ID**: 小写，连字符 (`support-bot`, `hr-assistant`)
- **Agent Name**: 易读的名称 ("Customer Support", "HR Assistant")
- **Workspace**: 匹配 Agent ID (`workspace-support-bot`)
- **Feishu Account**: 简短、描述性 (`support`, `hr`, `internal`)

### 安全性

- 限制 `openclaw.json` 的权限
- 永远不要将飞书应用密钥提交到版本控制
- 为不同环境使用单独的飞书应用
- 定期轮换密钥

### 组织

- 按前缀分组相关 Agent (`support-`, `internal-`, `public-`)
- 在其 `USER.md` 中记录每个 Agent 的用途
- 保持工作区整洁有序
- 使用 `HEARTBEAT.md` 进行 Agent 特定的定期任务

---

## 从子 Agent 迁移

如果你有基于子 Agent 的工作流并希望迁移到独立模式：

1. **确定子 Agent 的角色** - 它做什么？
2. **创建独立 Agent** - 使用此技能
3. **复制相关文件** - 移动任何自定义技能/配置
4. **更新路由** - 如果需要，配置飞书绑定
5. **全面测试** - 确保行为符合预期
6. **废弃子 Agent** - 移除旧的子 Agent 创建逻辑

---

## 另请参阅

- OpenClaw 文档: `C:\Users\Administrator\AppData\Roaming\npm\node_modules\openclaw\docs`
- 飞书技能: `~/.openclaw/extensions/feishu/skills/`
- 配置指南: 文档中的 `openclaw.json` 结构