OpenClaw 代理（Agent）配置完全指南

从建立、配置到高级管理

一、什么是 OpenClaw 代理？

在 OpenClaw 的世界里，「代理」（Agent）不仅仅是一个回答问题的聊天界面——它是一个具备独立身份、专属技能组合与隔离工作空间的自治实体。

你可以将代理想象为团队中的一位专业成员：它知道自己是谁、擅长什么、被允许做什么、以及在哪个环境中工作。

1.1 代理 vs. 聊天机器人：本质差异

传统聊天机器人是被动的：它接收一则消息，回复一则消息，然后等待下一则输入。它没有记忆（或仅有有限的会话记忆），不会主动规划行动，也无法使用外部工具。聊天机器人本质上是一个「问答机器」。

OpenClaw 代理则截然不同。一个完整的 OpenClaw Agent 具备以下五项核心特质：

• 身份（Identity）：通过 agent.md 定义的系统提示，赋予代理角色定位、人格特质与行为规范

• 自主规划（Planning）：面对复杂任务时，代理能自行拆解步骤、排定执行顺序，而非要求用户逐步引导

• 工具使用（Tool Use）：代理可以调用文件系统操作、Shell 指令、API 请求、浏览器控制等工具来完成任务

• 记忆与状态追踪（Memory）：代理在单次对话内维持完整的上下文记忆，并能通过 Workspace 中的文件实现跨会话的知识持续

• 安全边界（Security Boundary）：每个代理的 Workspace 与权限是独立的，一个代理无法访问另一个代理的受限资源

简而言之，聊天机器人是「回答者」，而 OpenClaw 代理是「执行者」。

1.2 OpenClaw 代理架构总览

在 OpenClaw 的架构中，代理是最核心的运作单元。每个代理由四个层次组成：

理解这四个层次至关重要，因为后续所有的配置操作，本质上都是在配置这四个维度。

1.3 何时需要建立自定义代理？

OpenClaw 安装完成后，会自带一个默认代理（Default Agent）。对于一般性的任务——代码问答、文件查询、简单的脚本撰写——默认代理通常就已足够。然而，以下情境建议建立自定义代理：

• 专业化需求：你需要一个专门处理数据库管理的代理、一个专门进行代码审查的代理、一个专门撰写技术文档的代理

• 安全隔离：不同项目的代理需要访问不同的机密数据，必须通过 Workspace 隔离防止交叉访问

• 模型优化：某些任务需要高阶模型（如 Claude Opus 4.6）的深度推理能力，而另一些仅需轻量模型（如 Claude Haiku）的快速响应

• 团队协作：多人团队中，不同成员需要不同配置的代理，或需要共用特定代理配置模板

二、建立第一个代理

2.1 前置条件

在建立代理之前，请确认以下条件已经满足：

• OpenClaw 已安装且完成初始化（openclaw onboard 已执行）
• 至少一个模型供应商的认证已设定完成（例如 Anthropic API Key）
• 主配置文件 ~/.openclaw/openclaw.json 存在且格式正确

你可以通过以下指令快速验证环境是否就绪：

openclaw doctor

如果所有检查都通过（显示绿色勾号），即可开始建立代理。

2.2 使用 agents add 指令

建立新代理的核心指令是 openclaw agents add。最简单的用法只需要一个代理名称：

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-opus-4-6 \
  --workspace ~/projects/my-app \
  --description "专责代码审查的 AI 代理"

2.3 交互式建立流程

如果你偏好引导式操作，可以不带任何参数执行 agents add：

openclaw agents add

系统会进入交互模式，逐步询问以下信息：

• 代理名称：必须唯一，建议使用小写英文加连字符（如 data-analyst、doc-writer）
• 描述：一段简短说明，帮助你日后辨识代理的用途
• 模型选择：从已认证的模型列表中选择，或输入自定义模型标识符
• 工作空间：指定代理的默认工作目录，或使用全局默认值

2.4 验证代理建立成功

代理建立完成后，使用以下指令确认它已正确注册：

openclaw agents list

你应该能看到类似以下的输出：

Name     Model     Workspace           Status
──────────────────────────────────
default          claude-opus-4-6    ~/                  active
code-reviewer    claude-opus-4-6    ~/projects/my-app   ready
data-analyst     claude-sonnet-4-6  ~/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你是一位资深的软件工程师，专精于代码品质审查。你的审查范围涵盖：程序逻辑、安全漏洞、效能瓶颈、可维护性与命名规范。## Behavior Guidelines- 提供具体、可行的改善建议，而非模糊的批评- 对每个发现的问题标注严重程度：Critical / Warning / Info- 引用业界最佳实践（如 OWASP、Clean Code）作为论据- 在审查完毕后提供总结摘要与整体评分（1-10）## Constraints- 不修改原始代码，仅提供建议- 不执行任何可能影响生产环境的指令- 审查范围限于 Workspace 内的文件## Output Format使用 Markdown 表格呈现发现清单，字段包含：文件路径、行号、严重程度、问题描述、改善建议

