1. 项目概述：打造你的专属AI副驾

最近在折腾AI智能体，发现了一个挺有意思的开源项目叫OpenClaw。简单来说，它允许你在自己的服务器上部署一个拥有长期记忆、能调用工具、并且可以接入Telegram、Discord等通讯渠道的“AI副驾”。这和我们平时用的ChatGPT网页版或者API调用完全不同，它是一个可以7x24小时运行、持续学习你、并为你执行具体任务的自主智能体。

项目作者Igor Ivanter提供了一个名为 openclaw-quickstart 的极简模板仓库，号称能在几分钟内帮你搭建起一个“认识你”的AI代理。我实际部署体验下来，发现它的核心理念非常清晰： 通过一组结构化的Markdown文件来定义智能体的灵魂（Soul）、身份（Identity）、对你的了解（User）以及它能做什么（Tools） ，而不是通过复杂的图形界面或冗长的配置文件。这种方式对于开发者或者喜欢折腾的技术爱好者来说，上手门槛低，定制化程度高。

这个模板适合谁呢？如果你对AI自动化有浓厚兴趣，不满足于简单的问答机器人，希望有一个能理解你的上下文、主动为你处理重复性工作（比如整理会议纪要、监控特定信息、管理待办事项）的智能助手，并且你愿意花点时间在命令行和文本编辑器上进行配置，那么OpenClaw会是一个非常有潜力的玩具，甚至生产力工具。接下来，我会结合自己的部署和配置过程，详细拆解这个模板的每一个部分，并分享一些从零到一让AI智能体真正“活”起来的实操心得。

2. 核心设计哲学与工作空间解析

2.1 以“工作空间”为中心的智能体架构

OpenClaw的设计非常“Unix哲学”：一个工具只做好一件事，并且通过清晰的接口组合在一起。它的核心单元不是某个复杂的应用，而是一个名为 workspace 的目录。这个目录就是智能体的“大脑”和“记忆库”。所有关于智能体如何思考、它服务于谁、它能做什么的定义，都通过一组Markdown文件来完成。

这种设计有几个显著优势：

  1. 可移植性与版本控制 ：整个工作空间就是一堆文本文件，你可以用Git轻松管理它的版本迭代。今天给智能体增加了新技能，明天调整了它的核心目标，所有的变更历史一目了然，也方便回滚。
  2. 人类可读与可编辑 ：配置不是藏在二进制或JSON深处。你或你的团队成员可以直接阅读和修改这些Markdown文件来调整智能体的行为，学习成本极低。
  3. 模块化与清晰分离 ：每个文件职责单一。 USER.md 只关于你， SOUL.md 只关于使命， TOOLS.md 只关于工具。这种分离使得维护和更新变得非常容易，不会牵一发而动全身。

