从聊天到干活：OpenClaw让AI Agent真正长出“手脚”

每次看到别人晒 AI Agent 的“破壳 Demo”，我都觉得像在看一只被人捏住尾巴的龙虾：看着张牙舞爪，一顿操作猛如虎，其实悬空划水，根本落不了地。直到 OpenClaw 这类把工具链和外部接入放到第一优先级的东西出现，我才真正想明白一句话——不搞懂“手”和“脚”的逻辑，你的 AI Agent 永远长不大。所谓“手”，是模型调用工具、操作资源的能力；所谓“脚”，是 Agent 接入 Teams、Obsidian、本地 Shell 这些真实环境的通道。网上用同一套源码跑出来的智能体，体验差别天上地下，差就差在开发者是不是真把这套手脚逻辑配置到了能干活的程度。

这篇文章不打算给你重复官网文档，我会把 OpenClaw 的部署、建模、接 Teams、上 Obsidian，以及从 0 到 1 搭一个“能自己干活”的 Agent 全过程讲透，也会把这段时间踩过的坑、试过的路径、最后沉淀下来的自检清单一起放出来。适合三种人看：刚接触 AI Agent、想搞清楚 Agent 为什么总是“只聊不做”的新手；已经在跑开源 Agent、但苦于不知道如何扩展技能的开发者；以及想把手头项目从 demo 推向产品化的朋友。

1. 项目为什么一直窝在 Demo 阶段？你的 Agent 只有脑子没有手脚

1.1 “大脑很强，四肢发育不良”是最常见的形态

我见过太多所谓的 AI Agent 项目，核心结构就一个带聊天气泡的大模型接口：用户说一句话，模型回一段话。演示视频很漂亮，一问“能帮我批量处理桌面文件吗”“能代替我把纪要存进 Obsidian 吗”，立刻卡壳。

问题不在模型不够聪明，而在架构上缺少两层东西：执行层和通道层。执行层负责把自然语言转换成实际动作，比如读文件、发请求、写数据库、调第三方 API；通道层负责让代理能“听到”外界的触发信号，并能把结果送回用户所在的环境，比如 Teams 里的一条 @消息、Obsidian 里的一个文件变更、服务器上的一条定时任务。

只有脑子，没有执行层，Agent 就是个聊天机器人；有执行层但没有通道层，它就只能活在终端里，谁也没法正常使用。OpenClaw 这个名字起得挺贴切，Claw 就是爪子，它强调的是“能抓住东西、能动手操作”，不是安安稳稳挂在那里的静态代码。

1.2 把“智能”变成“能做”的三个闭环

之前团队内部复盘时推演过一套 Agent 能力的成熟度模型。真正的 Agent 至少要跑通三个闭环：

感知闭环：环境里有事件进来，Agent 能感知到。比如 Teams 里有人发指令，或者某个文件夹新增了一个文件，系统要能把这些事件转成内部消息。

决策闭环：大模型基于系统提示词和上下文，把用户意图拆成子任务，再决定调用哪个技能。

动作闭环：技能真的执行了，文件真的写了，API 真的调了，最后把结果格式化后返回给用户。

我发现 90% 的“长不大”的项目，完整跑通的只有决策闭环，感知和动作全靠人肉转发。用 OpenClaw 这类框架去搭 Agent，最大的收益其实不是省掉几行代码，而是它强制你把这三个闭环都按标准接上。

1.3 龙虾蜕壳和 Agent 成长的类比

为什么标题里说“长不大”？龙虾不是慢慢变大的，它得不断蜕壳。旧壳限制了体积，脱掉旧壳、新壳还没硬的时候，它最脆弱，但也是长得最快的窗口期。Agent 的“壳”就是固定的技能边界和接入边界。如果你一直不让 Agent 接触外部工具，或者不给它增加新通道，它的能力上限就被卡死在提示词里。OpenClaw 这套东西在我看来，实际上是给了你一个主动“蜕壳”的框架：每注册一个新技能，每接通一个新渠道，Agent 就换过一次壳。

