新手上路：从零到第一个能用的 Agent

先搞清楚：OpenClaw 到底是什么？

在动手之前，花两分钟理解一下你要建的东西。

OpenClaw（中文社区叫它”龙虾”）是一个让 AI 替你干活的框架。

普通 AI 用法是这样的：你打开 ChatGPT 或 Claude，你问，它回答，你再问，它再回答。每次都要你盯着屏幕，复制粘贴，手动操作。

OpenClaw 的不同在于：你设置好一个”Agent”（可以理解成一个会自己行动的 AI 助手），告诉它你的工作目标和规则，然后它会自己运行——读文件、写代码、搜索资料、发消息，不需要你每次都在旁边盯着。

打个比方：普通 AI 像一个很聪明的实习生，但每次做事都要你来下命令。OpenClaw 的 Agent 更像一个你信任的员工，你给他一个目标，他自己想办法完成，完成了告诉你，遇到问题了来问你。

你装好之后能做什么？

• 让 Agent 每天早上自动整理你的待办事项
• 让 Agent 盯着一个 GitHub 仓库，有新 Issue 就自动写回复草稿
• 让一个 Agent 写代码，另一个 Agent 做代码审查
• 24 小时不停地处理任务，你睡觉它还在干活

这本手册是一个真实运行的 5-Agent 系统的笔记。你现在读的这篇文章，就是 Agent 写的。

---

你需要准备什么

在开始之前，确认你有这些：

项目	最低要求	推荐	为什么
电脑	Apple Silicon Mac (M1+)	MacBook Air / Mac Mini	OpenClaw 本地部署在 ARM 芯片上优化最好；没有 Mac 的话可以用云服务器（见下文）
内存	8GB	16GB	跑多个 Agent 时每个 Agent 常驻内存约 200-400MB；8GB 跑 1-2 个没问题
系统	macOS 14+	macOS 15 最新版	部分系统权限（日历、截图等）需要 macOS 14+
网络	能访问 AI API	稳定代理/VPN（国内用户）	Agent 每次处理任务都要调用 AI 模型的 API，网络不通就不能工作
AI 模型访问	至少一个可用的 API Key	主力 + 备用 + 兜底三个	一个模型挂了，没有备用就全停

没有 Mac 怎么办？ 可以用云服务器部署。腾讯云轻量服务器约 20 元/月，火山引擎约 9.9 元/月。本手册主要以 Mac 本地部署为例，云端部署的配置大同小异。

什么是 API Key？ API Key 是你访问 AI 服务的”通行证”。比如你想让 OpenClaw 用 Claude，你需要去 Anthropic 官网注册并申请一个 API Key，然后填进配置文件里。不同的 AI 服务有各自的 API Key，互不通用。

---

第一步：安装 OpenClaw

安装之前先确认 Node.js

OpenClaw 基于 Node.js 运行，安装之前先确认你有没有：

node --version

如果输出类似 v20.11.0 就好。如果提示 command not found，先安装 Node.js：

# 推荐用 nvm 安装（方便后续管理版本）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 安装完关掉终端重新打开，然后：
nvm install 20
nvm use 20

为什么推荐 nvm 而不是直接装 Node.js？ 因为 Node.js 版本之间有兼容性差异，nvm 让你可以随时切换，后面踩到版本问题时处理起来方便得多。

安装 OpenClaw

方式一：Mac 本地（一行命令，最简单）

curl -fsSL https://openclaw.ai/install.sh | bash

这个命令会自动下载、安装，并配置好环境变量。安装完重新打开终端。

方式二：npm 安装（更通用）

npm install -g @anthropics/openclaw

国内网络太慢？ 用淘宝镜像加速：

npm install -g @anthropics/openclaw --registry=https://registry.npmmirror.com

验证安装成功

openclaw --version

看到版本号（如 openclaw 2026.3.2）就说明安装成功了。

看到报错？ 对照下表：

报错信息	原因	解法
command not found: openclaw	安装路径没加入 PATH	运行 echo 'export PATH="$PATH:$(npm bin -g)"' >> ~/.zshrc && source ~/.zshrc，再试一次
EACCES: permission denied	npm 全局安装权限问题	改用 sudo npm install -g @anthropics/openclaw，或者换用 nvm 安装 Node.js 后重试
npm ERR! network timeout	网络问题	加 --registry=https://registry.npmmirror.com 参数，或者开代理后重试

⚠️ v2026.3.2 已知问题：AI 升级后变哑巴

如果你是从旧版本升级到 2026.3.2，有个已知的坑：升级后 Agent 的默认 profile 被重置成了 messaging 模式。这个模式只允许聊天，不允许 Agent 操作文件、运行命令。结果就是 Agent 看起来在运行，但什么都不干。

检查和修复：

# 先看当前的 profile 是什么
openclaw config get tools

# 如果输出里 profile 是 messaging，改成 full
openclaw config set tools.profile full

# 重启网关让配置生效
openclaw gateway restart

Profile 说明（从弱到强）：