3.2 撰写有效的系统提示

agent.md 的内容会被注入为代理的系统提示（System Prompt），因此撰写品质直接影响代理的行为表现。以下是几项关键原则：

• 角色定义要具体：不要写「你是一个助手」，而是「你是一位拥有十年经验的 DevOps 工程师，专精 Kubernetes 与 CI/CD 流水线设计」

• 行为准则要量化：不要写「回答要简洁」，而是「每次回复控制在 300 字以内，除非用户明确要求详细解释」

• 约束条件要明确：明确列出代理不应该做的事，比模糊地描述它应该做什么更有效

• 输出格式要固定：统一的输出格式让代理的回复具有可预测性，便于下游整合

3.3 动态变量与模板语法

OpenClaw 的 agent.md 支持动态变量注入，允许你在身份设定中引用执行时的环境信息：

# Data Analyst Agent

## Context
当前日期：{{current_date}}
工作目录：{{workspace_path}}
代理名称：{{agent_name}}

## Role
你是一位数据分析师，负责分析 {{workspace_path}}
目录下的所有数据文件。分析结果应以当前日期
（{{current_date}}）作为报告时间戳记。

这些变量会在代理启动时被自动替换为实际值，使得同一份 agent.md 模板可以在不同环境中复用。

四、模型配置

模型是代理的「大脑」，选择正确的模型对代理的效能、成本与响应品质有决定性影响。OpenClaw 提供了三层模型配置机制，从全局预设到个别代理覆写，确保最大的灵活性。

4.1 全局默认模型

全局默认模型通过 agents.defaults.model.primary 设定，适用于所有未单独指定模型的代理：

openclaw config set agents.defaults.model.primary claude-opus-4-6

这是最基础的设定。当你建立一个新代理而未指定 --model 参数时，该代理会自动继承此全局默认值。

4.2 Fallback 备援模型

在生产环境中，依赖单一模型是危险的。API 限流、服务中断、供应商维护窗口都可能导致代理突然无法运作。Fallback 机制解决了这个问题：

openclaw config set agents.defaults.model.fallbacks \
  '["claude-sonnet-4-6", "gpt-4o", "gemini-2.5-pro"]'

当 Primary 模型不可用时，系统会依序尝试 Fallback 列表中的模型，直到找到第一个可用的为止。整个切换过程对用户透明，代理的对话不会中断。

4.3 Per-Agent 模型覆写

不同代理对模型的需求可能天差地远。一个进行深度代码分析的代理需要最强大的推理能力，而一个只负责格式检查的代理用轻量模型就足够了。OpenClaw 允许为每个代理单独覆写模型设定：

openclaw config set agents.code-reviewer.model.primary claude-opus-4-6
openclaw config set agents.format-checker.model.primary claude-haiku-4

Per-Agent 设定的优先级高于全局默认。也就是说，如果 code-reviewer 代理有自己的 model.primary，它会忽略 agents.defaults.model.primary 的值。

4.4 模型选择实务建议

根据任务类型选择合适的模型，是 OpenClaw 代理配置中最具商业价值的优化手段。以下是经过验证的配置建议：

一个有效的经验法则是：如果任务的输出品质在两个模型之间差异不超过 10%，优先选择成本较低的模型。

五、Workspace 工作空间

Workspace 是 OpenClaw 代理安全模型的核心。它定义了代理能够访问的文件系统范围，是防止代理越权操作的第一道防线。

5.1 默认 Workspace

如果未为代理指定 Workspace，OpenClaw 使用全局默认值：

openclaw config set agents.defaults.workspace "~/"

将默认 Workspace 设定为用户家目录（~/）意味着代理可以访问家目录下的所有文件。这在个人开发机上通常是可以接受的，但在多人共用的服务器环境中，应该缩小范围。

5.2 Per-Agent Workspace

为每个代理设定独立的 Workspace 是最佳实践：

openclaw config set agents.code-reviewer.workspace "~/projects/my-app"
openclaw config set agents.data-analyst.workspace "~/data/analytics"

这确保了 code-reviewer 代理只能访问 ~/projects/my-app 目录下的文件，无法读取 ~/data/analytics 中的数据——即使用户在对话中要求它这么做。

5.3 Workspace 安全意涵

Workspace 的安全意涵不可低估。以下几点值得特别注意：

• 最小权限原则：每个代理的 Workspace 应该只包含它完成任务所需的最小文件集合

• 机密隔离：包含 API 密钥、密码或其他机密的文件（如 .env）不应出现在任何代理的 Workspace 中

• 写入限制：对于只需要读取数据的代理，考虑将 Workspace 设为只读模式

• 定期审查：随着项目演进，原本合理的 Workspace 范围可能需要调整——建议每季度审查一次

5.4 多 Workspace 配置

