【OpenClaw 进阶实战系列六】 Agents 指令完全指南:add、list、config 与模型配置

OpenClaw Agents 指令完全指南：add、list、config 与模型配置

一、引言：为什么需要深入了解 Agents 指令？

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

但在实际开发中，许多开发者初次接触 openclaw agents add 指令时，常被繁多的参数组合和多层级的配置结构所困扰。这不仅会消耗宝贵的开发时间，还可能导致代理在运行时出现不符合预期的行为（比如用了错误的 API 模型，或者没有正确的目录访问权限）。

本文将以“开箱即用、可直接复制执行”为原则，为您彻底拆解 OpenClaw Agents 系列指令的每一个参数、每一个选项，并深度剖析其配置文件的底层结构。读完本文，您将能够：

精准掌握 openclaw agents add 的完整语法及参数作用。
熟练使用 openclaw agents list 监控与管理代理状态。
深刻理解 openclaw config set 在模型配置中的运行机制。
亲手设计适合团队的多代理、多模型协作架构。
快速排查并解决常见的 CLI 报错。

二、OpenClaw 配置文件结构总览

在敲下任何一行指令前，我们必须先理清 OpenClaw 的配置架构——因为你在终端敲击的每一条指令，最终都会精准地映射并修改这些配置文件。

2.1 双层配置体系

OpenClaw 采用了非常经典的双层配置体系，分为“全局配置”与“项目配置”：

1. 全局配置（Global Config）：位于用户的主目录下，适用于跨项目复用的通用设置。

~/.config/openclaw/├── config.json          # 全局配置（如：模型 API 密钥、默认使用的模型等）├── agents/              # 全局代理定义目录│   ├── default/│   │   └── agent.md     # 默认代理的身份与提示词定义文件│   ├── code-reviewer/│   │   └── agent.md│   └── doc-writer/│       └── agent.md├── templates/           # 代理预设模板│   ├── minimal.json│   └── full.json└── logs/                # 全局运行日志    └── openclaw.log

2. 项目配置（Project Config）：位于当前项目的根目录，仅对当前项目生效。

your-project/├── openclaw.json        # 项目级配置（优先级较高，会覆盖全局配置）├── .openclaw/│   ├── agents/          # 当前项目专属的代理│   │   └── project-bot/│   │       └── agent.md│   └── cache/           # 本地运行缓存└── src/    └── ...

配置优先级遵循“就近原则”：项目级配置 > 全局配置 > 系统内置默认值。这意味着你可以把敏感的 API 密钥写在全局配置中，而在具体项目里只覆盖所需使用的特定模型。

2.2 `openclaw.json` 核心结构解析

无论是全局还是项目级的配置文件，其 JSON 结构都包含以下五个核心区块：

