OpenClaw Agents 指令完全指南

一、为什么需要深入了解 Agents 指令

OpenClaw 作为当前最具影响力的开源 AI 代理框架之一，其核心价值在于让开发者能够通过简洁的 CLI 指令，快速建立、配置与管理多个智能代理。

根据 OpenClaw 官方社区统计，超过 60% 的初期使用问题都集中在三个面向：agents add 的指令语法、agents list 的输出解读、以及 config set 的模型配置路径。

本文将以「可直接复制执行」为原则，完整拆解 OpenClaw agents 系列指令的每一个参数、每一个选项。

二、OpenClaw 配置文件结构总览

在深入 agents 指令之前，必须先理解 OpenClaw 的配置文件架构——因为每一条 agents 指令的执行结果，最终都会反映在配置文件的变更上。

2.1 双层配置体系

OpenClaw 采用双层配置体系，分别对应「全局设置」与「项目设置」：

全局配置位于用户家目录下：

~/.config/openclaw/├── config.json       # 全局设定（模型 API 密钥、默认模型等）├── agents/          # 全局代理定义│   ├── default/│   │   └── agent.md # 默认代理身份文件│   ├── code-reviewer/│   │   └── agent.md│   └── doc-writer/│       └── agent.md├── templates/        # 代理模板└── logs/            # 运行日志

项目配置位于项目根目录：

your-project/├── openclaw.json        # 项目级配置（覆写全局设定）├── .openclaw/│   ├── agents/          # 项目专属代理│   └── cache/           # 本地缓存└── src/

配置的优先顺序遵循**「就近优先」原则**：项目级配置 > 全局配置 > 内建默认值。

2.2 openclaw.json 核心结构

{"agents":{"defaults":{"model":{"primary":"anthropic:claude-opus-4","fallback":"openai:gpt-4.1"},"workspace":"./","tools":["file","shell","browser"]},"registered":{"code-reviewer":{"identity":".openclaw/agents/code-reviewer/agent.md","model":{"primary":"anthropic:claude-opus-4"},"workspace":"./src"}}},"models":{"providers":{"anthropic":{"apiKey":"${ANTHROPIC_API_KEY}"},"openai":{"apiKey":"${OPENAI_API_KEY}"}}}}

三、openclaw agents add 完整语法

这是 OpenClaw 代理管理中最核心的指令—它负责建立并注册一个新的代理。

3.1 基本语法

openclaw agents add <agent-name> [options]

命名规则：

• 仅允许小写字母、数字与连字符（a-z、0-9、-）
• 必须以字母开头，不得以连字符结尾
• 长度限制为 2 至 64 个字符
• 名称在同一配置层级中必须唯一

3.2 完整参数表

openclaw agents add <agent-name>  --model <model-id>        # 指定主要模型（覆写全局预设）  --fallback-model <model-id>  # 指定 Fallback 模型  --identity <path>         # 指定 agent.md 身份文件路径  --workspace <directory>     # 指定工作空间目录  --tools <tool1,tool2,...>    # 指定允许使用的工具（逗号分隔）  --template <template-name>   # 从模板建立代理  --description <text>       # 代理描述文字  --max-tokens <number>      # 单次请求最大 Token 数  --temperature <float>      # 模型温度参数（0.0 ~ 2.0）  --global               # 注册为全局代理（而非项目级）  --no-identity            # 跳过自动建立 agent.md  --dry-run              # 预览变更但不实际执行  --verbose              # 显示详细执行过程  --json                # 以 JSON 格式输出结果

3.3 最简范例：30 秒建立第一个代理

# 建立一个名为 my-assistant 的代理（使用全局预设模型）openclaw agents add my-assistant

执行后，OpenClaw 会自动完成以下动作：

• 在 .openclaw/agents/my-assistant/ 目录下建立 agent.md 身份文件
• 将代理注册至 openclaw.json 的 agents.registered 区块
• 继承 agents.defaults 中的模型、工具与工作空间设定

输出范例：

✓ Agent "my-assistant" created successfully  Identity: .openclaw/agents/my-assistant/agent.md  Model: anthropic:claude-opus-4 (inherited from defaults)  Workspace: ./  Tools: file, shell, browser

3.4 进阶范例：完整参数配置

# 建立一个专责代码审查的代理openclaw agents add code-reviewer \  --model anthropic:claude-opus-4 \  --fallback-model openai:gpt-4.1 \  --identity ./agents/code-reviewer/agent.md \  --workspace ./src \  --tools file,shell,git \  --description "专责代码审查的代理，聚焦于安全漏洞与效能问题" \  --max-tokens 64000 \  --temperature 0.1

这条指令做了以下设定：

• 主要模型设为 Anthropic Claude Opus 4，Fallback 模型设为 OpenAI GPT-4.1
• 使用自定义的 agent.md 身份文件
• 工作空间限制在 ./src 目录
• 仅允许使用 file、shell、git 三项工具
• 温度设为 0.1（降低随机性，使审查结果更一致）

3.5 从模板建立代理

OpenClaw 内建数个代理模板，可透过 --template 快速建立具备预设配置的代理：