想通这一点之后，我不再把 Agent 当作一个“大模型封装”，而是当作一只需要不断换壳的生物在养。你的核心工作变成了给它的肢体末端持续增加新的“爪子”。

2. 拆开这套“手脚”：技能注册、连接器与执行链路

2.1 上半身的“手”：技能和 Function Calling 的关系

很多人会把 OpenClaw 的“技能（Skill）”和模型侧自带的 Function Calling 混在一起，这是概念上最容易绕晕的地方。

Function Calling 是大模型输出结构化调用指令的能力，模型只负责说“现在应该调用 search_files 这个函数，参数是这些”。真正干活的是技能本身。OpenClaw 里的技能更像一个带描述文件和参数规范的 Python 模块，我通常用下面的方式组织：

skills: - name: obsidian_write entry: ./skills/obsidian_write.py description: "把内容写入 Obsidian 指定文件夹，支持 markdown 格式" parameters: title: type: string description: "文档标题" folder: type: string description: "目标文件夹，如 DailyNotes" content: type: string description: "文档正文内容"

这段配置的意义是：普通情况下，模型根本不知道“往 Obsidian 里写笔记”这个动作长什么样；但当你把技能名、描述、参数都塞给它之后，它就知道了——原来在一个日常任务里，它可以请求调用obsidian_write来完成写入动作。

对刚接触 Agent 的朋友，我建议把技能当做一个“可被模型发现和调用的函数”。你在本地验证时可以直接用命令行调用，比如：

python cli.py skill-test --name obsidian_write --payload '{"title":"测试笔记","folder":"DailyNotes","content":"hello openclaw"}'

为什么这很重要？因为如果技能本身不通过命令行跑通，那它在 Agent 里大概率也跑不通；反之，只要命令行能跑，后面的一切只是流程编排问题。

2.2 下半身的“脚”：连接器与事件循环

“脚”在 OpenClaw 里的实现叫连接器（Connector）。它负责把外部平台的事件接进来，再把 Agent 的结果送回去。我用过的最典型的连接器是 Microsoft Teams 和 Obsidian 本地文件夹。

Teams 连接器做的事情本质上是：起一个 WebSocket 或 Webhook 服务，接收 Teams 发送来的消息事件，解析出消息文本和用户信息，拼接成标准化的AgentMessage，交给调度器；等 Agent 处理完后，再把响应通过 Teams Bot API 发回对应会话。

在配置里，它长这样：

channels: teams: enabled: true app_id: ${TEAMS_APP_ID} app_password: ${TEAMS_APP_PASSWORD} tenant_id: ${TEAMS_TENANT_ID}

Obsidian 连接器则正好反过来，它更像是“带路的手脚组合”：监听某个 vault 文件夹的变更，新笔记创建后自动触发摘要或标签生成，然后把处理结果写回另一个文件夹。这种场景天然适合 Agent，因为文件系统的变更是一个确定的事件源。

2.3 手和脚的配合：一条标准动作链路

在我自己搭的流程里，一次完整动作通常是这样的：

1. Teams 群里有人发了“帮我整理一下今天会议记录的待办”。
2. Teams 连接器收到事件，转成内部消息。
3. 调度器把消息发给大模型，并附上当前可用的技能清单。
4. 模型输出决策：先调用teams_get_messages拉取会议记录，再调用obsidian_write生成待办文档。
5. 技能执行并返回结果给模型。
6. 模型汇总后交给 Teams 连接器，发送回会话窗口。

整个链路中，负责“思考”的模型反而只占很小一部分，真正花时间的是手脚是否配合流畅。每次部署时我都会盯着第 4 步和第 5 步的输出日志，确认模型的 tool_calls 是否真的落地执行，而不是说出来就算了。

3. Ubuntu 上从零部署 OpenClaw：实操记录与避坑清单

3.1 环境准备阶段容易被低估的三个问题

