夜雨聆风OpenClaw 代理（Agent）配置全指南：创建、设置与管理
在 OpenClaw 的生态中，“代理”（Agent）绝不仅仅是一个只负责回答问题的聊天界面——它是一个拥有独立身份、专属技能组以及隔离工作空间的自主实体。你可以将代理想象成你开发团队中的一位专业成员：它清楚地知道自己是谁、擅长什么、被允许执行哪些操作，以及在哪个确切的环境中工作。
本文将专门聚焦于 OpenClaw 代理的创建、配置与管理。无论你是第一次接触 OpenClaw 的新手，还是已经在生产环境中运行了多个代理的高级用户，这份指南都将为你提供一条从零到一的完整路径：从执行 agents add 的第一步开始，逐步深入探索 agent.md 身份设定、模型选择与降级（Fallback）策略、工作空间（Workspace）安全配置，直至高级的权限管控与多代理管理技巧。
一、 什么是 OpenClaw 代理？
在深入配置流程之前，我们需要先厘清 OpenClaw 代理的本质。它与传统聊天机器人（Chatbot）之间的差异，远比大多数人想象的要大得多。
1.1 代理 vs. 聊天机器人：本质差异
传统的聊天机器人是被动的：它接收一条消息，回复一条消息，然后原地等待下一次输入。它几乎没有记忆（或仅有极短的会话上下文），不会主动规划行动，也无法调用外部工具。本质上，聊天机器人只是一个“问答机器”。
而 OpenClaw 代理则截然不同。一个完整的 OpenClaw Agent 具备以下五项核心特质：
身份（Identity）：通过 agent.md定义系统提示词（System Prompt），赋予代理角色定位、人格特质与行为规范。自主规划（Planning）：面对复杂任务时，代理能自行拆解步骤、排定执行顺序，而不需要用户像挤牙膏一样逐步引导。 工具调用（Tool Use）：代理可以调用文件系统操作、执行 Shell 命令、发起 API 请求、甚至控制浏览器来完成任务。 记忆与状态追踪（Memory）：代理能在单次对话内维持完整的上下文记忆，并能通过工作空间（Workspace）中的文件实现跨会话的知识沉淀。 安全边界（Security Boundary）：每个代理的工作空间与权限都是相互隔离的，一个代理绝对无法越权访问另一个代理的受限资源。
简而言之，聊天机器人是“回答者”，而 OpenClaw 代理是“执行者”。当你告诉代理“帮我重构这个模块并编写单元测试”时，它会自动读取代码、分析结构、进行修改、运行测试并汇报结果——这一连串的行动无需你再做任何干预。
1.2 OpenClaw 代理架构总览
在 OpenClaw 的架构中，代理是最核心的运行单元。每个代理由四个维度的层次组成：
身份层（Identity Layer）：由 agent.md定义，决定代理的角色、行为边界与系统指令。模型层（Model Layer）：决定代理使用哪个大型语言模型（LLM）进行推理，包含主模型（Primary）与备用模型（Fallback）配置。 技能层（Skills Layer）：代理被允许调用的工具与能力集合，例如文件读写、Shell 执行、网络请求等。 工作空间层（Workspace Layer）：代理的文件系统边界——它能读写哪些目录、能访问哪些资源。
理解这四个层次至关重要，因为后续所有的配置操作，本质上都是在这四个维度上进行微调。
1.3 何时需要创建自定义代理？
OpenClaw 安装完成后，会自带一个默认代理（Default Agent）。对于一般性的任务（如简单的代码问答、文档查询、写个小脚本），默认代理通常就足够了。然而，在以下场景中，强烈建议创建自定义代理：
专业化需求：你需要一个专门处理数据库管理的代理、一个负责代码 Review 的代理、或是一个专门撰写 API 文档的代理。 安全隔离：不同项目的代理需要访问不同的机密数据，必须通过独立的工作空间进行物理隔离，防止交叉访问。 模型成本优化：某些复杂任务需要高级模型（如 Claude 3.5 Sonnet）的深度推理能力，而另一些简单任务只需轻量级模型（如 Claude 3 Haiku）来保证响应速度并降低成本。 团队协作：在多人团队中，不同成员需要不同配置的代理，或者需要共享特定的代理配置模板。
二、 创建第一个代理
接下来进入实战环节。我们将使用命令行工具，从零开始创建一个 OpenClaw 代理。
2.1 前置条件
在创建代理之前，请确保你的开发环境满足以下条件：
OpenClaw 已正确安装并完成初始化（即已执行过 openclaw onboard）。至少配置好了一个大模型供应商的 API 密钥（例如 Anthropic 或 OpenAI 的 API Key）。 主配置文件 ~/.openclaw/openclaw.json存在且 JSON 格式合法。
你可以通过以下命令快速验证环境健康状态：
# 检查 OpenClaw 的环境依赖和配置是否正常openclaw doctor如果所有检查项都通过（显示绿色勾号），即可开始创建代理。
2.2 使用 agents add 命令
创建新代理的核心命令是 openclaw agents add。最基础的用法只需提供一个代理名称：
# 创建一个名为 code-reviewer 的代理openclaw agents add code-reviewer执行上述命令后，OpenClaw 会在后台完成以下动作：
在 ~/.openclaw/agents/目录下创建code-reviewer/文件夹。自动生成一个默认的 agent.md身份文件。继承全局默认的模型设置（即 agents.defaults.model.primary）。将该代理注册到 openclaw.json的代理列表中。
如果你想在创建代理的同时，一步到位地指定模型和工作目录，可以使用完整参数：
# 一键创建代理并配置模型、工作空间和描述openclaw agents add code-reviewer \ --model claude-3-5-sonnet \ --workspace ~/projects/my-app \ --description "专职负责代码审查的 AI 代理"2.3 交互式创建流程
如果你不喜欢记忆冗长的命令行参数，可以直接运行不带参数的命令，系统会提供友好的引导：
# 进入交互式代理创建向导openclaw agents add向导会逐步询问你以下信息：
代理名称：必须唯一，建议使用小写英文加连字符（如 data-analyst、doc-writer）。描述：一段简短的说明，方便日后识别该代理的用途。 模型选择：从已认证的模型列表中进行单选，或手动输入自定义模型 ID。 工作空间：指定代理的默认工作目录路径。
这种交互式流程非常适合新手，能有效降低配置出错的概率。
2.4 验证代理创建状态
代理创建完成后，可以使用以下命令查看代理列表，确认其是否注册成功：
# 列出当前系统中所有的 OpenClaw 代理openclaw agents list控制台应该会输出类似以下的表格：
Name Model Workspace Status─────────────────────────────────────────────────────────────────default claude-3-5-sonnet ~/ activecode-reviewer claude-3-5-sonnet ~/projects/my-app readydata-analyst gpt-4o ~/data ready(注：active 表示当前正在会话中使用的代理，ready 表示已配置完毕随时可被调用。)
三、 agent.md 身份配置
如果说 agents add 给了代理“肉体”，那么 agent.md 就是注入代理的“灵魂”。这个基于 Markdown 格式的文件，决定了代理如何认知自己的角色、如何与用户对话，以及在什么规则边界内行事。
3.1 agent.md 的位置与结构
每个代理的 agent.md 都存放在其专属的配置目录下，例如：
~/.openclaw/agents/code-reviewer/agent.md一个编写优良的 agent.md 通常包含以下几个标准区块：
# Code Reviewer Agent## Role (角色定义)你是一位资深的 Web 全栈工程师，专精于代码质量审查。你的审查范围涵盖：业务逻辑严谨性、安全漏洞、性能瓶颈、可维护性与命名规范。## Behavior Guidelines (行为准则)- 提供具体、代码级的改进建议，坚决避免假大空的模糊批评。- 对发现的每个问题标注严重级别：Critical（致命） / Warning（警告） / Info（信息）。- 引用业界最佳实践（如 OWASP 安全指南、Clean Code 原则）作为你的论据。- 在审查完毕后，务必提供一份总结摘要，并给出整体代码评分（1-10分）。## Constraints (约束条件)- 绝对不要直接修改原始代码文件，仅在对话中提供修改建议。- 禁止执行任何可能影响系统状态的 Shell 命令（如 rm, npm publish 等）。- 审查范围严格限制在当前 Workspace 内的代码文件。## Output Format (输出格式)请使用 Markdown 表格呈现你的审查清单，表头必须包含：| 文件路径 | 行号 | 严重级别 | 问题描述 | 改进建议 |3.2 编写高效的系统提示词（System Prompt）
agent.md 的内容在运行时会被作为 System Prompt 注入给大模型，因此它的质量直接决定了代理的表现。作为开发者，请遵循以下 Prompt 工程原则：
角色定义要具象化：不要写“你是一个编程助手”，而要写“你是一位拥有 10 年经验的 Node.js 专家，精通 V8 引擎性能调优和高并发微服务架构”。 行为准则要可量化：不要写“回答要简洁”，而要写“除非用户明确要求详细解释，否则每次回复必须控制在 300 字以内”。 约束条件要明确：告诉大模型“不该做什么”，往往比告诉它“该做什么”更能有效防止幻觉和越界行为。 固定输出格式：要求模型输出 JSON 或标准 Markdown 表格，这能让代理的输出具备高度的可预测性，非常利于后续的自动化解析。
3.3 动态变量与模板语法
OpenClaw 支持在 agent.md 中使用双大括号语法 {{variable}} 注入运行时环境变量。这使得同一份配置模板可以灵活适配不同环境：
# Data Analyst Agent## Context (运行时上下文)当前日期：{{current_date}} 工作目录：{{workspace_path}} 代理名称：{{agent_name}}## Role你是一位数据分析师，负责分析 {{workspace_path}} 目录下的所有 CSV 和 JSON 数据文件。你的分析报告必须以当前系统日期（{{current_date}}）作为时间戳前缀。当代理启动时，这些变量会被自动替换为真实的系统值。
3.4 本地化语言支持
OpenClaw 对多语言支持极佳。为了让模型生成更符合中文语境的内容，强烈建议直接用中文撰写 agent.md，并在提示词中明确语言要求：
# 技术文档工程师代理## 行为规范- 必须使用流畅的简体中文撰写文档。- 遇到专业技术名词（如 Promise, Closure）时保留英文原文，不要生硬翻译。- 代码块中的注释翻译为中文，但变量名和函数名保持不变。四、 模型配置
模型是大脑。为代理选择合适的模型，能在性能、响应速度和 Token 成本之间取得完美平衡。OpenClaw 提供了三层模型配置机制。
4.1 全局默认模型
全局默认模型（Global Default）适用于所有没有单独指定模型的代理：
# 将全局默认主模型设置为 Claude 3.5 Sonnetopenclaw config set agents.defaults.model.primary claude-3-5-sonnet4.2 Fallback 备用策略（兜底机制）
在生产环境中，单点依赖某个模型是极其危险的。API 触发限流（Rate Limit）、供应商服务器宕机等都可能导致代理瘫痪。Fallback 机制完美解决了这个问题：
# 配置全局备用模型队列（按优先级排序）openclaw config set agents.defaults.model.fallbacks \'["gpt-4o", "gemini-1.5-pro", "claude-3-haiku"]'当主模型不可用时，系统会自动静默切换到 Fallback 列表中的下一个模型。用户侧几乎无感知，对话不会因此中断。
4.3 Per-Agent（单代理）模型覆盖
不同的代理对智商的要求不同。代码重构需要极强的逻辑推理，而简单的拼写检查只需要速度快的轻量级模型即可。你可以为特定代理单独指定模型：
# 为需要高智商的代理配置顶级模型openclaw config set agents.code-reviewer.model.primary claude-3-opus# 为只做简单格式化的代理配置轻量、廉价的模型openclaw config set agents.format-checker.model.primary claude-3-haiku(注意：单代理的配置优先级永远高于全局默认配置。)
你也可以直接编辑 ~/.openclaw/openclaw.json（支持 JSON5 语法）进行可视化管理：
{ agents: { // 全局默认配置 defaults: { model: { primary: "claude-3-5-sonnet", fallbacks: ["gpt-4o", "claude-3-haiku"], }, }, // 单独覆盖 code-reviewer 代理配置 "code-reviewer": { model: { primary: "claude-3-opus", // 代码审查任务不容错，降级时依然使用同级别模型 fallbacks: ["gpt-4o"], }, }, "quick-helper": { model: { primary: "claude-3-haiku", fallbacks: ["gpt-4o-mini"], }, }, },}4.4 选型实战建议
根据我的全栈开发经验，合理的模型分发能为您节省极大的 API 账单：
深度推理（系统架构、疑难 Bug 排查）：首选 Claude 3.5 Sonnet或GPT-4o，兜底方案也必须是同级别。日常开发（写基础组件、写测试用例）：同样推荐 Claude 3.5 Sonnet，性价比目前最高。高频低智任务（JSON 格式化、日志提取）：毫不犹豫地选择 Claude 3 Haiku或GPT-4o-mini，成本不到高级模型的十分之一，速度极快。
五、 Workspace 工作空间安全
工作空间（Workspace）是 OpenClaw 防止 AI 代理“暴走”的第一道物理防线。它限制了代理能触碰到的文件系统边界。
5.1 默认 Workspace 的风险
如果不指定工作空间，OpenClaw 会将其设为用户主目录 ~/：
openclaw config set agents.defaults.workspace "~/"警告：这在个人电脑上勉强可以接受，但在服务器或 CI/CD 环境中，这意味着 AI 可以读取你所有的 SSH 密钥、.env 文件和个人文档。强烈建议缩小范围。
5.2 实施最小权限原则
最佳实践是为每个代理分配独立且最小化的工作目录：
# 将代码审查代理限制在特定的前端项目中openclaw config set agents.code-reviewer.workspace "~/projects/frontend-app"这样一来，即使你命令代理“去读取并修改我后端的数据库密码”，代理也会因为超出工作空间边界而直接拒绝执行。
5.3 多路径 Workspace 配置
有时候，全栈开发代理需要同时访问前端项目和后端项目，但这两个项目并不在一个目录下。OpenClaw 支持传入路径数组：
{ agents: { "full-stack-dev": { // 允许访问多个离散的目录 workspace: ["~/projects/frontend-vue", "~/projects/backend-node", "~/projects/shared-types"], }, },}六、 代理管理命令日常用法
掌握以下 CLI 命令，可以让你高效管理代理生命周期。
6.1 查看状态与用量
# 基础列表openclaw agents list# 详细模式（会显示每个代理的 Token 消耗、最后活动时间和 Fallback 配置）openclaw agents list --verbose6.2 更新身份信息
想给代理换个名字或改个图标？使用 set-identity 命令：
openclaw agents set-identity code-reviewer这会触发交互式面板，让你修改显示名称、UI 主题色等表现层属性。
6.3 安全删除代理
# 删除无用的代理openclaw agents delete code-reviewer执行后会弹出防误删确认。注意：删除操作会彻底抹除该代理的配置目录及对话历史记录。（系统自带的 default 代理被保护，无法删除）。
6.4 在团队中共享配置
目前官方尚未内置一键导出功能。对于开发团队，推荐的做法是利用 Git 共享配置目录：
# 1. 复制代理的配置文件夹到共享仓库cp -r ~/.openclaw/agents/code-reviewer/ ~/team-shared-configs/# 2. 团队成员拉取后，覆盖本地配置openclaw agents add code-reviewer --model claude-3-5-sonnetcp ~/team-shared-configs/code-reviewer/agent.md ~/.openclaw/agents/code-reviewer/提示：切记不要把包含 API Key 的主配置文件传到公共仓库中！
七、 高级配置（生产环境必备）
在企业级应用中，我们需要对 AI 的行为进行更细粒度的约束。
7.1 超时控制（Timeout）
分析庞大的代码库可能需要耗费大量时间。默认的 120 秒超时往往不够用：
# 将特定代理的超时时间延长至 10 分钟 (600秒)openclaw config set agents.code-reviewer.timeout 6007.2 动作拦截：白名单与黑名单
这是最重要的安全配置。通过 allowlist（允许列表）和 blocklist（拒绝列表），你可以严格限制代理可以使用的底层工具：
{ agents: { "code-reviewer": { permissions: { // 白名单：只允许读取文件和执行 git 相关命令 allowlist: ["file:read", "shell:git *"], // 黑名单：明确禁止任何写入、删除及提权操作 blocklist: ["file:write", "file:delete", "shell:rm *", "shell:sudo *"], }, }, },}防御机制：黑名单优先级绝对高于白名单。如果一个操作同时匹配两者（或者匹配了通配符），它将被无情拦截。这符合安全领域的“默认拒绝”原则。
7.3 危险警告：自动审批（Auto-Approve）
默认情况下，代理执行文件写入或 Shell 命令前，界面会弹窗要求人类开发者点击确认。为了效率，你可以免除这些确认：
# 允许自动执行读取操作和 git diff，无需人工干预openclaw config set agents.code-reviewer.autoApprove '["file:read", "shell:git diff *"]'⚠️ 安全红线：绝对不要将 file:write（文件写入）或 shell:*（任意命令执行）加入自动审批列表。一旦发生提示词注入攻击（Prompt Injection），黑客可能借由代理直接摧毁你的本地系统。
八、 实战范例：组建全栈开发 AI 团队
将以上知识融会贯通，让我们在 openclaw.json 中配置一个包含“架构师”、“开发”和“代码审查”三个角色的虚拟团队：
{ agents: { // ------------------------------------ // 1. 全局基准配置 // ------------------------------------ defaults: { model: { primary: "claude-3-5-sonnet", fallbacks: ["gpt-4o", "claude-3-haiku"], }, workspace: "~/", timeout: 180, }, // ------------------------------------ // 2. 架构师：负责系统设计 (需要最强逻辑) // ------------------------------------ architect: { model: { primary: "claude-3-opus", // 使用顶级模型 fallbacks: ["gpt-4o"], }, workspace: "~/projects/my-app", timeout: 600, // 思考时间给足 }, // ------------------------------------ // 3. 开发者：负责干苦力写代码 (需要高效率) // ------------------------------------ developer: { model: { primary: "claude-3-5-sonnet", fallbacks: ["gpt-4o"], }, workspace: "~/projects/my-app", // 为了效率，放开常规的读写和 npm/git 命令的自动审批 autoApprove: ["file:read", "file:write", "shell:npm *", "shell:git *"], }, // ------------------------------------ // 4. 审查员：挑毛病 (需要安全限制) // ------------------------------------ reviewer: { model: { primary: "claude-3-5-sonnet", fallbacks: ["gpt-4o"], }, workspace: "~/projects/my-app", permissions: { // 绝对禁止审查员自己修改代码或删除文件 blocklist: ["file:write", "file:delete", "shell:rm *"], }, }, },}九、 常见问题解答（FAQ）
Q1：代理的数量有上限吗？ OpenClaw 核心系统没有硬性限制。但出于管理成本考虑，建议单人维护不超过 10-15 个活跃代理。过多的代理会增加寻找和切换的认知负担。
Q2：Per-Agent 设置了主模型，全局的 Fallback 还会生效吗？不会。在 OpenClaw 中，单代理的模型配置是“完全覆盖”而非“合并”。如果你只给代理配置了 model.primary，那么它将失去降级能力。建议重写主模型时，顺手把 fallbacks 也写上。
Q3：工作空间（Workspace）可以指定为网络驱动器（如 NAS 或 SMB）吗？ 技术上可以，但极其不推荐。AI 在分析项目时会频繁遍历和读取大量小文件，网络延迟会导致严重的性能瓶颈甚至触发 Timeout 错误。请尽量在本地固态硬盘上运行。
Q4：如何让代理启动时自动加载项目的某个说明文档？ 你可以在 agent.md 中使用 {{file:path/to/docs.md}} 语法引入外部文件。该路径是相对于当前代理 Workspace 根目录的相对路径。
Q5：autoApprove (自动审批) 支持正则表达式吗？ 目前只支持轻量级的 Glob 模式匹配（例如 shell:git * 匹配所有 git 命令），不支持复杂的 Regex。如果逻辑复杂，请采用“宽泛白名单 + 精准黑名单”的组合策略来进行拦截。