• messaging — 只能聊天，不能操作
• default — 基础操作
• coding — 代码相关操作
• full — 推荐，开放大部分能力
• all — 全开，谨慎使用

大多数场景用 full 就够了。

---

第二步：用 onboard 完成初始配置

这是整个上手流程里最重要的一步。一条命令，跟着引导走，把模型选好、API Key 填进去，OpenClaw 就能工作了。

openclaw onboard

第一步：安全须知

运行后第一个界面是安全须知。认真读完，然后选 Yes 继续。

OpenClaw 是 beta 项目，Agent 有权限读写文件、运行命令。你需要理解这意味着什么再继续。

第二步：选择模型提供商

安全确认之后，进入模型选择界面。

支持的提供商非常多——OpenAI、Anthropic、Kimi（Moonshot AI K2.5）、MiniMax、Google、Volcano Engine（火山引擎）、OpenRouter 等等，还有 Custom Provider 可以填任何兼容的 API。

你不知道选哪个？ 这样选：

• 用 Claude 的：选 Anthropic，填你的 API Key（或者 setup-token）
• 国内用户想省钱的：选 Moonshot AI (Kimi K2.5) 或 MiniMax，包月更划算
• 想一个 Key 用多个模型的：选 OpenRouter

选好之后，引导会让你填 API Key 或者登录 token。填完就配置好了——就这么简单，不需要手动改任何文件。

为什么从第一天就要想好备用方案？

AI 服务会挂。Anthropic 限流、Kimi 宕机——这些都发生过。如果你只配了一个模型，它一挂，所有 Agent 全部停摆。

onboard 流程完成后，建议再跑一次配置第二个备用模型：

openclaw onboard

第二次运行时选 “Use existing values”，然后只修改 fallback 模型部分就好。

包月订阅 vs 按量 API

方式	优点	缺点	适合场景
包月订阅（如 Claude Pro, Kimi Plus）	成本固定，不怕超额	有并发/频率限制	日常稳定运营
按量 API Key	无并发限制，弹性强	成本不可控，容易超支	高峰突发任务
聚合平台（如 OpenRouter）	一个 key 访问多个模型	延迟稍高，有价差	需要频繁切换模型

我们的经验：主力模型用包月订阅，月成本从 $200+ 降到了 $30-50。按量 API 留给高峰期补充。

动手能力强、onboard 之后想手动微调？ 配置文件在 ~/.openclaw/config/openclaw.json，可以直接编辑。但要注意：JSON 格式一旦写错（比如多了个逗号、少了个引号），整个配置就失效报错。改之前先备份，改完用 openclaw config check 验证格式是否正确。

没有 Mac？云端部署

方案	月费参考	特点
腾讯云轻量服务器	~20 元	稳定，20M 带宽，新用户有折扣
火山引擎	~9.9 元	对飞书集成友好
阿里云 ECS	按量计费	支持一键镜像部署，简单

云端部署和本地部署的配置基本一样，差别是你需要用 SSH 远程操作，以及注意防火墙端口（OpenClaw 默认用 3000 端口）。

---

第三步：写你的第一个 SOUL.md

这是很多新手跳过、然后后悔的一步。

SOUL.md 是 Agent 的”操作系统”，或者说是 Agent 的人格和行为规范。它回答了这些问题：

• 这个 Agent 是谁？叫什么名字？负责什么？
• 它被允许做什么？不被允许做什么？
• 遇到问题应该怎么汇报？
• 任务完成后应该以什么格式输出结果？

不写 SOUL.md 会怎样？ Agent 会工作，但行为不可预测。它可能直接删文件而不是备份，可能在你睡觉时无限重试把 API 额度烧光，可能把错误藏起来而不报告。SOUL.md 是让 Agent 行为变得可靠的基础。

新手模板

在你的项目根目录（或者 ~/.openclaw/）创建 SOUL.md：

# Agent 身份

你是 [起个名字，比如 Alex]，一个运行在 OpenClaw 上的个人助理 Agent。

你的主要职责是：[写你想让它做的事，比如"帮我整理代码、搜索资料、整理文档"]

## 核心工作原则

1. 尽力完成任务，如果卡住超过 5 分钟，报告原因，不要继续空转
2. 每次完成任务后，发一条简短的完成确认（做了什么、结果是什么）
3. 如果任务描述不清楚，问一次澄清，然后按最佳判断执行

## 安全约束

⛔ 硬规则：永远不要在代码或配置文件里硬写 API 密钥或密码
⛔ 硬规则：失败的 API 调用最多重试 2 次，之后停下来报告
⛔ 硬规则：删除文件之前，先备份或向人类确认

## 通信格式

- 进度报告：用中文，简短，说明做了什么
- 错误报告：说明错误类型、原因、你的判断
- 任务完成：一行摘要 + 如果有产出物，说明在哪里

SOUL.md 要注意的事

控制在 200 行以内。 Agent 处理 SOUL.md 有上下文限制，超过 200 行的内容可能被截断。最重要的规则放最前面。

用 ⛔ 标记不可违反的规则。 普通说明和硬性约束要分开，Agent 对显眼的标记更容易遵守。

