掌控 OpenClaw：核心命令行

引言：从执行者到架构师的跃迁

一个AI智能体平台是一台精密的机器。Web UI 提供了观察其灵魂的窗口，但真正的掌控权，源自命令行（CLI）------工程师的中央控制台。在这里，每一次敲击都直接与系统的核心交互，每一次命令的执行都可能重塑智能体的行为。

然而，将 CLI 仅仅视为命令的集合，会极大地限制您的潜力。本文的目标，是带领您越过命令的表象，直抵系统架构的核心。我们将不再满足于知道"这个命令是做什么的"，而是要去理解"在何种场景下、出于何种战略考量，我应该使用这个命令"。

摒弃枯燥的命令手册范式，为您提供一套"战略思想"。我们将把 OpenClaw 最核心的一批命令，按照逻辑功能进行分组，并深入剖析其背后的设计哲学。您将学到：

核心服务与诊断 (gateway, doctor): 如何像维护中枢神经系统一样，确保服务的稳定与健康。
配置管理 (config): 如何像编辑DNA序列一样，精准、安全地定义系统的一切行为。
智能体与能力扩展 (agents, skills, plugins): 如何构建AI的认知核心，并为其装备一个无限扩展的能力军火库。

当您读完本文，您将不再是一个简单的命令执行者，而是一位能够通过命令行驾驭整个 OpenClaw 平台的系统架构师。

您需要具备的基础

基本命令行操作能力: 熟悉在终端（Terminal）中执行命令。
OpenClaw 基础概念: 对智能体（Agent）、插件（Plugin）、技能（Skill）等核心概念有初步了解。

第一部分：生命体征 ------ 核心服务与状态诊断 (Gateway & Health)

在深入任何高级功能之前，我们必须确保系统的"生命体征"是平稳的。网关（Gateway）是 OpenClaw 的心跳，而医生（Doctor）则是它的免疫系统。掌握这组命令，是保障一切稳定运行的基石。

1.1 `gateway` 命令：系统的脉搏

gateway 是 OpenClaw 的心脏和中枢神经系统。它是一个持续运行的后台服务，负责处理所有客户端（Web UI、CLI、聊天工具等）的连接，管理会话，并将任务精准地路由给对应的智能体。如果 gateway 没有运行，OpenClaw 就是一个没有灵魂的躯壳。

深度解析

openclaw gateway start: 启动网关服务。这是最基础也是最重要的命令。
openclaw gateway stop: 停止在后台运行的网关服务。
openclaw gateway status: 检查网关服务的当前状态。它会告诉你服务是否在运行（running/stopped）、进程ID（PID）以及已经运行了多长时间。
openclaw gateway logs: 查看网关的实时或历史日志。这是排查问题的黄金矿山。

关键参数详解

-d 或 --detach: 以"守护进程"模式在后台启动 。关闭当前终端窗口后，服务会继续运行。这是生产环境部署的唯一正确方式。
--port <端口号>: 指定网关监听的端口 ，默认是 18789。当默认端口被占用或您需要在一个服务器上运行多个实例时，此参数至关重要。
--bind <地址>: 指定绑定的网络地址 。默认为 loopback (即 127.0.0.1)，这意味着只有本机可以访问网关。
- 安全警告 : 如果您想让其他计算机访问此 OpenClaw 服务，可以设置为 --bind 0.0.0.0。但请务必确保您的防火墙配置正确，并且了解这带来的安全风险。

实战策略

策略一："前台调试法"------快速定位实时错误

这是所有开发者和运维人员必须掌握的首要调试技巧。当遇到Web UI无响应、消息发送失败等问题时，与其大海捞针般地翻阅日志文件，不如直接在问题现场进行观察。