# 查看可用模板openclaw agents templates list# 从 "code-assistant" 模板建立代理openclaw agents add my-coder --template code-assistant# 从 "doc-writer" 模板建立代理openclaw agents add my-writer --template doc-writer

3.6 使用 --dry-run 预览变更

在正式建立代理前，建议先使用 --dry-run 标志预览将要发生的变更：

openclaw agents add data-analyst \  --model openai:gpt-4.1 \  --workspace ./data \  --tools file,shell,python \  --dry-run

输出：

[DRY RUN] The following changes would be applied:1. Create directory: .openclaw/agents/data-analyst/2. Create file: .openclaw/agents/data-analyst/agent.md3. Update openclaw.json:   + agents.registered.data-analyst = {       "identity": ".openclaw/agents/data-analyst/agent.md",       "model": { "primary": "openai:gpt-4.1" },       "workspace": "./data",       "tools": ["file", "shell", "python"]     }No changes were made (dry run).

四、openclaw agents list——列出与管理代理

建立代理后，你需要一种方式来查看、监控与管理所有已注册的代理。

4.1 基本用法

# 列出当前项目的所有代理openclaw agents list

默认输出为简洁的表格格式：

NAME            MODEL              STATUSmy-assistant    anthropic:claude-opus-4    activecode-reviewer    anthropic:claude-opus-4    activedata-analyst    openai:gpt-4.1          activedoc-writer      anthropic:claude-sonnet-4   inactive

4.2 详细模式（--verbose）

openclaw agents list --verbose

输出范例：

Agent: my-assistant  Identity: .openclaw/agents/my-assistant/agent.md  Model: anthropic:claude-opus-4 (inherited)  Fallback: openai:gpt-4.1 (inherited)  Workspace: ./  Tools: file, shell, browser  Tokens: 128000 (inherited)  Temp: 0.7 (inherited)  Status: active  Created: 2026-02-14T10:23:45ZAgent: code-reviewer  Identity: ./agents/code-reviewer/agent.md  Model: anthropic:claude-opus-4 (explicit)  Fallback: openai:gpt-4.1 (explicit)  Workspace: ./src  Tools: file, shell, git  Tokens: 64000  Temp: 0.1  Status: active  Created: 2026-02-14T10:30:12Z

注意 (inherited) 与 (explicit) 标记——明确标示了每个设定值是来自全局预设还是代理自身的覆写配置。

4.3 JSON 格式输出

# 输出 JSON 格式openclaw agents list --format json# 搭配 jq 筛选特定代理openclaw agents list --format json | jq '.agents[] | select(.model.primary == "anthropic:claude-opus-4")'# 仅列出作用中的代理名称openclaw agents list --format json | jq -r '.agents[] | select(.status == "active") | .name'

4.4 筛选与搜索

# 仅列出使用特定模型的代理openclaw agents list --model anthropic:claude-opus-4# 仅列出作用中的代理openclaw agents list --status active# 仅列出全局代理openclaw agents list --global# 同时显示全局与项目级代理openclaw agents list --all

4.5 其他管理指令

# 查看单一代理的详细配置openclaw agents show code-reviewer # 修改已有代理的设定openclaw agents update code-reviewer --model openai:gpt-4.1# 暂时停用代理openclaw agents disable doc-writer# 重新启用代理openclaw agents enable doc-writer# 移除代理（需确认）openclaw agents remove data-analyst# 复制已有代理的配置建立新代理openclaw agents clone code-reviewer security-reviewer

五、openclaw config set 模型配置

openclaw config set 是 OpenClaw 配置管理的瑞士军刀，几乎所有配置项都可透过这条指令修改。

5.1 设定全局默认模型

# 设定全局默认主要模型openclaw config set agents.defaults.model.primary anthropic:claude-opus-4# 设定全局默认 Fallback 模型openclaw config set agents.defaults.model.fallback openai:gpt-4.1# 验证设定结果openclaw config get agents.defaults.model

输出：

agents.defaults.model:  primary: anthropic:claude-opus-4  fallback: openai:gpt-4.1

若要修改全局设定，需加上 --global 标志

5.2 设定个别代理的模型

# 为 code-reviewer 代理设定专属模型openclaw config set agents.registered.code-reviewer.model.primary anthropic:claude-opus-4# 为 data-analyst 代理设定不同的模型openclaw config set agents.registered.data-analyst.model.primary openai:gpt-4.1# 为 doc-writer 设定成本较低的模型openclaw config set agents.registered.doc-writer.model.primary anthropic:claude-haiku-4

5.3 模型配置的完整路径参考

# ── 全局默认 ──agents.defaults.model.primary        # 默认主要模型agents.defaults.model.fallback       # 默认 Fallback 模型agents.defaults.model.temperature    # 默认温度agents.defaults.model.maxTokens      # 默认最大 Token 数# ── 个别代理 ──agents.registered.<name>.model.primaryagents.registered.<name>.model.fallbackagents.registered.<name>.model.temperatureagents.registered.<name>.model.maxTokens# ── 模型提供者 ──models.providers.<provider>.apiKeymodels.providers.<provider>.baseUrl