{"agents": {"defaults": {// 全局默认配置：新创建的代理若无特殊指定，将继承这里的设置"model": {"primary": "anthropic:claude-opus-4","fallback": "openai:gpt-4.1"      },"workspace": "./","tools": ["file", "shell", "browser"]    },"registered": {// 已注册的代理列表：通过 agents add 创建的代理会写入这里"code-reviewer": {"identity": ".openclaw/agents/code-reviewer/agent.md","model": {"primary": "anthropic:claude-opus-4"        },"workspace": "./src"      }    }  },"models": {"providers": {// 模型供应商配置：强烈建议使用环境变量引用，避免密钥泄露"anthropic": {"apiKey": "${ANTHROPIC_API_KEY}","baseUrl": "https://api.anthropic.com"      },"openai": {"apiKey": "${OPENAI_API_KEY}"      }    }  },"tools": {// 允许代理使用的工具列表"enabled": ["file", "shell", "browser", "mcp"],"permissions": {// 细粒度的权限控制：例如限制 shell 只能执行特定命令"shell": { "allowlist": ["git", "npm", "node"] }    }  },"security": {"sandbox": true,"networkPolicy": "restricted","maxTokensPerRequest": 128000  },"logging": {"level": "info","output": "~/.config/openclaw/logs/openclaw.log"  }}

安全提示：环境变量支持 如上所示，OpenClaw 支持 ${ENV_VAR} 语法。请将 export OPENAI_API_KEY="sk-..." 写入您的 .bashrc 或 .zshrc，不要将明文密钥提交到代码仓库中。

三、`openclaw agents add` 完整语法拆解

这是您最高频使用的指令。它负责实例化并注册一个新的 AI 代理。

3.1 基本语法与命名规范

openclaw agents add <agent-name> [options]

<agent-name> 是必填的唯一标识符，命名需符合以下规范：

仅包含小写字母、数字和中划线（a-z, 0-9, -）。
必须以字母开头，不能以中划线结尾。
长度介于 2 到 64 个字符之间。

3.2 完整参数列表

openclaw agents add <agent-name> \  --model <model-id>            # 指定主要模型（覆盖默认值）  --fallback-model <model-id>   # 指定备用模型（主模型请求失败时使用）  --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 实战演示：创建代理的 3 种姿势

姿势一：极简模式（30秒上手）

# 创建名为 my-assistant 的代理，一切继承默认配置openclaw agents add my-assistant

执行后，框架会自动在 .openclaw/agents/my-assistant/ 生成身份文件，并将其注册到 openclaw.json 中。

姿势二：全副武装（高阶定制）

# 创建一个专职进行代码审查的严格代理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 # 温度设为 0.1，保证审查标准的客观一致性

姿势三：无损预览（团队协作利器）

在正式创建前，使用 --dry-run 预览变更，非常适合在提交 PR 前向团队展示配置逻辑：

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

终端将清晰打印出即将创建的目录、文件以及将要修改的 JSON 节点，但不会产生实际写入。

四、`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               active

4.2 详细模式（排错必备）

当你怀疑某个代理配置未生效时，带上 --verbose：

openclaw agents list --verbose

输出将明确标识出配置是继承 (inherited) 还是**覆盖 (explicit)**的：

Agent: 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:    128000 (inherited)                   <-- 继承自全局的  Temp:      0.1  Status:    active

4.3 脚本化处理（结合 jq）

作为全栈开发，我们经常需要把 CLI 结果交给 CI/CD 管道，使用 --format json 极其方便：

# 仅提取出处于 active 状态的代理名称openclaw agents list --format json | jq -r '.agents[] | select(.status == "active") | .name'

五、`openclaw config set`：配置管理的瑞士军刀

OpenClaw 几乎所有的配置都可以通过 config set 动态修改。在代理上下文中，最核心的是模型节点的配置。

5.1 修改全局默认模型

# 设置所有代理默认使用 claude-opus-4openclaw config set agents.defaults.model.primary anthropic:claude-opus-4 --global# 验证设置是否成功openclaw config get agents.defaults.model

5.2 为特定代理“开小灶”

如果文档编写代理想用便宜的模型，而核心代码代理想用最强的模型：

# 为文档代理指定低成本的 Haiku 模型openclaw config set agents.registered.doc-writer.model.primary anthropic:claude-haiku-4# 为架构师代理指定最高配的 Opus 模型openclaw config set agents.registered.architect.model.primary anthropic:claude-opus-4

5.3 常用配置路径速查表

# 全局默认设置agents.defaults.model.primary          # 默认主模型agents.defaults.model.fallback         # 默认备用模型agents.defaults.model.temperature      # 默认发散度agents.defaults.workspace              # 默认工作区# 特定代理设置agents.registered.<name>.model.primaryagents.registered.<name>.tools# API 密钥设置models.providers.<provider>.apiKey

5.4 撤销与重置

配置乱了？没关系，一键恢复：

# 移除针对 code-reviewer 的特殊模型配置，让其乖乖继承全局默认值openclaw config unset agents.registered.code-reviewer.model.primary# 慎用：将 defaults 区块恢复出厂设置openclaw config reset agents.defaults

六、实战架构：设计企业级多代理体系

在企业级项目中，不同角色的代理对算力和智能程度的需求是不同的。合理配置可以节约 40%-60% 的 API 成本，同时保障工程质量。

6.1 场景：组建一个 4 代理开发团队

**Architect (系统架构师)**：需极强推理能力（低频、高 Token 消耗）。
**Coder (代码开发者)**：速度与质量平衡（高频、中 Token 消耗）。
**Reviewer (代码审查者)**：极高的严谨度和一致性（中频、要求温度低）。
**Documenter (文档撰写者)**：归纳总结即可（低频、可用廉价模型）。

6.2 一键部署脚本

#!/bin/bash# 1. 注入密钥 (全局)openclaw config set models.providers.anthropic.apiKey '${ANTHROPIC_API_KEY}' --globalopenclaw config set models.providers.openai.apiKey '${OPENAI_API_KEY}' --global# 2. 设定打底的全局默认配置openclaw config set agents.defaults.model.primary anthropic:claude-sonnet-4 --globalopenclaw config set agents.defaults.model.fallback openai:gpt-4.1-mini --globalopenclaw config set agents.defaults.model.temperature 0.5 --global# 3. 实例化：架构师 (最强模型, 大上下文)openclaw agents add architect \  --model anthropic:claude-opus-4 \  --max-tokens 128000 \  --temperature 0.3 \  --tools file,shell,browser,mcp \  --description "系统架构师：负责高层设计与技术选型"# 4. 实例化：程序员 (平衡模型, 限定工作区在 src)openclaw agents add coder \  --model anthropic:claude-sonnet-4 \  --workspace ./src \  --tools file,shell,git,npm \  --description "代码开发者：负责功能实现与单元测试"# 5. 实例化：审查员 (强模型, 但温度极低, 拒绝发散)openclaw agents add reviewer \  --model anthropic:claude-opus-4 \  --temperature 0.1 \  --workspace ./src \  --tools file,git \  --description "代码审查者：聚焦安全与代码规范"# 6. 实例化：文档撰写员 (廉价模型, 限定工作区在 docs)openclaw agents add documenter \  --model anthropic:claude-haiku-4 \  --workspace ./docs \  --tools file \  --description "文档撰写者：维护 README 与 API 文档"

只需将以上脚本保存并运行，一个高性价比、分工明确的 AI 研发团队就初始化完成了。

七、常见排坑指南 (Troubleshooting)

7.1 报错：`Error: Agent name already exists`

原因：你想创建的代理名称被占用了。解决：

# 方案 A：改名openclaw agents add coder-v2# 方案 B：先删除后重建openclaw agents remove coderopenclaw agents add coder ...# 方案 C：直接更新已有代理配置 (推荐)openclaw agents update coder --model anthropic:claude-sonnet-4

7.2 报错：`Error: Model not found`

原因：填错了模型名称，或者该模型尚未在提供商列表中配置。解决：

# 查看系统支持的所有可用模型列表openclaw models list

7.3 配置文件路径拼写错误（静默失败）

这是开发者最容易踩的坑。config set 接受任意层级的路径，拼错了它不会报错，但配置将无法生效！

# 错误示范：把 defaults 拼成了 defautlsopenclaw config set agents.defautls.model.primary ...# 解决之道：使用 validate 校验配置文件的合法性openclaw config validate# 输出示例:# ⚠ Warning: agents.defautls.model.primary — unrecognized path (did you mean "agents.defaults"?)

7.4 权限不足：`Workspace directory not found`

原因：指定的 --workspace 目录在磁盘上不存在。解决：

# 添加 --create-workspace 参数，让 OpenClaw 帮你自动创建目录openclaw agents add my-bot --workspace ./nonexistent --create-workspace

八、总结

OpenClaw 的 CLI 体系设计得极具 UNIX 哲学：简单、组合、强大。

agents add 赋予了你快速搭建沙箱化代理的能力。利用 --template 和 --dry-run 能让你事半功倍。
agents list 结合 jq 等工具，能完美融入开发者的 CI/CD 工作流。
config set 的双层继承体系，让你可以精准调配每一分 API 算力成本。

掌握这些指令，不仅仅是为了“少敲几个字母”，更是为了在多代理协同（Multi-Agent）的复杂时代，构建出高性能、低成本且极具安全性的 AI 基础设施架构。希望这份指南能成为你桌面常驻的效率手册！