场景: 用户报告Web UI无法连接，发送消息后没有任何反应。
步骤 :
1. 首先，确保后台没有僵尸进程：openclaw gateway stop。
2. 然后，在终端中直接运行：openclaw gateway start (注意：不带 -d 参数)。
3. 此时，网关的所有实时活动，包括连接请求、消息收发、插件加载、错误报告，都会直接打印在您的终端窗口上。
4. 让用户再次尝试在Web UI上发送消息。
5. 观察终端输出 :
  - case A: 终端没有任何新输出
    - 诊断: 网络连接问题。客户端的请求根本没有到达网关。
    - 排查清单: 检查用户访问的IP和端口是否正确；检查服务器防火墙是否放行了该端口；检查中间是否有Nginx等反向代理配置错误。
  - case B: 终端打印出错误信息
    - 诊断 : 问题根源暴露。例如，您可能会看到 ERROR: Invalid API Key for model 'gpt-4' 或 ERROR: Plugin 'custom-plugin' failed to load due to missing dependency 'X'。
    - 解决: 根据清晰的错误提示，直接修复问题（如修正API密钥，安装依赖）。
  - case C: 终端显示已收到消息，但后续无响应
    - 诊断: 网关正常接收，问题出在后端处理逻辑，很可能是智能体配置或某个技能（Skill）执行时卡住了。
    - 下一步: 这将引导您去检查智能体的配置、模型设置或相关技能的日志。

架构洞察 (Architecture Insight)

"前台调试法"的本质是将系统从一个"黑盒"变成一个"白盒"，让你能实时观察到系统内部的数据流和控制流。这是最快、最有效的定位问题根源的方法。

策略二："生产环境部署清单"

在生产环境中，稳定性和可维护性是第一位的。以下是部署 gateway 服务的最佳实践。

使用守护进程 : 永远使用 openclaw gateway start -d 来启动服务。
端口规划 : 规划好一个固定的端口，并确保它不会与其他服务冲突。例如，openclaw gateway start -d --port 18789。
绑定地址 : 除非您明确需要公网访问，并已配置好安全措施，否则请保持默认的 loopback 绑定或绑定到内网IP。
日志管理 : 了解 openclaw gateway logs 的用法。可以配合 -f 参数实时跟踪日志 (tail -f 的效果)，或者使用 > 将日志重定向到指定文件进行归档。
进程监控 : 在生产环境中，应使用 systemd、supervisor 或 Docker 等工具来管理 OpenClaw 进程，确保在进程意外退出时能够自动重启。

1.2 `doctor` 命令：AI的私人医生

如果说 gateway 是心脏，那么 doctor 就是一位全科医生，定期为整个系统进行"体检"。它会自动扫描您的配置文件，检查环境依赖、插件兼容性、通道连接性，并报告潜在的安全风险。

深度解析

openclaw doctor: 运行一次完整的健康检查 。它会输出一份详细的体检报告，包含 [OK]、[WARNING] 和 [ERROR] 等状态。
openclaw doctor --fix: 尝试自动修复它发现的一些常见配置问题。例如，补全缺失的默认配置项。

实战策略

策略三："首诊负责制"------建立排错纪律

在团队中建立一个铁律：在遇到任何无法解释的"奇怪"问题时，第一步永远是运行 openclaw doctor。这能解决超过50%的配置类和环境类问题，极大地节省排错时间。

场景: 升级 OpenClaw 版本后，某个插件突然不工作了。
错误的做法: 一头扎进代码或日志，花费数小时进行调试。
正确的做法 :
1. 运行 openclaw doctor。
2. doctor 报告 [WARNING]: Plugin 'wecom' is incompatible with current core version. Expected ^1.5.0, found 1.4.2.。
3. 问题立刻明朗：插件版本与核心不兼容。
4. 解决: 更新或回滚插件版本。

Pro-Tip (专家提示)

将 openclaw doctor 命令加入到您的持续集成（CI）流程中。在每次代码提交或部署前自动运行一次健康检查，可以提前发现大量潜在问题。

策略四："读懂体检报告"

doctor 的报告是信息金矿，学会解读它至关重要。