OpenClaw 的安装没有想象中难，但如果你把它当成纯 Python 项目，直接在系统全局环境里跑，很快会撞墙。我的建议是在 Ubuntu 22.04 或 24.04 上，用虚拟环境安装。

先说前置项：Python 3.11 以上，Git，Redis。别小看 Redis，OpenClaw 的任务队列和日志缓冲都依赖它。很多部署到一半报 connection refused 的问题，十有八九是 Redis 没启动。

sudo apt update && sudo apt upgrade -y sudo apt install -y python3.11 python3.11-venv python3-pip git redis-server # 顺手确认 Python 版本别低于 3.11 python3 --version

然后拉仓库、建虚拟环境、装依赖。仓库地址以你 fork 的为准，我习惯把官方源 clone 到本地再用自己的分支：

git clone <你的 OpenClaw 仓库地址> openclaw cd openclaw python3.11 -m venv .venv source .venv/bin/activate pip install -r requirements.txt cp .env.example .env

这里有一个很隐蔽的坑：.env.example里的模型 API Key 占位符往往带一段说明文字，如果你直接复制整个文件再改，Key 前后可能残留空格或注释符号，验证时一直报鉴权失败。我的习惯是用cat -A .env | grep API_KEY确认行尾没有多余符号。

3.2 一键部署脚本到底帮你做了哪些事

OpenClaw 提供了一键部署脚本，在 Ubuntu 上确实可以做到“下载即用”，但这个脚本不是魔法，它只是把前面的步骤自动化了：创建虚拟环境、装依赖、初始化配置、启动 Redis、通过 systemd 注册常驻服务。

如果你不放心脚本，完全可以按手动流程跑。我就在生产环境里遇到过脚本创建的用户权限不对，导致 Agent 没法写工作目录的问题。手动方式虽然慢，但每一步都看得见。

启动服务前先做一次初始化：

python cli.py init --model-provider openai --model gpt-4o python cli.py start

看到类似CLaw Agent has started的日志后，可以开另一个终端验证健康检查接口：

curl http://127.0.0.1:8765/health

返回{"status":"ok"}基本说明核心服务已经跑起来了。注意，cli.py start是前台模式，适合调试；确认没问题后再用systemd或pm2做守护进程。

3.3 部署完别急着接平台，先验证“手”能不能干活

很多人的习惯是服务起来了，马上跑去配 Teams、配 Obsidian，然后遇到问题不知道是人家的通道问题还是技能问题。这属于“脚伤了怪手没力”，排查起来极为痛苦。

我会先做两件事。第一，用内置的 CLI 表单页看技能列表，确认核心技能都已加载：

python cli.py skills list

第二，单独测试一个能产生实际副作用的技能。最稳妥的是让 Agent 读写一个临时文件：

python cli.py run --skill file_write --payload '{"path":"/tmp/openclaw_test.txt","content":"手没问题"}' cat /tmp/openclaw_test.txt

如果文件写出来了，说明“手”是通的，后面加入再复杂的动作也只是技能叠加的问题。如果这一步就不通，先别怀疑模型，去查技能权限和路径配置。

3.4 部署阶段我踩过的三个报错

ModuleNotFoundError / 编译错误：某些依赖需要系统编译环境，空 Ubuntu 上会出现python.h缺失。安装build-essential和libssl-dev即可：

sudo apt install -y build-essential libssl-dev

Redis connection refused：常见原因是 Redis 只监听了 IPv6 的::1，而 OpenClaw 默认连127.0.0.1。把配置文件里的 bind 改成127.0.0.1 ::1，或者用redis-cli ping先确认。

端口被占用：默认管理端口 8765 被其他服务占用，启动后日志一直刷address already in use。改端口很简单，在.env里把PORT换掉就行。别跟别的服务抢端口，这不是什么值得争的事。

4. 给 Agent 装上“腿”：把 OpenClaw 接进 Microsoft Teams