模板中的文件结构看似简单，但每一份都承载着关键信息：

  • AGENTS.md ： 定义智能体的 操作规则 。你可以把它理解为公司的员工手册。里面规定了智能体在什么情况下应该采取什么行动，回复的格式应该怎样，遇到模糊请求时如何追问澄清。这是塑造智能体行为边界和风格的关键文件。
  • SOUL.md ： 定义智能体的 核心使命与价值观 。这是它的“北极星”。内容不是“帮我做事”，而是更本质的“优化什么”。例如，“最大化用户每日的深度工作时间”或“确保用户不错过任何重要的行业动态”。这为智能体的所有决策提供了最高层次的指导原则。
  • USER.md ： 这是关于 你的档案 。智能体对你的了解全部来源于此。你的职业、当前项目、长期目标、沟通偏好（喜欢简洁还是详细）、甚至你的时区。信息越丰富、越具体，智能体提供的帮助就越个性化和精准。
  • TOOLS.md ： 智能体的 技能清单 。它列出了智能体被授权可以调用的所有命令行工具、API接口及其使用方式。例如，它可能被允许使用 curl 查询某个API，用 jq 处理JSON，或者调用一个本地的Python脚本。这里需要详细说明每个工具的目的、命令格式和所需的认证信息（通过环境变量或配置文件引用，切记不要将密钥硬编码在此文件中）。
  • IDENTITY.md ： 给智能体一个 人格化外壳 。包括名字、角色（如“效率副驾”、“研究助手”）、一个代表它的表情符号，以及整体的“氛围感”（如“专业且高效”、“热情且鼓励型”）。这决定了它与你互动时的“语气”和“人设”。
  • HEARTBEAT.md ： 定义 主动检查任务 。这是实现“智能体主动找你”功能的关键。你可以在这里设置定时任务，比如“每天上午9点检查我的日历，并提醒我今天的第一个会议”，“每周一总结上周的项目进展”。智能体会定期扫描这个文件并执行里面定义的任务。
  • MEMORY.md ： ** curated长期记忆**。这不是聊天记录，而是由你或智能体共同维护的、经过提炼的重要信息。例如，项目关键决策、重要的联系人信息、达成的共识等。智能体在思考时会参考这部分记忆。
  • memory/ 目录 ： 存放 原始会话记录 。与智能体的每一次对话都会被自动记录在这里，作为它学习和回顾的原始材料。这个目录是自动生成和管理的。

2.2 配置文件与环境变量：连接现实世界的桥梁

工作空间定义了智能体的“内在”，而根目录下的 openclaw.json 和 .env 文件则是连接“内在”与“外在”世界的桥梁。

openclaw.json - 主配置文件 这个文件告诉OpenClaw核心系统如何运行。你需要关注几个关键部分：

  • workspaceDir : 必须正确设置 。它应该指向你本地的 workspace 目录的绝对路径或相对于配置文件的位置。如果路径错误，智能体将无法加载它的“大脑”。
  • model : 指定使用的AI模型提供商和型号（如 openai/gpt-4o ， anthropic/claude-3-sonnet ）。这直接决定了智能体的“基础智力”水平和成本。
  • channel ： 配置智能体与你的交互渠道，比如Telegram机器人、Discord机器人或内置的WebChat。每个渠道需要各自的配置（如Bot Token）。
  • plugins : 启用系统级插件来扩展核心功能，比如是否需要联网搜索、访问特定数据库等。

.env - 密钥与敏感信息 这是最重要的安全文件。模板提供了一个 .env.template ，你需要复制它为 .env 并填入所有必要的密钥。

重要安全提示 ： .env 文件已被 .gitignore 排除在版本控制之外， 永远不要 将它提交到Git仓库。这里通常包括：

  • OPENAI_API_KEY : 如果你使用OpenAI的模型。
  • ANTHROPIC_API_KEY : 如果你使用Claude模型。
  • TELEGRAM_BOT_TOKEN 和 TELEGRAM_BOT_USERNAME : 用于配置Telegram通道。
  • DISCORD_TOKEN : 用于配置Discord通道。
  • 其他任何在 TOOLS.md 或插件中引用的API密钥。

3. 从零开始的详细部署与配置指南

3.1 基础环境准备与项目克隆

首先，确保你的运行环境满足基本要求。OpenClaw本身可能需要Docker或者直接的Node.js/Python环境（具体请查阅官方文档）。这里假设你是在一个Linux/macOS的终端或Windows的WSL环境下操作。

第一步是获取模板。打开终端，执行以下命令：

# 克隆模板仓库，并重命名为你喜欢的项目目录名
git clone https://github.com/IgorIvanter/openclaw-quickstart my-personal-agent
cd my-personal-agent

执行后，你就拥有了一个名为 my-personal-agent 的目录，里面包含了上一节介绍的所有模板文件。建议立即将这个目录初始化为你自己的Git仓库，以便后续追踪更改：

# 删除原有的.git文件夹（这是模板的，不是你的）
rm -rf .git
# 初始化你自己的Git仓库
git init
git add .
git commit -m "Initial commit from openclaw-quickstart template"

3.2 核心配置文件定制详解