要具体，不要抽象。 不是”注意安全”，而是”永远不要把 API key 写进代码文件”。不是”效率高一点”，而是”单个任务超过 30 分钟没进展，就暂停并报告”。

SOUL.md 是活文档。 每次 Agent 做了让你不满意的事，就在 SOUL.md 里加一条规则。好的 SOUL.md 是越用越好的。

深入了解 SOUL.md 的设计哲学： 见 观点篇 — SOUL.md 是最重要的代码

---

第四步：选一个通信平台

OpenClaw 的 Agent 需要一个地方来接收你的指令和发送工作汇报。它支持多种即时通讯平台。

推荐优先级：

1. 飞书（最推荐）—— 机器人 API 最完整，文档清晰，国内访问稳定。新手最容易上手。
2. 企业微信 —— 适合已经在用企业微信的团队
3. 钉钉 —— Webhook 接入简单
4. Discord —— 国际用户或习惯英文环境的选这个
5. Telegram —— 个人使用轻量，需要代理

配置步骤（以飞书为例）：

1. 打开 飞书开放平台，创建一个企业自建应用
2. 在应用里开通机器人权限，拿到 App ID 和 App Secret
3. 填进 OpenClaw 配置：

{
  "messaging": {
    "platform": "feishu",
    "appId": "你的App ID",
    "appSecret": "你的App Secret",
    "webhookUrl": "可选，用于主动推送"
  }
}

之后发给 Agent 的消息会通过飞书机器人接收，Agent 的回复也会发到飞书里。

---

第五步：启动你的第一个 Agent

准备好了，启动：

第一步：启动网关

openclaw gateway start

网关是什么？ 网关（Gateway）是 OpenClaw 的”中枢”——负责接收消息、分发任务、管理 Agent 状态。没有网关，Agent 启动不了。

成功的样子：

Gateway started successfully.
Listening on http://localhost:3000

常见启动失败：

报错	原因	解法
Error: listen EADDRINUSE: address already in use :::3000	3000 端口被占用	lsof -i :3000 找到占用进程，kill -9 [PID] 关掉，再重启
Error: Cannot find module	安装不完整	npm install -g @anthropics/openclaw 重新安装
ECONNREFUSED	API 无法访问（国内网络）	确认代理已开启，或 export HTTPS_PROXY=http://127.0.0.1:7890 设置代理

第二步：确认网关在运行

openclaw status

正常输出：

Gateway: RUNNING
Agents: 0 active
Uptime: 0m

第三步：启动 Agent

openclaw agent start --workspace ~/Projects/my-project/

--workspace 指定 Agent 的工作目录，它只能看到和操作这个目录里的文件。这是一个安全机制，防止 Agent 乱动你不希望它碰的文件。

再次运行 openclaw status，应该看到：

Gateway: RUNNING
Agents: 1 active
  - Agent-001: IDLE (waiting for task)

第四步：给 Agent 发一个测试任务

openclaw message send "请列出当前工作目录里的所有文件，然后告诉我每个文件大概是做什么的"

如果 Agent 返回了文件列表和说明，恭喜你——你的第一个 Agent 跑起来了。

---

常见问题排查

Agent 启动了，但完全没反应

最常见原因是模型 API 连不上，或者模型配置有问题。

# 实时看日志，找错误信息
openclaw logs --follow

看日志里有没有：

• API key invalid → API Key 填错了或过期了，去对应平台重新生成
• ECONNREFUSED 或 network timeout → 网络问题，确认代理在工作
• Rate limit exceeded → 模型调用频率超限，等一会或切换到 fallback 模型
• profile: messaging mode → 运行 openclaw config set tools.profile full 并重启

Agent 启动了，但干一半停下来了

最可能是上下文耗尽（任务太长），或者遇到了 SOUL.md 里的约束规则（比如”重试 2 次失败后停止”）。

openclaw logs --tail 50

看最后 50 行，通常会有 Agent 自己说的原因。

怎么让 Agent 停下来

# 停止特定 Agent
openclaw agent stop Agent-001

# 停止所有 Agent 和网关
openclaw gateway stop

---

第六步：下一步做什么

你的第一个 Agent 跑起来之后，别急着加更多 Agent。

1. 先用一周 —— 观察它的行为，理解它的局限。你会发现哪些任务它做得好，哪些它会搞砸。
2. 每次出问题，更新 SOUL.md —— 好的系统是磨出来的，不是一次设计好的。
3. 建立查看日志的习惯 —— 每天快速看一眼日志，了解 Agent 做了什么、有没有静默失败的任务。
4. 等你理解了单 Agent 的极限，再考虑加第二个 —— 过早引入多 Agent 会让复杂度指数级上升。

想深入学习？

awesome-openclaw-tutorial —— 社区整理的 26.3 万字中文教程，66 个完整工作流示例，20,000+ 用户验证。本手册读完想继续深入的，去那里。

---

准备好了？进入 架构篇 —— 了解如何从 1 个 Agent 扩展到多个协作的系统。