某些进阶场景中，代理可能需要访问多个不相邻的目录。OpenClaw 支持为单一代理设定多个 Workspace 路径：

{
"agents":{"full-stack-dev":{"workspace":["~/projects/frontend","~/projects/backend","~/projects/shared-libs"]}}}

代理将能访问所有列出的目录，但仍无法访问未被列出的路径。

六、代理管理指令

OpenClaw 提供了一套完整的 CLI 指令来管理代理的生命周期。

6.1 列出所有代理

openclaw agents list

此指令显示所有已注册的代理，包含名称、模型、Workspace 与状态。你也可以使用 --verbose 标志获取更详细的信息：

openclaw agents list --verbose

详细模式会额外显示每个代理的 Fallback 模型列表、最后一次活动时间、累计 Token 消耗量等信息。

6.2 代理身份管理

如需修改代理的显示名称、主题色或表情符号等身份信息，可使用 set-identity 指令：

openclaw agents set-identity code-reviewer

系统会进入交互模式，让你设定代理的身份属性。

6.3 删除代理

移除不再需要的代理：

openclaw agents delete code-reviewer

系统会要求确认，并在删除前提示是否需要备份 agent.md 与相关设定。删除操作会从 openclaw.json 中移除代理的注册记录，并删除其专属目录。

注意：默认代理（default）无法被删除，这是 OpenClaw 的安全设计——确保系统在任何时刻都至少有一个可用的代理。

七、进阶配置

7.1 Timeout 设定

代理在执行长时间任务时，可能会遇到超时问题。OpenClaw 允许在全局与 Per-Agent 层级设定 Timeout：

# 全局 Timeout（单位：秒）
openclaw config set agents.defaults.timeout 300

# Per-Agent Timeout
openclaw config set agents.code-reviewer.timeout 600

对于需要处理大型项目的代理，建议将 Timeout 设定为 10 分钟（600 秒）以上。

7.2 Allowlist 与 Blocklist

通过 Allowlist（允许列表）与 Blocklist（阻止列表），你可以精细控制代理能够执行的操作类型：

{
 "agents":{"code-reviewer":{"permissions":{"allowlist":["file:read","shell:git *"],"blocklist":["file:write","file:delete","shell:rm *","shell:sudo *"]}}}}

Blocklist 的优先级高于 Allowlist。这种「默认拒绝，明确允许」的设计模式，是安全配置的业界最佳实践。

7.3 Auto-Approve 设定

默认情况下，代理在执行敏感操作（如 Shell 指令、文件写入）前会要求用户确认。在信任的环境中，你可以为特定代理启用自动核准，以提升效率：

openclaw config set agents.code-reviewer.autoApprove '["file:read", "shell:git diff *"]'

⚠️ 安全警告：除非你完全理解 Auto-Approve 的风险，否则不建议对写入操作或 Shell 执行启用自动核准。

八、常见问题（FAQ）

Q1：建立代理后可以修改其名称吗？

可以。使用 openclaw agents set-identity <agent-name> 指令可更新代理的显示名称等身份属性。若需要完全重建，可先删除再以新名称建立。

Q2：代理的数量有上限吗？

OpenClaw 本身对代理数量没有硬性限制。然而，每个代理都会占用一定的磁盘空间（主要是 agent.md 与历史记录），且管理过多代理会增加配置的认知负担。实务上，建议单一用户维护不超过 10–15 个活跃代理。

Q3：如何在代理之间共享 agent.md 模板？

目前 OpenClaw 尚未内建模板共享机制。推荐的做法是将常用的 agent.md 模板存放在版本控制系统（如 Git）中，建立新代理后再手动复制。

Q4：Per-Agent 模型设定覆盖了全局默认，但 Fallback 也会被覆盖吗？

是的。Per-Agent 的模型设定是「完整覆盖」，而非「合并」。如果你为某个代理设定了 model.primary 但未设定 model.fallbacks，该代理将没有 Fallback 模型。因此，建议在覆写模型设定时，同时设定 Primary 与 Fallback。

Q5：删除代理后，其对话历史还能恢复吗？

不能。openclaw agents delete 会删除代理的所有数据，包含对话历史。如果你可能需要这些记录，请在删除前手动备份 ~/.openclaw/agents/<agent-name>/ 目录。

Q6：如何让代理在启动时自动加载特定的 context 文件？

在 agent.md 中，你可以使用 {{file:path/to/context.md}} 语法引入外部文件的内容。这些文件会在代理启动时被读取并注入系统提示中。

总结

OpenClaw 代理配置的核心，在于理解四个层次：身份层、模型层、技能层、工作空间层。

• 身份层（agent.md）定义了代理是谁、如何行为
• 模型层决定了代理的「大脑」——选择合适的模型是成本与品质平衡的关键
• 技能层赋予了代理完成任务的能力
• 工作空间层划定了代理的安全边界

掌握这四个层次的配置方式，你就能打造出真正高效、安全、可扩展的 AI 代理团队！

引用链接