接下来是赋予智能体灵魂的关键步骤——编辑配置文件。

1. 配置环境变量 

# 复制环境变量模板
cp .env.template .env
# 使用你喜欢的编辑器（如VS Code, nano, vim）编辑.env文件
code .env

在打开的 .env 文件中，找到类似 OPENAI_API_KEY= 的行，将你的实际API密钥填入等号右侧。 请务必确保每一行都没有多余的空格 ，特别是键和值之间。例如：

OPENAI_API_KEY=sk-your-actual-openai-api-key-here
TELEGRAM_BOT_TOKEN=1234567890:ABCdefGhIJKlmNoPQRsTUVwxyZ

保存并关闭文件。

2. 定制工作空间文件 这是最需要花心思的部分。不要试图一次性填满所有文件，建议按以下顺序和思路进行：

  • 首先，编辑 workspace/USER.md ： 这是智能体认识你的起点。不要只写“我是一个软件工程师”。试着这样写：

    ## 我是谁
-   **姓名**： [你的名字或昵称]
-   **角色**： 全栈开发工程师，目前专注于云原生和AI应用开发。
-   **当前核心项目**： 正在构建一个内部用的数据分析仪表板，使用React前端和FastAPI后端，数据库是PostgreSQL。
-   **短期目标（本周）**： 完成仪表板用户认证模块的API联调。
-   **长期兴趣**： 自动化、效率工具、 indie hacking。
-   **沟通风格偏好**： 喜欢直接、有条理的回答。在提供解决方案时，如果能附带简短的代码片段或命令示例更好。
-   **需要帮助的领域**： 代码调试、技术方案调研、日常任务提醒、会议要点总结。

    你提供的信息越具体、场景越丰富，智能体后续的回应就越有针对性。

  • 其次，定义 workspace/SOUL.md ： 为智能体确立一个高层次的目标。避免模糊的“帮助我”。例如：

    # 核心使命
你的首要目标是作为我的技术副驾，**提升我的编码和研发效率**，并**保护我的注意力免受琐事干扰**。

## 价值观与原则
1.  **主动而非被动**： 在发现可以自动化的重复模式或潜在风险时，主动提出建议。
2.  **准确高于速度**： 提供的代码、命令或信息必须经过验证，宁可多确认一步，也不要给出可能出错的答案。
3.  **上下文感知**： 始终结合`USER.md`中关于我和我当前项目的背景信息来思考问题。
4.  **尊重边界**： 除非在`HEARTBEAT.md`中明确授权或我直接要求，否则不要主动打断我。

    这个文件为智能体的所有行为提供了伦理和战略框架。

  • 然后，塑造 workspace/IDENTITY.md ：

    -   **Name**: DevMate
-   **Role**: 效率编码副驾
-   **Emoji**: ⚙️
-   **Vibe**: 专业、冷静、可靠。像一位经验丰富的资深工程师，话不多但句句在点子上。在提供复杂方案时，会先给出概要，再询问是否需要展开细节。

    这个名字和形象会在对话中体现出来，让交互更有温度。

  • 接着，装备 workspace/TOOLS.md ： 这是智能体的“双手”。初期可以从最简单的开始。假设你允许它帮你执行一些系统命令：

    # 可用工具
## 系统与文件操作
-   `ls`： 列出目录内容。用于帮我查看项目文件结构。
    -   示例： `ls -la ./src/components`
-   `find`： 查找文件。
    -   示例： `find . -name "*.py" -type f`
-   `grep`： 在文件中搜索文本。
    -   示例： `grep -r "TODO" ./src`

## 网络与API（需配置环境变量）
-   `curl`： 调用HTTP API。用于快速测试后端端点。
    -   认证： 使用环境变量`INTERNAL_API_TOKEN`。
    -   示例： `curl -H "Authorization: Bearer $INTERNAL_API_TOKEN" https://api.internal.com/status`

    重要 ： 在授予任何可能修改系统或访问敏感数据的工具权限（如 rm , git push , 生产环境数据库命令）时，必须极度谨慎。最好在 AGENTS.md 中设置明确的约束规则。

  • 最后，规划 workspace/HEARTBEAT.md ： 设置一些轻量级的主动任务。例如：

    ## 每日任务