[ERROR] : 必须立即解决的严重问题。例如，配置文件语法错误、核心数据库无法连接。不解决这些问题，系统根本无法正常运行。
[WARNING] : 需要关注的潜在问题 。这些通常不影响系统启动，但会在运行时导致特定功能异常。
- 案例 : [WARNING]: Channel 'wecom' is enabled, but required config key 'corp_id' is missing.
- 解读 : 这意味着 gateway 可以启动，但任何试图通过企业微信通道发送的消息都会失败。这精准地指出了问题的范围和原因。
[OK]: 表示该项检查通过。

第二部分：系统蓝图 ------ 配置与环境管理 (Configuration)

如果说 gateway 是系统的生命，那么配置文件（openclaw.json）就是描绘这个生命的蓝图，是系统的DNA。config 命令提供了一个安全、高效的方式来读取和修改这份蓝图。

2.1 `config` 命令：编纂系统的DNA

手动编辑 JSON 文件很容易出错，比如遗漏一个逗号或括号，就可能导致整个系统瘫痪。config 命令是一个非交互式的命令行工具，可以让你像操作数据库一样，精准地读写配置项，避免了手动编辑的风险。

深度解析

openclaw config get <键路径>: 获取一个配置项的值。键路径使用点 . 来分隔层级。
- 示例 : openclaw config get channels.wecom.enabled
openclaw config set <键路径> <值>: 设置一个配置项的值。它会自动处理值的类型（字符串、数字、布尔值）。
- 示例 : openclaw config set channels.wecom.enabled false
- 示例 : openclaw config set server.port 18800
openclaw config unset <键路径>: 删除一个配置项，使其恢复到默认值。
openclaw config path: 显示当前配置文件的绝对路径。当您不确定正在编辑哪个配置文件时，这个命令非常有用。

实战策略

策略五："自动化部署脚本"------实现基础设施即代码

在需要部署多个 OpenClaw 实例时，手动配置每一个实例是低效且易错的。config set 命令是实现自动化部署的核心工具。

场景: 为一个新项目快速搭建一套完整的 OpenClaw 环境，包括数据库连接、模型API密钥和默认智能体设置。
实现 : 编写一个 setup_openclaw.sh 脚本。

bash 复制代码

#!/bin/bash

# 设置数据库连接
openclaw config set database.type "postgres"
openclaw config set database.host "db.example.com"
openclaw config set database.port "5432"
openclaw config set database.user "admin"
openclaw config set database.password "your_secure_password"

# 设置默认的大语言模型
openclaw config set models.default "azure_gpt4_turbo"
openclaw config set models.providers.azure_openai.api_key "your_azure_api_key"
openclaw config set models.providers.azure_openai.endpoint "your_azure_endpoint"

# 启用并配置企业微信通道
openclaw config set channels.wecom.enabled true
openclaw config set channels.wecom.corp_id "wwxxxxxxxxxxxxxx"
# ... 其他配置

echo "OpenClaw environment setup complete!"

# 最后重启服务使配置生效
openclaw gateway stop
openclaw gateway start -d

这个脚本是可重复、可版本控制的，完美地诠释了"基础设施即代码"（Infrastructure as Code）的理念。

策略六："动态功能开关"------安全的灰度测试与A/B测试

当您开发了一个新功能（例如一个新插件或新技能）并希望先对一小部分用户进行测试时，config 命令可以作为强大的"功能开关"（Feature Flag）。

场景: 上线一个新的"网页内容总结"技能，但不确定其稳定性，希望在不影响主服务的情况下进行测试。
步骤 :
1. 默认禁用 : 在配置文件中，默认将此技能或相关插件禁用。
  openclaw config set plugins.entries.summary_plugin.enabled false
2. 创建测试智能体 : 使用 agents 命令创建一个专用的测试智能体（详见第三部分）。
  openclaw agents create skill-tester
3. 为测试智能体启用功能: 通过修改测试智能体的特定配置，为其单独开启该功能。（假设智能体配置支持独立插件开关）
4. 动态切换 : 如果需要在主智能体上临时开启进行测试，可以直接执行 config set ... true，然后重启 gateway。测试完成后，再执行 config set ... false 并重启，即可安全下线该功能，全程无需修改代码或手动编辑JSON。