5.4 config get 与 config list

# 查看特定配置值openclaw config get agents.defaults.model.primary# 输出: anthropic:claude-opus-4# 查看某个代理的完整配置openclaw config get agents.registered.code-reviewer# 列出所有配置项（含来源标记）openclaw config list --show-origin# 以 JSON 格式输出完整配置openclaw config list --format json

六、实战范例：多代理模型配置

6.1 场景描述

假设你的团队需要以下四个代理：

6.2 Step 1：设定全局默认与模型提供者

# 设定模型提供者的 API 密钥openclaw config set models.providers.anthropic.apiKey '${ANTHROPIC_API_KEY}' --globalopenclaw config set models.providers.openai.apiKey '${OPENAI_API_KEY}' --global# 设定全局默认模型openclaw config set agents.defaults.model.primary anthropic:claude-sonnet-4 --globalopenclaw config set agents.defaults.model.fallback openai:gpt-4.1-mini --global

6.3 Step 2：建立四个代理

# 架构师——使用最强模型，高 Token 上限openclaw agents add architect \  --model anthropic:claude-opus-4 \  --fallback-model anthropic:claude-sonnet-4 \  --max-tokens 128000 \  --temperature 0.3 \  --tools file,shell,browser,mcp \  --description "系统架构师：负责高层设计、技术选型与架构决策"# 开发者——平衡速度与品质openclaw agents add coder \  --model anthropic:claude-sonnet-4 \  --fallback-model openai:gpt-4.1 \  --max-tokens 64000 \  --temperature 0.4 \  --tools file,shell,git,npm \  --workspace ./src \  --description "程序开发者：负责代码撰写、功能实现与单元测试"# 审查者——低温度确保一致性openclaw agents add reviewer \  --model anthropic:claude-opus-4 \  --fallback-model anthropic:claude-sonnet-4 \  --max-tokens 64000 \  --temperature 0.1 \  --tools file,git \  --workspace ./src \  --description "代码审查者：聚焦安全漏洞、效能瓶颈与代码风格"# 文件撰写者——使用成本较低的模型openclaw agents add documenter \  --model anthropic:claude-haiku-4 \  --fallback-model openai:gpt-4.1-mini \  --max-tokens 32000 \  --temperature 0.7 \  --tools file,shell \  --workspace ./docs \  --description "文件撰写者：维护 README、API 文件与技术指南"

6.4 成本考量

透过为不同代理指派不同等级的模型，相较于统一使用最高等级模型，预估可降低 40–60% 的 API 费用，同时不牺牲关键环节（架构设计、安全审查）的推理品质。

七、常见问题排解

7.1 Error: Agent name already exists

$ openclaw agents add coderError: Agent "coder" already exists in project config.

解决方式：

# 方式 1：使用不同名称openclaw agents add coder-v2# 方式 2：先移除再重建openclaw agents remove coderopenclaw agents add coder --model anthropic:claude-sonnet-4# 方式 3：使用 update 修改现有代理openclaw agents update coder --model anthropic:claude-sonnet-4

7.2 Error: Model not found

$ openclaw agents add my-bot --model anthropic:claude-5Error: Model "anthropic:claude-5" not found.

解决方式：

# 查看所有可用模型openclaw models list# 使用正确的模型 IDopenclaw agents add my-bot --model anthropic:claude-opus-4

7.3 Error: API key not configured

$ openclaw agents add my-bot --model anthropic:claude-opus-4Error: No API key configured for provider "anthropic".

解决方式：

# 方式 1：透过 config set 设定openclaw config set models.providers.anthropic.apiKey 'sk-ant-xxxx' --global# 方式 2：透过环境变量设定（建议）export ANTHROPIC_API_KEY="sk-ant-xxxx"openclaw config set models.providers.anthropic.apiKey '${ANTHROPIC_API_KEY}' --global

7.4 Error: Invalid agent name

$ openclaw agents add My_AgentError: Invalid agent name "My_Agent".

解决方式： 使用符合命名规则的名称，例如 my-agent。

7.5 Error: Workspace directory not found

$ openclaw agents add my-bot --workspace ./nonexistentError: Workspace directory "./nonexistent" does not exist.

解决方式：

# 方式 1：先建立目录mkdir -p ./nonexistentopenclaw agents add my-bot --workspace ./nonexistent# 方式 2：使用 --create-workspace 标志openclaw agents add my-bot --workspace ./nonexistent --create-workspace

八、总结

OpenClaw 的 agents 指令体系——从 agents add 的代理建立、agents list 的状态监控，到 config set 的模型配置——构成了整个代理管理工作流的核心。

核心要点回顾：

• 配置文件结构：理解双层配置体系（全局 vs. 项目）与就近优先原则
• agents add：掌握完整参数语法，善用 --template 加速建立、--dry-run 预览变更
• agents list：搭配 --verbose 与 --format json，实现代理状态的即时掌握
• config set：熟悉模型配置路径，养成设定后验证的习惯
• 多代理架构：为不同职责的代理指派最适合的模型，可大幅降低 API 费用

引用链接