-   **时间**： 每个工作日 09:00 (我的时区)
-   **动作**： 检查`/tmp/daily_standup.txt`文件是否存在。如果存在，读取内容并向我摘要汇报；如果不存在，提醒我“今日站会笔记还未创建”。
-   **目的**： 帮助我形成每日站会的记录习惯。

## 每周任务
-   **时间**： 每周一 10:00
-   **动作**： 向我发送消息：“新的一周开始啦！请花5分钟回顾一下`USER.md`中的本周目标，是否需要调整或分解任务？”

    心跳任务让智能体从“应答机”转变为“提醒者”。

3. 修改 openclaw.json 用编辑器打开 openclaw.json 。最关键的一步是确认 workspaceDir 路径是否正确。如果你在项目根目录下启动OpenClaw，那么通常保持 "workspaceDir": "workspace" 即可。同时，根据你的 .env 配置，选择正确的模型和启用你想要的渠道（如Telegram）。

3.3 启动与初次对话

配置完成后，就可以启动智能体了。根据OpenClaw的官方安装指南，启动命令通常是：

# 假设你已通过npm或docker安装了openclaw命令行工具
openclaw gateway start
# 或者使用docker-compose
docker-compose up

启动成功后，控制台会输出服务运行的地址和端口（例如 http://localhost:3000 ），以及你配置的机器人连接信息。

进行第一次对话 ：

  • 如果配置了WebChat，直接访问 http://localhost:3000 。
  • 如果配置了Telegram，去Telegram找到你的Bot，发送 /start 。

尝试用一些简单的指令测试，例如：“嗨，DevMate，介绍一下你自己。” 或者 “根据你对我的了解，我现在应该优先做什么？” 观察它的回复是否融合了 IDENTITY.md 和 USER.md 中的信息。

4. 高级技巧与实战经验分享

4.1 如何设计高效的 AGENTS.md （代理规则）

AGENTS.md 是智能体的“宪法”，写得好能极大提升协作效率。以下是一些设计原则和示例：

  1. 分场景制定规则 ： 不要写成一锅粥。可以按任务类型分类。

    ## 当被问及代码或技术问题时
-   首先，尝试理解问题是否与用户当前项目（参考`USER.md`）相关。
-   如果相关，优先从项目上下文和技术栈出发思考解决方案。
-   提供的代码片段必须完整、可运行，并注明所需的环境或依赖。
-   如果涉及复杂操作，先提供步骤概述，询问用户是否继续。

## 当被要求执行工具（`TOOLS.md`中的命令）时
-   在执行任何具有潜在风险的操作（如删除文件、重启服务）前，必须向用户**明确陈述该操作的影响**并请求最终确认。
-   对于查询类命令（如`ls`, `grep`），可以直接执行并返回结果，但结果如果过长，应提供摘要或建议查看方式。

## 通用交互规则
-   保持回复简洁，但随时准备应要求提供更深入的细节。
-   如果用户的请求模糊，通过提问来澄清具体需求、期望格式或截止时间。
-   所有基于外部信息（非`WORKSPACE`内）的建议，都应注明“根据公开信息”或“这是一个假设”。

  2. 引入“思考过程”提示 ： 可以要求智能体在回答复杂问题前，先输出它的思考链。这不仅能让你理解其推理过程，也能在出现偏差时及时纠正。这通常需要在 openclaw.json 的模型配置或系统提示词中设置。

4.2 利用 MEMORY.md 实现持续学习

MEMORY.md 不是聊天记录的备份，而是知识的结晶。你应该和智能体共同维护它。

  • 手动提炼 ： 在一次有价值的深度对话后，主动将结论、决策或学到的关键点整理成条目，添加到 MEMORY.md 。例如：

    ## 项目决策记录 - 2023-10-27