第三部分：认知核心 ------ 智能体与能力扩展 (Agent & Skills)

这一部分我们触及AI的核心：它的大脑（Agent）、记忆和工具箱（Skills & Plugins）。这些命令决定了您的AI"是谁"以及"能做什么"。

3.1 `agents` 命令：塑造多重人格

OpenClaw 的强大之处在于它支持创建多个相互隔离的"智能体"（Agent）。每个智能体都可以拥有自己独立的工作区、模型配置、记忆库和启用的技能。这就像为一个组织雇佣了多位能力各异的专家。

深度解析

openclaw agents list: 列出所有已创建的智能体。
openclaw agents create <名称>: 创建一个新的智能体。
openclaw agents set-default <名称>: 设置一个默认智能体。所有未指定智能体的请求都会被路由到这里。
openclaw agents exec <智能体名称> -- <命令>: 以特定智能体的身份执行一个命令。这是一个非常强大的功能，允许您在不同智能体的上下文中执行操作。

实战策略

策略七："安全沙箱环境"------无风险测试新能力

在为您的主智能体（例如，一个正在为客户提供服务的客服AI）添加新技能或配置时，直接在生产环境上操作是极其危险的。正确的做法是建立一个"沙箱"（Sandbox）环境。

场景 : 您想测试一个社区开发的、能够执行服务器命令的 shell 技能，但担心其安全性。
步骤 :
1. 创建沙箱智能体 :
  openclaw agents create test-sandbox
2. 配置沙箱 : 为 test-sandbox 配置最低权限，例如使用一个能力较弱、成本较低的语言模型，并限制其文件访问权限。
3. 启用新技能 : 仅为 test-sandbox 智能体启用 shell 技能。
4. 隔离测试 : 使用 exec 命令进入该智能体的上下文进行测试。例如，启动一个专属于该智能体的TUI（文本用户界面）:
  openclaw agents exec test-sandbox -- tui
5. 在这个TUI中，您可以尽情测试 shell 技能的各种功能。即使出现问题，也只会影响到 test-sandbox 这个被隔离的智能体，完全不会波及到您正在提供服务的主智能体。

策略八："多租户服务架构"------为不同客户提供专属服务

如果您使用 OpenClaw 为多个客户或公司内部的不同部门提供服务，agents 命令是实现多租户架构的基础。

场景: 同时为"法务部"和"市场部"提供AI助手服务。
实现 :
1. 创建专属智能体 :
  openclaw agents create legal-assistant
  openclaw agents create marketing-assistant
2. 配置不同能力 :
  - 为 legal-assistant 加载法律术语知识库，并启用文档比对、条款检索等专业技能。
  - 为 marketing-assistant 连接社交媒体分析工具，并启用文案生成、热点追踪等营销技能。
3. 路由规则: 在您的应用入口（例如API网关）处，根据用户的身份（属于法务部还是市场部），将请求路由给对应的智能体。
4. 这样，法务部的用户永远不会调用到市场部的技能，反之亦然，实现了数据和能力的完全隔离。

3.2 `skills` & `plugins` 命令：构建能力军火库

这是扩展 OpenClaw 能力的两个核心概念，理解它们的区别至关重要。

Plugins (插件) : 是对 OpenClaw 核心功能的扩展。它通常用于集成第三方服务（如企业微信、Discord通道插件）或添加全新的底层能力（如一个新的数据库支持、一种新的认证方式）。插件是"平台的扩展"。
Skills (技能) : 是智能体可以使用的"工具"。例如上网搜索、文件读写、代码执行、调用计算器等。技能是"智能体的工具"。一个插件可能会向系统注册一个或多个新的技能。

深度解析