4.1 为什么我推荐用 Teams 做第一个外部通道

市面上能接的 IM 平台很多，但我特别建议第一个正式通道用 Microsoft Teams，原因有三个。

第一，Teams 的 Bot 机制成熟稳定，消息事件、文件事件、会议事件都有明确的 API 形式，不像某些平台还要自己去抓协议。第二，办公场景和 Agent 的能力天然契合：会议纪要、任务提醒、文档归档，全是知识型工作，正好是 Agent 最擅长的。第三，调试成本低——Teams 开发者环境和个人测试账号免费，一个人就能完成完整链路验证。

4.2 注册机器人并拿到三件套凭证

在 Azure 门户里创建一个 Bot 资源，然后来到 Teams 开发者门户把 Bot 关联进去，启用 Personal Chat 和 Team 频道。这个过程会拿到三样东西：App ID、App Secret（密码）、租户 ID。这三件套就像人的身份证、钥匙和户口本，缺一个都登不了门。

拿到凭证后，在 OpenClaw 里开通 Teams 连接器：

python cli.py channel enable teams

然后编辑配置，填写凭证。Payload 示例：

channels: teams: enabled: true app_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" app_password: "你的Bot密码" tenant_id: "租户ID" route: "/api/messages"

填完之后重启服务，在 Teams 里给自己发一条私聊消息测试。这里提醒一句：Teams Bot 首次使用时需要在 Azure 门户里把“Message Delivery”权限打开，否则消息只会进不会出。

4.3 在 Teams 里完整跑通一个任务

我实际跑通的最经典任务是会议纪要多维归档。在 Teams 里我会对 Agent 说：“整理这周产品例会纪要，输出待办清单，并写进 Obsidian 项目库”。这条指令走的链路是：

1. Teams 连接器收消息。
2. 调度器判断需要调用teams_get_messages技能，拉取最近会议频道的消息。
3. 大模型对消息进行结构化分析，提取决议、待办、负责人。
4. 调用obsidian_write技能，在 Obsidian 的Projects/产品例会目录下生成一份带有日期命名的 Markdown 文档。
5. 返回一份摘要到 Teams。

整个过程里 Agent 同时用到了“嘴巴（IM 对话）”、“耳朵（消息感知）”、“手（写文件）”、“腿（Teams 接入）”。当四个环节都跑通，你会明显感觉到它从一个“演示用聊天框”变成了一个“线上数字员工”。

5. 从“会聊天”到“能干活”：中台化思路与三个练手项目

5.1 一个 Agent 中台的基本分法

聊完单实例部署，再拔高一层。一个团队如果想把 Agent 能力规模化，迟早会碰到中台问题。很多人一听“中台”就头疼，但站在 OpenClaw 这个框架看，中台化无非是把技能、连接器、模型配置、权限做统一管理。

我验证过的结构是三个池子：技能池负责沉淀可复用能力，比如邮件发送、文档解析、定时任务；通道池统一管理 Teams、飞书、钉钉、Obsidian 等入口和出口；策略池控制模型选用、温度参数、访问频率、操作白名单。对外呈现的只是一个配置中心，对内是一个 Agent 工厂。

这样做的好处很实际：新项目上线时不再从线性代码开始写，而是从技能池里挑几个技能，连一个通道，配一个模型，一个可用的 Agent 就生成了。

5.2 国内 AI Agent 产品盘点给我的启发

从 2026 年国内 Agent 产品的大趋势看，基本都在朝“低代码化 + 连接器生态 + 技能市场”走。早期的 Agent 产品拼谁的模型调教得好、对话体验顺；现在的产品拼的是谁能更快地接到企业已有的系统上，比如打通 OA、CRM、IM、知识库。这个变化本质上也是手和脚的竞争——模型的智商是“平权”的，各家差不了多少，真正拉开体验差距的是谁能把动作做扎实。