-   **决策**： 在数据分析仪表板项目中，选择使用Chart.js而非D3.js进行可视化。
-   **原因**： 开发周期紧，Chart.js上手更快，且能满足当前所有图表需求。D3.js虽然更强大，但学习成本过高。
-   **相关文件**： `./docs/tech-selection.md`

  • 指令智能体总结 ： 你可以对智能体说：“将我们刚才关于API认证方案讨论的最终结论，用简洁的格式总结到 MEMORY.md 中。” 一个设计良好的智能体在拥有相应工具权限后，可以帮你完成这个动作。

4.3 工具集成实战：连接真实世界

让智能体真正强大的，是它能安全、可靠地调用外部工具。以下是一个为智能体集成“发送电子邮件”工具的进阶示例：

  1. 在 .env 中配置密钥 ：

    SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-specific-password  # 注意：不要用邮箱登录密码，用应用专用密码

  2. 在 TOOLS.md 中定义工具 ：

    ## 通信工具
-   `send_email`： 通过SMTP发送电子邮件。
    -   **执行方式**： 调用本地脚本 `./scripts/send_email.py`
    -   **参数**：
        -   `to`: 收件人邮箱
        -   `subject`: 邮件主题
        -   `body`: 邮件正文
    -   **示例**： `send_email --to "colleague@company.com" --subject "项目更新" --body "已完成模块A的初版开发。"`
    -   **安全警告**： 此工具仅限用于发送非敏感的工作进度通知。禁止用于发送任何形式的营销邮件或私人信息。

  3. 创建工具脚本 ( ./scripts/send_email.py )：

    #!/usr/bin/env python3
import smtplib
from email.mime.text import MIMEText
from email.header import Header
import os
import sys
import argparse

def send_email(to, subject, body):
    smtp_host = os.getenv('SMTP_HOST')
    smtp_port = int(os.getenv('SMTP_PORT', 587))
    smtp_user = os.getenv('SMTP_USER')
    smtp_password = os.getenv('SMTP_PASSWORD')

    msg = MIMEText(body, 'plain', 'utf-8')
    msg['From'] = smtp_user
    msg['To'] = to
    msg['Subject'] = Header(subject, 'utf-8')

    try:
        with smtplib.SMTP(smtp_host, smtp_port) as server:
            server.starttls()
            server.login(smtp_user, smtp_password)
            server.send_message(msg)
        print(f"邮件已成功发送至 {to}")
    except Exception as e:
        print(f"发送邮件失败: {e}", file=sys.stderr)
        sys.exit(1)

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description='发送电子邮件')
    parser.add_argument('--to', required=True, help='收件人邮箱')
    parser.add_argument('--subject', required=True, help='邮件主题')
    parser.add_argument('--body', required=True, help='邮件正文')
    args = parser.parse_args()
    send_email(args.to, args.subject, args.body)

    并赋予执行权限： chmod +x ./scripts/send_email.py

  4. 在 AGENTS.md 中设置使用规则 ：

    ## 使用`send_email`工具时
-   必须明确告知用户邮件的收件人、主题和正文内容，并等待用户明确回复“确认发送”后再执行。
-   邮件正文发送前，可以询问用户是否需要最后审阅。

现在，你就可以对你的智能体说：“DevMate，帮我发封邮件给张三，告诉他会议纪要已经整理好放在共享盘了。” 智能体会根据规则向你确认，然后调用背后的Python脚本完成任务。

4.4 常见问题与故障排查