openclaw plugins list: 列出所有已安装的插件及其启用状态。
openclaw skills list: 列出所有可用技能，以及当前智能体是否已启用它们。
openclaw plugins enable/disable <名称>: 这通常是 openclaw config set plugins.entries.<插件名>.enabled true/false 的快捷方式。

实战策略

策略九："能力扩展全流程"------从需求到实现的闭环

掌握这个流程，您就可以像搭积木一样，不断增强 OpenClaw 的能力。

场景: 您的团队希望AI能够读取网页内容，并进行总结。
步骤 :
1. 识别需求: 需求是"获取并理解网页内容"。
2. 寻找能力模块 (插件) : 在 OpenClaw 官方市场或社区中，搜索关键词"web", "scrape", "url"。您可能会找到一个名为 web-reader 的插件。
3. 安装插件: 按照插件的说明进行安装（例如，通过包管理器）。
4. 验证与启用插件 :
  - 运行 openclaw plugins list，确认 web-reader 插件已成功加载。
  - 运行 openclaw config set plugins.entries.web-reader.enabled true 来启用它。
  - 重启网关：openclaw gateway stop && openclaw gateway start -d。
5. 发现并启用新技能 :
  - 插件启用后，它会向系统注册新的技能。运行 openclaw skills list。
  - 您可能会在列表中看到一个新的技能，例如 web.fetch_content。
  - 为您的智能体启用这个新技能（通常通过智能体的配置文件或相关命令）。
6. 测试与应用 : 现在，您的智能体在与用户对话时，就可以调用 web.fetch_content 这个工具来获取指定URL的内容，并在此基础上进行总结分析了。

这个从"需求"到"寻找插件"，再到"启用技能"的流程，是 OpenClaw 生态系统的核心工作模式。

结论：

我们已经走过了一段漫长的旅程，从确保系统心跳的 gateway，到塑造AI人格的 agents。现在，这些命令在您眼中，应该不再是孤立的工具，而是一套环环相扣、用于构建和指挥复杂AI系统的架构控制台。

让我们回顾一下您已掌握的高级战术：

策略一："前台调试法": 将系统黑盒变白盒，实时捕获错误。
策略二："生产环境部署清单": 确保服务的稳定、安全与可维护。
策略三："首诊负责制" : 将 doctor 作为排查任何问题的起点。
策略四："读懂体检报告": 从警告和错误中精准定位问题根源。
策略五："自动化部署脚本" : 使用 config 命令实现基础设施即代码。
策略六："动态功能开关": 安全地进行灰度发布和A/B测试。
策略七："安全沙箱环境": 在隔离区中无风险地测试新能力。
策略八："多租户服务架构": 为不同用户群体提供专属、隔离的AI服务。
策略九："能力扩展全流程": 掌握从需求到功能上线的完整闭环。

OpenClaw 的命令行远不止于此，但您现在已经掌握了其最核心的哲学。真正的精通，始于将这些策略融会贯通，并结合您的具体业务场景，创造出属于您自己的、高效、自动化的管理工作流。

掌控 OpenClaw：核心命令行

引言：从执行者到架构师的跃迁

您需要具备的基础

第一部分：生命体征 ------ 核心服务与状态诊断 (Gateway & Health)

1.1 gateway 命令：系统的脉搏

深度解析

关键参数详解

实战策略

1.2 doctor 命令：AI的私人医生

深度解析

实战策略

第二部分：系统蓝图 ------ 配置与环境管理 (Configuration)

2.1 config 命令：编纂系统的DNA

深度解析

实战策略

第三部分：认知核心 ------ 智能体与能力扩展 (Agent & Skills)

3.1 agents 命令：塑造多重人格

深度解析

实战策略

3.2 skills & plugins 命令：构建能力军火库

深度解析

实战策略

结论：

1.1 `gateway` 命令：系统的脉搏

1.2 `doctor` 命令：AI的私人医生

2.1 `config` 命令：编纂系统的DNA

3.1 `agents` 命令：塑造多重人格

3.2 `skills` & `plugins` 命令：构建能力军火库