比如你印象里那些“顶流”Agent 平台，拆开看一定分别解决了三个问题：可编排的技能（手）、丰富的连接器（脚）、灵活的触发方式（神经系统）。OpenClaw 的思路其实和这些产品同源，只是它给了你一个自托管的、可以完全掌控底层细节的入口。

5.3 三个从 0 到 1 可以落地的练手项目

如果你正在找 Agent 练手项目，我强烈推荐按下面三个方向做，覆盖了读写、通知、搜索三大类能力。

Obsidian 自动归档助手：这是门槛最低、反馈最快的一个。做一个技能监听 Obsidian 的Inbox文件夹，新文件进来后自动调用大模型做分类、打标签、写摘要，然后把文件移动到对应目录。我用了不到半天就跑通，适合用来建立对技能事件的体感。

Teams 会议纪要机器人：把第 4 节的链路做成固定模式。让 Agent 定时拉取某个 Teams 频道的聊天记录，自动生成会议纪要和工作任务清单，并发布到指定的 “Task” 频道。这个项目能直接让同事看到 Agent 的价值，也逼你把权限、错误重试这些问题处理干净。

RSS 每日摘要订阅源：定时触发一个技能，抓取你设定的几个 RSS 源，用模型生成每日情报摘要，再以纯文本推送到 Teams 私聊。会涉及到定时任务、HTTP 请求技能、文本格式化三个能力，属于非常标准的 Agent 场景。

这三个项目做完，你会对“技能注册—通道接入—定时触发—结果回传”这条主链路有非常完整的理解。

6. 这段时间踩过的坑，总结成一张自检清单

最后一次排查经验总结。我把自己在 Ubuntu 部署、Teams 接入、技能编写里踩过的明显坑整理成一张检查表，供你一条一条过。这张表比任何部署文档都更接近实际运行逻辑，因为它记录的是失败过的路径。

部署与系统层

• 检查 Python 版本是否高于 3.11，旧版本会导致语法级报错。
• 检查 Redis 是否真正在运行，redis-cli ping必须返回 PONG。
• 检查工作目录有没有写权限，很多创建文件失败的问题其实是权限，而不是代码。

模型与配置层

• 检查.env里 API Key 是否有隐藏字符，用cat -A .env检查行尾。
• 检查模型名是否匹配当前接口的实际型号名称，模型名写错会在调用时报 404。
• 检查 system prompt 是否明确说明“你必须使用工具而不是猜测”，否则模型可能跳过调用直接编结果。

技能与执行层

• 检查技能是否在命令行单独跑通过，未通过前不要进入 Agent 联调。
• 检查技能参数类型是否与模型输出一致，数字型字段最容易变成字符串，导致后端校验失败。
• 检查技能是否有超时和重试机制，慢 API 会导致整个任务被挂死。
• 检查危险操作（删文件、执行 shell、发邮件）是否做了二次确认，Agent 再聪明也别让它直接拿到核按钮。

通道与安全层

• 检查 Teams Bot 权限里是否开启了 Message Delivery，否则消息只进不出。
• 检查连接器的 WebHook 路由是否被公网防火墙挡住，本地调试可以用内网穿透类工具做临时验证。
• 检查凭证是否被提交到 Git 仓库，这个我吃过亏—— 一个 App Secret 被推到远程仓库后，我只能全部轮换重新配置。

把这张表存成项目根目录下的CHECKLIST.md，每次新环境部署前过一遍，能省掉你不下一两个晚上的排障时间。

最后再分享一个小心得：Agent 这种项目，最忌讳的是把它当普通程序写一次就能稳定跑起来。它更像养一只不断蜕壳的龙虾，每加一个技能、每接一个新渠道，系统都会经历一次不稳定的窗口期。但只要手脚链路清晰、日志完整、检查清单在手，这些窗口期反而会变成能力突飞猛进的阶段。我现在的习惯是每完成一个连接器接入，就在终端里跑一遍技能自测、看一遍日志链路、更新一遍清单——慢是慢一点，但每一步都踩在实地上。