在部署和使用过程中，你可能会遇到以下问题：

  1. 智能体启动失败，提示“无法加载工作空间”

    • 检查 ： openclaw.json 中的 workspaceDir 路径是否正确。使用绝对路径是最稳妥的方式。
    • 检查 ： workspace/ 目录下的关键文件（如 USER.md , SOUL.md ）是否存在且可读。确保没有拼写错误。

  2. 智能体回应“我不知道如何做这个”或无法调用工具

    • 检查 ： 你的请求是否清晰地在 TOOLS.md 中定义的范围内？工具描述是否足够详细，包括示例？
    • 检查 ： 如果工具需要脚本或程序，该脚本是否存在、有执行权限、且路径在 TOOLS.md 中正确引用？
    • 检查 ： 工具所需的API密钥或环境变量是否已在 .env 中正确配置，并且OpenClaw进程能访问到这些环境变量？（对于Docker部署，需在 docker-compose.yml 中声明环境变量）

  3. 智能体的回复泛泛而谈，没有结合我的上下文

    • 优化 ： 重新审视 USER.md 。信息是否足够具体？尝试添加更多你正在进行的项目细节、你的技术栈、你常遇到的问题模式。
    • 优化 ： 检查 SOUL.md 中的使命是否足够聚焦？一个“优化我的工作效率”的使命，比“帮助我”能提供更强的指导性。
    • 技巧 ： 在对话中，有时可以主动提醒智能体：“请参考 USER.md 中我的当前项目背景来回答。”

  4. 心跳任务没有按时执行

    • 检查 ： HEARTBEAT.md 中的时间格式是否正确？OpenClaw通常使用Cron表达式或类似格式。
    • 检查 ： OpenClaw服务是否在持续运行？心跳任务需要服务常驻才能触发。
    • 检查 ： 心跳任务中指定的工具或检查项，智能体是否真的有权限和执行能力？

  5. 对话历史似乎没有被有效记忆

    • 理解 ： memory/ 目录下的会话记录是原始数据。智能体的“记忆”更多依赖于 MEMORY.md 中的提炼信息和它在每次对话时被提供的上下文（包括最近的会话记录）。模型本身有上下文长度限制，太旧的对话不会被纳入。
    • 解决 ： 对于需要长期记住的重要信息，务必手动或指令智能体将其精华总结到 MEMORY.md 中。

5. 迭代优化与个性化之路

部署成功只是开始。一个真正好用的个人AI智能体是需要“驯养”和迭代的。我的经验是，把它当作一个需要磨合的新同事。

每周花15分钟进行“维护” ：

  1. 回顾对话 ： 翻看 memory/ 目录下近几天的对话，看看智能体在哪些地方理解有偏差，哪些地方表现惊艳。
  2. 更新上下文 ： 你的工作重点在变，及时更新 USER.md 中的“当前核心项目”和“短期目标”。
  3. 提炼记忆 ： 把有价值的讨论结果固化到 MEMORY.md 。
  4. 增删工具 ： 这周经常让智能体帮你查天气？考虑把调用天气API的工具加到 TOOLS.md 。某个工具从来没用过？可以考虑删除以简化认知负荷。
  5. 调整规则 ： 如果发现智能体在某些场景下行为不符合预期，去 AGENTS.md 中增加或修改相应的规则。

不要追求一步到位 ： 最开始只配置一两个最需要的工具，设定一两个简单的心跳任务。随着信任和默契的建立，再逐步扩展它的能力边界。安全永远是第一位的，尤其是涉及执行命令和访问API时，遵循最小权限原则，并在 AGENTS.md 中设置足够的确认环节。

这个模板的精髓在于它的极简和文本驱动。它没有给你一个无所不能的黑箱，而是给了你一套清晰的结构和工具，让你能够亲手塑造一个真正理解你、适应你工作流的数字伙伴。剩下的，就取决于你愿意投入多少心思去定义它、训练它、与它协作了。

# AI智能体
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

PulseClaw实时流背压控制：SSE代理缓冲与RAG延迟的工程权衡

avatar 龙虾开发者社区
cover

OpenClaw 工作流中的容器逃逸防御：rootless podman 与 host docker 的沙箱权衡

avatar 龙虾开发者社区
cover

Agent 出站审核实战：为何 Claw 网关的 POLICY 钩子必须前置处理？

avatar 龙虾开发者社区