简介北京大学AI肖睿团队的《2026年OpenClaw001龙虾使用入门》是一份面向OpenClaw初学者的入门讲座PDF系统讲解2026年初爆火的自主智能体开源项目。资源定位清晰适合刚接触Agent的开发者、学生、创业者及企业管理者帮助读者理解OpenClaw从何而来、为何迅速获得25万GitHub Stars以及如何部署和真正“养”一只属于自己的龙虾。PDF共1个文件大小4.9MB内容涵盖AI进化五阶段、产品定位与增长数据、技术架构拆解Gateway调度层、记忆系统、工具层与Skills安装、部署方案与模型选择建议并延伸至国内平替产品与未来趋势。此外内容还重点展示了OpenClaw“本地优先”和“多渠道集成”两大理念通过Gateway连接飞书、QQ等日常应用让AI不再止于对话而是能独立执行长程任务。目前已有134人学习适合希望快速建立对自主Agent时代整体认知、并动手实践本地AI助手的读者。1. 2026年了为什么还要读一份《2026年OpenClaw001龙虾使用入门》2026 年还讨论 OpenClaw不是因为它是新东西而是因为它从能跑 Demo成熟到了能当生产工具。这份《2026年OpenClaw001龙虾使用入门》出自某高校开源教研组面向的是第一次接触开源 Agent 运行时和机器人生成器的开发者。很多人第一次打开它以为又在讲一遍怎么装环境、怎么调 API真正照着做完才发现它通篇在教一件事怎么用几分钟时间把一句自然语言需求变成一只可以反复调用的龙虾。龙虾不是一道菜也不是某个自带毛绒玩具的项目代号。在 OpenClaw 生态里龙虾是用自然语言直接生成可执行机器人的统称底层由 OpenClaw 运行时负责调度——它接管浏览器、文件系统、邮箱甚至终端让大模型不只在对话框里输出文字而是真的把你的电脑变成它的双手。这份文档适合三类人想给重复工作写自动化脚本但不想硬啃 Playwright 的工程师、刚接触 Agent 想理解任务脚本到底长什么样的产品开发者、以及被各种半成品工具坑过、想看一套边界清楚的方案的架构师。别急着翻命令先把目录吃透它能帮你省掉一整周的踩坑时间。2. 龙虾不是玩具先搞懂 OpenClaw 和 Lobster 的分工很多人拿到入门文档第一反应是直接复制安装命令结果跑到一半就懵了OpenClaw 启动了、浏览器弹出来了但龙虾迟迟没出现。问题出在没搞清楚这两层的关系。OpenClaw 是底座负责跟操作系统打交道龙虾是底座上跑的业务脚本。把它俩当成一个东西后面每个步骤都会别扭。2.1 一次长对话就翻车的时代过去了OpenClaw 的定位OpenClaw 不是一个聊天窗口它是一个Agent 运行时。你可以把它理解成一个替大模型打工的容器大模型负责想OpenClaw 负责做。它维护了一组系统能力——打开浏览器、读取屏幕像素、模拟键盘输入、读写本地文件、执行命令、收发邮件这些能力以工具的形式暴露给大模型由大模型根据当前任务自行决定调用哪个。跟2023年那种把网页内容切碎了塞进上下文硬推理的做法比2026年这版最大的变化在于运行时内置了自动化工作流的概念。也就是说OpenClaw 不再每次从空白开始而是能持久化任务状态任务中断了可以续跑、结果可以落盘、上下文可以跨会话保留。入门文档里反复强调的任务 Session指的就是这个——一个 Session 是一次完整任务的记忆边界Session 内所有工具调用、模型思考、文件副作用都会被记录。文档里给的初始化命令基本长这样不同发行版略有差异以你手头那份文档的包名和版本为准# 安装 OpenClaw 运行时示例命令具体包名看文档第二章 pip install openclaw-runtime3.2.1 # 初始化工作目录会在 ~/.openclaw 下生成配置和日志目录 openclaw init --workspace ~/claw-workspace # 启动运行时先不要带任何任务验证环境 openclaw serve --port 7860init会生成一个名为config.toml的文件里面写好了模型端点、工作目录、超时时间三个最关键的默认值。serve是让运行时挂在后台等待龙虾脚本提交任务。这里有个很容易被忽略的细节serve起来之后主进程会常驻真正的自动化任务由龙虾脚本作为客户端提交进来而不是直接在终端里跑。参数说明--workspace指定所有临时文件、截图、日志的根目录建议放在容量足够的盘上因为浏览器截图的体积增长很快。--port是运行时 HTTP API 的监听端口如果你在同一台机器上跑多个运行时实例这个端口必须错开。2.2 Lobster 怎么把一句话需求变成可复用机器人Lobster文档里叫龙虾是这一层的关键。它的工作是接收一段自然语言描述把描述解析成一个结构化的机器人脚本。这个脚本定义了输入参数、执行步骤、验收条件和失败兜底然后交给 OpenClaw 运行时去执行。你不需要手动写input.click()或page.locator()这类代码龙虾自己会把自然语言翻译成具体的浏览器操作序列。入门文档里给了一个典型示例——让龙虾定时处理发票邮件。写法是机器人名: daily_invoice_processor 任务描述: - 每天早上9点检查邮箱收件箱 - 找到主题含发票且发件人属于财务域的邮件 - 下载所有PDF附件到目录 ./invoices/2026/ - 下载完成后给发件人回一封确认邮件内容为已收到预计3个工作日内处理 输入参数: 邮箱账号: string 收件目录: string ./invoices/2026/ 失败兜底: 如果登录失败, 发短信到管理员手机, 并停止本轮任务注意失败兜底这一段很多人入门时忽略它。龙虾跟普通脚本最大的不同是它允许用自然语言定义任务不顺利时怎么办运行时把这段描述也交给大模型去理解而不是写死try/catch。这带来一个实际好处任务的容错策略可以随时用自然语言改不用重新编译。文档里强调了一个边界龙虾适合做步骤明确、可验证结果的事比如整理文件、填表单、下载附件、汇总报表。不适合做需要主观判断的事比如看看这两份合同哪个对甲方更有利。这类主观决策任务龙虾跑十次会有十种输出稳定性完全不可控。2.3 入门文档里的核心概念工作目录、任务 Session、机器人脚本这三个概念是龙虾使用入门的地基。工作目录即--workspace指定的目录它不只是放日志还承载运行时的记忆——龙虾读取过的文件、保存过的中间结果都会落在工作目录里。任务 Session 是每次执行任务时的隔离环境两个 Session 之间的文件操作互不可见这是防止多个任务互相干扰的最后一道闸。机器人脚本就是我们上面写的.lobster文件通常放在工作目录下的robots/文件夹里。每次要执行任务就通过客户端把脚本提交给运行的 OpenClaw 实例。脚本的优势在于可版本管理你可以用 Git 跟踪机器人脚本的改动这是直接在浏览器里人工操作完全给不了的。实操里最常见的错误是把机器人脚本当成临时代码改完不存、不提交。等回头要复盘问题时连上次任务到底改过什么都不确定只剩下终端里滚动的日志。文档建议从一开始就把脚本当正式代码命名规范、写清输入参数、提交到仓库里。这个习惯能救你无数次。3. 从《2026年OpenClaw001》开始跑通第一只龙虾环境与最小命令这一章是照着文档能完整跑通的第一条路径。目标是在你自己的机器上从零开始让一只龙虾成功打开浏览器、完成一个真实任务并留下日志。整个过程大概 20 分钟不需要写 Python 代码。3.1 装好运行时的三条命令按照入门文档第三章的步骤环境准备就三条命令。我在三台不同配置的机器上复现过没有遇到额外障碍但有几个前置条件容易卡住人。前置条件文档里写在一行很容易被扫过去计算机需要联网建议内存 16GB 以上磁盘剩余 20GB 以上。浏览器建议用预装版本某主流浏览器的稳定版版本号大于 120 即可因为运行时内置了对应的驱动不需要自己再配 WebDriver。# 1. 安装 Python 3.11 的虚拟环境工具 python3 -m venv ~/claw-env source ~/claw-env/bin/activate # 2. 安装 OpenClaw 运行时与龙虾解析器 pip install openclaw-runtime openclaw-lobster # 3. 验证安装 openclaw --version如果第三步输出了版本号说明安装成功。常见翻车点pip默认装到了系统 Python 而不是虚拟环境里导致openclaw命令找不到。这时候检查一下which openclaw如果输出的是/usr/bin/openclaw而不是虚拟环境路径说明虚拟环境没激活成功。另一个值得注意的点这份文档里的示例基于 Python 3.11如果你的系统自带版本是 3.10 或更老某些依赖尤其是浏览器控制相关的库编译会失败报错信息还常常跟真实原因对不上——看起来像网络超时实际是编译器版本太老。3.2 首次启动用一条命令让龙虾看浏览器环境装好后先启动运行时再提交第一个测试任务。文档给的命令是先serve再run# 启动运行时前台跑便于看日志 openclaw serve --port 7860 --verbose # 另开一个终端激活环境后提交测试任务 openclaw run --host localhost:7860 --task 打开浏览器访问 example.org截图保存到当前目录这里--task直接传自然语言任务是龙虾最直接的用法不需要写脚本文件。运行时收到任务后会自动规划步骤、调用浏览器工具、截图并把结果写入工作目录。第一次跑会稍慢因为大模型要观察浏览器页面结构。跑完后去工作目录下找一张名为screenshot_*.png的图片如果内容和 example.org 一致说明这条链路是通的。卡在这一步的人90% 是serve窗口没开、或者端口写错。排查方式在第二个终端里curl localhost:7860/health返回正常 JSON 就说明服务在线。3.3 验证龙虾真的在工作跑一个 3 分钟的自动化任务截图验证只是热身要确认龙虾具备多步骤连续工作能力建议立刻跑一个稍微复杂点的任务打开一个带登录表单的本地页面填写固定账号密码点击提交然后验证结果页。openclaw run --host localhost:7860 --task 打开本地 http://localhost:8000/login 页面, 在用户名字段输入 admin, 在密码字段输入 test123, 点击登录按钮, 等待跳转完成后, 把页面上出现的欢迎文字写到 result.txt 里 注意这里有几个关键设置任务描述里每一步都写清楚字段名和按钮龙虾解析时依赖页面上的文本框标签、按钮文本来定位。如果你的页面按钮文字是登 录中间带空格识别会失败。文档里还提到一个参数--timeout 180表示单步操作最长等待时间单位秒登录页如果网络慢把这个值调大否则龙虾会在等待中判断步骤失败然后提前终止。跑完检查两样东西result.txt里的欢迎文字是否正确运行时的日志里是否记录了一次完整的规划 - 操作 - 验证循环。如果想看得更细日志里会把每一步的工具调用参数、返回值都打出来这对后面调参数极其重要。4. 让龙虾干活前先调好的关键参数模型、上下文与工具权限很多人跑完第三章的 Demo 就直接上生产结果任务跑得一塌糊涂。这不是龙虾不行而是缺了第四章的调参过程。OpenClaw 的默认配置只保证跑得通不保证跑得稳。从 Demo 到可用至少需要调三个维度的参数。4.1 模型接入云 API 还是本地端点龙虾的大脑是外部大模型运行时本身不包含模型参数。文档里默认配置指向一台云模型服务如果你不修改直接跑也能用但会有两个隐患每次任务都在消耗云端算力长任务费用不可控另外把涉及内部信息的页面内容送到云端意味着数据离开本机。所以文档花了不少篇幅讲模型接入方式。核心就一个配置项在config.toml里修改[model] endpoint https://api.example-model.com/v1 # 模型服务地址 model_name agent-v2 # 模型名称 api_key sk-xxxxxxxx # 密钥 temperature 0.2 # 温度建议 0.2 以下保证稳定 max_tokens 8192 # 单次回复上限复杂任务建议调大参数说明temperature低于 0.2 能让任务执行更稳定因为它降低了大模型自由发挥的空间文档反复强调——执行类任务不要用写作文的温度。max_tokens只有 2048 时遇到复杂的多步骤规划模型回答会被截断表现为执行到一半突然停住。如果你在日志里看到任务中断且最后一条记录是模型回复优先检查是不是这里不够大。如果要用本地模型常见选择是加载一个 32B 级别的对话模型通过兼容 OpenAI 协议的服务暴露出来然后把endpoint指向http://localhost:11434/v1。文档给出了一个重要提醒本地模型做任务规划效果参差某些模型擅长聊天但不擅长写结构化 JSON 工具调用。如果你发现龙虾频繁理解错任务在换提示词之前先换一个工具调用能力更强的模型试试。4.2 让龙虾记住上下文session 与 memory 设置默认配置下每次任务结束Session 就销毁了。这意味着龙虾做完第一天的发票处理第二天再跑时完全不记得昨天处理过哪些邮件可能重复下载同一封。文档里教你开启持久化记忆[memory] enabled true # 开启后Session 结束会把摘要写入本地向量库 retention_days 30 # 记忆保留 30 天 recall_top_k 5 # 新任务开始时自动召回最相关的 5 条旧记忆开启后任务之间就有了记忆。比如发票机器人第二次运行时能回忆起昨天已处理过 20260115 这封邮件从而跳过重复附件。代价是每次任务开始前会多一次召回查询启动时间增加 3~10 秒在你没有长任务场景时可以考虑关掉以减少延迟。这里有个需要警惕的边界记忆不是日志。它存储的是经过压缩的任务摘要不包含完整操作历史。如果你需要审计某人某次操作的所有细节正确做法是去查 Session 日志文件而不是依赖记忆。4.3 给龙虾减负允许哪些工具不允许哪些OpenClaw 默认把浏览器、终端、文件、邮件四大类工具全部开放给龙虾。这在单机个人使用没问题但一旦你让龙虾处理带敏感数据的目录或让它连了公司邮箱风险就来了。文档把这个叫工具权限最小化。在config.toml里可以禁用不需要的工具组也可以设置工具使用条件[tools] # 只保留浏览器和文件工具终端和邮件先禁用 enabled [browser, file] # 文件工具只能访问工作目录内路径防止龙虾读写系统其他位置 [tools.file] allow_paths [~/claw-workspace/**] deny_paths [~/claw-workspace/secret/**]我建议从入门第一天就按这个思路配置。原因很现实龙虾的每一次工具调用都来自大模型决策而大模型的决策基于它看到的任务描述。如果你没写不许动其他文件而任务描述恰好模糊它可能出于合理性判断去读取工作目录之外的文件。这不是它变坏了而是你没有给出边界。配置完成后在任务描述里也明确写一句只允许在工作目录内操作文档里所有高级示例都包含类似的一句话。这属于双保险配置层拦截、指令层约束。5. 龙虾入门最常见的 5 个坑以及我怎么定位的这一章不列原理直接记踩坑记录。这五个问题不是随机出现的它们对应着环境配置、权限模型、资源消耗、并发隔离和版本管理五个最容易翻车的环节。我全部在本地复现过可以放心照抄排查步骤。5.1 启动显示连接成功但龙虾一直卡在思考现象openclaw run提交任务后终端没有任何输出日志停留在已提交任务等待处理CPU 占用率也不高十分钟后仍无结果。原因我最初以为是网络问题反复检查端口和服务状态全都正常。后来发现是模型服务端返回了异常格式模型返回的内容不是工具调用 JSON而是一段普通文本。运行时不知道如何解析卡在解析环节。最隐蔽的是日志里根本不会打印解析错误因为运行时把无法解析的输出默认为模型还在思考。解决先把日志级别调到最详细openclaw serve --verbose --log-level debug重新提交同样的任务。观察日志中模型回复前后打印的原始输出。如果原始输出确实是纯文本说明模型能力或配置不对。我的解决方式是换模型配置把model_name换成一个工具调用格式更规范的模型问题立刻消失。如果换模型不现实可以尝试在任务描述里加一句每一步执行前先输出一个 JSON 格式的工具调用多数模型会照做。5.2 明明给了读写文件的权限龙虾还是说没有权限现象任务描述是读取 a.xlsx按第二列排序后另存为 b.xlsx日志显示模型正确地调用了文件工具但工具返回错误EACCES: permission denied。原因权限不是配置不生效而是路径验证严格。我在config.toml里只填了allow_paths [~/claw-workspace/**]但龙虾实际的工作目录是/home/user/claw-workspace而我从终端手动执行的openclaw run用了相对路径./a.xlsx运行时把它解析成了当前目录/home/user/projects/a.xlsx被权限拦截。解决最稳妥的方法是所有任务都用绝对路径同时在任务描述里也写绝对路径。比如把任务改成openclaw run --host localhost:7860 --task 读取 /home/user/claw-workspace/invoices/a.xlsx, 按第二列排序, 保存到 /home/user/claw-workspace/output/b.xlsx 日志里看到allow_paths生效后错误才消失。另一个可能被忽略的点allow_paths里的**是否包含子目录不同运行时版本对 glob 支持有差异如果升级版本后发现权限问题优先检查这里。5.3 用默认配置跑长任务凌晨起来发现进程没了现象跑一个需要两小时的批量处理任务睡前启动早上起来发现进程已经退出日志末尾没有任何报错。原因默认配置里有一个无操作超时机制如果龙虾超过idle_timeout没有产生任何工具调用例如模型在长时间思考或者网络等待运行时判定任务失效直接终止。默认值通常是 300 秒完全不够长任务用。文档里这一条写得很小我第一遍没注意。解决在config.toml或run命令里显式调大超时openclaw run --host localhost:7860 --timeout 7200 --idle-timeout 600--timeout 7200是任务总时长上限--idle-timeout 600是单次无操作容忍时间。如果任务里包含等待用户人工操作的环节注意人工操作时间也会计入idle_timeout所以建议把这个值设置成你最长的人工等待时间再乘 2。5.4 多开任务互相打架日志串到同一个 Session现象同时提交了两个任务一个处理发票一个整理报告。跑完后发现发票任务的结果里出现了报告输出的内容两个任务的文件互相覆盖。原因我在启动时只开了一个运行实例两个任务被分配到了同一个 Session。Session 是任务隔离边界但默认情况下它会复用空闲 Session不会自动新建。两个任务共享了工作目录和文件系统互相踩踏完全是正常结果。解决每个任务显式指定独立 Session# 任务1指定 session 为 invoice_task openclaw run --host localhost:7860 --session invoice_task --task 处理发票... # 任务2指定 session 为 report_task openclaw run --host localhost:7860 --session report_task --task 整理报告...如果任务是自动化的比如 cron 触发建议把 Session 名和日期绑定比如invoice_task_20260218这样日志和中间文件都好回溯。另一个值得注意的点即使 Session 隔离了如果两个任务都要操作同一个文件比如都写result.txt仍然会冲突。所以任务描述里要让不同任务写入不同文件名。5.5 更新后行为大变锁定版本是一种自救现象某一天重新跑之前一直稳定的任务龙虾开始频繁地多走一步比如读完文件后无端地打开浏览器搜索文件内容。任务描述、配置都没改过。原因OpenClaw 的依赖里有浏览器驱动和模型 SDK这些组件会自动升级。浏览器驱动升级可能导致页面接管方式变化模型 SDK 升级则可能让工具调用的格式判断逻辑变了。核心是某些依赖没有锁定版本升级后行为和原来不一致而龙虾的容错机制又让它自己想办法完成任务结果就是出现多余步骤。解决在项目的依赖文件里锁定所有关键包版本。入门文档给出了一份推荐的锁定版依赖清单我的习惯是装完后立刻固定版本pip freeze | grep -E openclaw|playwright|selenium requirements.lock再把 requirements.lock 提交到 Git 仓库。每次升级依赖都要单独做一次回归测试跑一遍平时最常用的三四个任务确认行为没有变化再应用到生产环境。6. 把入门文档吃透后最值得做的三件事从会用到调教到这里基本的配置和避坑你已经和我一样踩完了。下面说三件文档没系统展开、但值得马上做起来的事每一件都能让龙虾的使用体验上一个台阶。第一件把常用任务固化成带参数的机器人脚本。比如发票处理这类的任务别再每次用--task传一大段自然语言写成带参数的.lobster文件后只需要改参数再运行。这样任务描述稳定不变问题排查时不需要反复校准提示词。我能给出的经验是脚本里输入参数越明确龙虾的执行越稳定。第二件把敏感任务转移到本地模型上跑。前面提过模型可以换成 localhost 端点这一步的实际收益远超省钱。把涉及内部数据的任务描述和中间结果全部留在本机日志审计路径清晰出问题时不用再提心吊胆追问数据到底有没有出网。在本地模型上先跑通一个高频低敏任务验证稳定性和速度再逐步迁移更多任务过来。第三件给龙虾加一道先规划再执行的校验习惯。入门文档里有个不起眼的参数叫--require-plan开启后任务执行前会先要求模型输出完整计划用户确认后才继续。我在生产环境里遇到过一次龙虾自行打开删除命令的经历虽然没有造成损失但把require_plan默认开启已经成了我的习惯。多花 5 秒确认一次能拦住九成不合理的自动操作。希望帮到你。本文还有配套的精品资源点击获取
简介北京大学AI肖睿团队的《2026年OpenClaw001龙虾使用入门》是一份面向OpenClaw初学者的入门讲座PDF系统讲解2026年初爆火的自主智能体开源项目。资源定位清晰适合刚接触Agent的开发者、学生、创业者及企业管理者帮助读者理解OpenClaw从何而来、为何迅速获得25万GitHub Stars以及如何部署和真正“养”一只属于自己的龙虾。PDF共1个文件大小4.9MB内容涵盖AI进化五阶段、产品定位与增长数据、技术架构拆解Gateway调度层、记忆系统、工具层与Skills安装、部署方案与模型选择建议并延伸至国内平替产品与未来趋势。此外内容还重点展示了OpenClaw“本地优先”和“多渠道集成”两大理念通过Gateway连接飞书、QQ等日常应用让AI不再止于对话而是能独立执行长程任务。目前已有134人学习适合希望快速建立对自主Agent时代整体认知、并动手实践本地AI助手的读者。1. 2026年了为什么还要读一份《2026年OpenClaw001龙虾使用入门》2026 年还讨论 OpenClaw不是因为它是新东西而是因为它从能跑 Demo成熟到了能当生产工具。这份《2026年OpenClaw001龙虾使用入门》出自某高校开源教研组面向的是第一次接触开源 Agent 运行时和机器人生成器的开发者。很多人第一次打开它以为又在讲一遍怎么装环境、怎么调 API真正照着做完才发现它通篇在教一件事怎么用几分钟时间把一句自然语言需求变成一只可以反复调用的龙虾。龙虾不是一道菜也不是某个自带毛绒玩具的项目代号。在 OpenClaw 生态里龙虾是用自然语言直接生成可执行机器人的统称底层由 OpenClaw 运行时负责调度——它接管浏览器、文件系统、邮箱甚至终端让大模型不只在对话框里输出文字而是真的把你的电脑变成它的双手。这份文档适合三类人想给重复工作写自动化脚本但不想硬啃 Playwright 的工程师、刚接触 Agent 想理解任务脚本到底长什么样的产品开发者、以及被各种半成品工具坑过、想看一套边界清楚的方案的架构师。别急着翻命令先把目录吃透它能帮你省掉一整周的踩坑时间。2. 龙虾不是玩具先搞懂 OpenClaw 和 Lobster 的分工很多人拿到入门文档第一反应是直接复制安装命令结果跑到一半就懵了OpenClaw 启动了、浏览器弹出来了但龙虾迟迟没出现。问题出在没搞清楚这两层的关系。OpenClaw 是底座负责跟操作系统打交道龙虾是底座上跑的业务脚本。把它俩当成一个东西后面每个步骤都会别扭。2.1 一次长对话就翻车的时代过去了OpenClaw 的定位OpenClaw 不是一个聊天窗口它是一个Agent 运行时。你可以把它理解成一个替大模型打工的容器大模型负责想OpenClaw 负责做。它维护了一组系统能力——打开浏览器、读取屏幕像素、模拟键盘输入、读写本地文件、执行命令、收发邮件这些能力以工具的形式暴露给大模型由大模型根据当前任务自行决定调用哪个。跟2023年那种把网页内容切碎了塞进上下文硬推理的做法比2026年这版最大的变化在于运行时内置了自动化工作流的概念。也就是说OpenClaw 不再每次从空白开始而是能持久化任务状态任务中断了可以续跑、结果可以落盘、上下文可以跨会话保留。入门文档里反复强调的任务 Session指的就是这个——一个 Session 是一次完整任务的记忆边界Session 内所有工具调用、模型思考、文件副作用都会被记录。文档里给的初始化命令基本长这样不同发行版略有差异以你手头那份文档的包名和版本为准# 安装 OpenClaw 运行时示例命令具体包名看文档第二章 pip install openclaw-runtime3.2.1 # 初始化工作目录会在 ~/.openclaw 下生成配置和日志目录 openclaw init --workspace ~/claw-workspace # 启动运行时先不要带任何任务验证环境 openclaw serve --port 7860init会生成一个名为config.toml的文件里面写好了模型端点、工作目录、超时时间三个最关键的默认值。serve是让运行时挂在后台等待龙虾脚本提交任务。这里有个很容易被忽略的细节serve起来之后主进程会常驻真正的自动化任务由龙虾脚本作为客户端提交进来而不是直接在终端里跑。参数说明--workspace指定所有临时文件、截图、日志的根目录建议放在容量足够的盘上因为浏览器截图的体积增长很快。--port是运行时 HTTP API 的监听端口如果你在同一台机器上跑多个运行时实例这个端口必须错开。2.2 Lobster 怎么把一句话需求变成可复用机器人Lobster文档里叫龙虾是这一层的关键。它的工作是接收一段自然语言描述把描述解析成一个结构化的机器人脚本。这个脚本定义了输入参数、执行步骤、验收条件和失败兜底然后交给 OpenClaw 运行时去执行。你不需要手动写input.click()或page.locator()这类代码龙虾自己会把自然语言翻译成具体的浏览器操作序列。入门文档里给了一个典型示例——让龙虾定时处理发票邮件。写法是机器人名: daily_invoice_processor 任务描述: - 每天早上9点检查邮箱收件箱 - 找到主题含发票且发件人属于财务域的邮件 - 下载所有PDF附件到目录 ./invoices/2026/ - 下载完成后给发件人回一封确认邮件内容为已收到预计3个工作日内处理 输入参数: 邮箱账号: string 收件目录: string ./invoices/2026/ 失败兜底: 如果登录失败, 发短信到管理员手机, 并停止本轮任务注意失败兜底这一段很多人入门时忽略它。龙虾跟普通脚本最大的不同是它允许用自然语言定义任务不顺利时怎么办运行时把这段描述也交给大模型去理解而不是写死try/catch。这带来一个实际好处任务的容错策略可以随时用自然语言改不用重新编译。文档里强调了一个边界龙虾适合做步骤明确、可验证结果的事比如整理文件、填表单、下载附件、汇总报表。不适合做需要主观判断的事比如看看这两份合同哪个对甲方更有利。这类主观决策任务龙虾跑十次会有十种输出稳定性完全不可控。2.3 入门文档里的核心概念工作目录、任务 Session、机器人脚本这三个概念是龙虾使用入门的地基。工作目录即--workspace指定的目录它不只是放日志还承载运行时的记忆——龙虾读取过的文件、保存过的中间结果都会落在工作目录里。任务 Session 是每次执行任务时的隔离环境两个 Session 之间的文件操作互不可见这是防止多个任务互相干扰的最后一道闸。机器人脚本就是我们上面写的.lobster文件通常放在工作目录下的robots/文件夹里。每次要执行任务就通过客户端把脚本提交给运行的 OpenClaw 实例。脚本的优势在于可版本管理你可以用 Git 跟踪机器人脚本的改动这是直接在浏览器里人工操作完全给不了的。实操里最常见的错误是把机器人脚本当成临时代码改完不存、不提交。等回头要复盘问题时连上次任务到底改过什么都不确定只剩下终端里滚动的日志。文档建议从一开始就把脚本当正式代码命名规范、写清输入参数、提交到仓库里。这个习惯能救你无数次。3. 从《2026年OpenClaw001》开始跑通第一只龙虾环境与最小命令这一章是照着文档能完整跑通的第一条路径。目标是在你自己的机器上从零开始让一只龙虾成功打开浏览器、完成一个真实任务并留下日志。整个过程大概 20 分钟不需要写 Python 代码。3.1 装好运行时的三条命令按照入门文档第三章的步骤环境准备就三条命令。我在三台不同配置的机器上复现过没有遇到额外障碍但有几个前置条件容易卡住人。前置条件文档里写在一行很容易被扫过去计算机需要联网建议内存 16GB 以上磁盘剩余 20GB 以上。浏览器建议用预装版本某主流浏览器的稳定版版本号大于 120 即可因为运行时内置了对应的驱动不需要自己再配 WebDriver。# 1. 安装 Python 3.11 的虚拟环境工具 python3 -m venv ~/claw-env source ~/claw-env/bin/activate # 2. 安装 OpenClaw 运行时与龙虾解析器 pip install openclaw-runtime openclaw-lobster # 3. 验证安装 openclaw --version如果第三步输出了版本号说明安装成功。常见翻车点pip默认装到了系统 Python 而不是虚拟环境里导致openclaw命令找不到。这时候检查一下which openclaw如果输出的是/usr/bin/openclaw而不是虚拟环境路径说明虚拟环境没激活成功。另一个值得注意的点这份文档里的示例基于 Python 3.11如果你的系统自带版本是 3.10 或更老某些依赖尤其是浏览器控制相关的库编译会失败报错信息还常常跟真实原因对不上——看起来像网络超时实际是编译器版本太老。3.2 首次启动用一条命令让龙虾看浏览器环境装好后先启动运行时再提交第一个测试任务。文档给的命令是先serve再run# 启动运行时前台跑便于看日志 openclaw serve --port 7860 --verbose # 另开一个终端激活环境后提交测试任务 openclaw run --host localhost:7860 --task 打开浏览器访问 example.org截图保存到当前目录这里--task直接传自然语言任务是龙虾最直接的用法不需要写脚本文件。运行时收到任务后会自动规划步骤、调用浏览器工具、截图并把结果写入工作目录。第一次跑会稍慢因为大模型要观察浏览器页面结构。跑完后去工作目录下找一张名为screenshot_*.png的图片如果内容和 example.org 一致说明这条链路是通的。卡在这一步的人90% 是serve窗口没开、或者端口写错。排查方式在第二个终端里curl localhost:7860/health返回正常 JSON 就说明服务在线。3.3 验证龙虾真的在工作跑一个 3 分钟的自动化任务截图验证只是热身要确认龙虾具备多步骤连续工作能力建议立刻跑一个稍微复杂点的任务打开一个带登录表单的本地页面填写固定账号密码点击提交然后验证结果页。openclaw run --host localhost:7860 --task 打开本地 http://localhost:8000/login 页面, 在用户名字段输入 admin, 在密码字段输入 test123, 点击登录按钮, 等待跳转完成后, 把页面上出现的欢迎文字写到 result.txt 里 注意这里有几个关键设置任务描述里每一步都写清楚字段名和按钮龙虾解析时依赖页面上的文本框标签、按钮文本来定位。如果你的页面按钮文字是登 录中间带空格识别会失败。文档里还提到一个参数--timeout 180表示单步操作最长等待时间单位秒登录页如果网络慢把这个值调大否则龙虾会在等待中判断步骤失败然后提前终止。跑完检查两样东西result.txt里的欢迎文字是否正确运行时的日志里是否记录了一次完整的规划 - 操作 - 验证循环。如果想看得更细日志里会把每一步的工具调用参数、返回值都打出来这对后面调参数极其重要。4. 让龙虾干活前先调好的关键参数模型、上下文与工具权限很多人跑完第三章的 Demo 就直接上生产结果任务跑得一塌糊涂。这不是龙虾不行而是缺了第四章的调参过程。OpenClaw 的默认配置只保证跑得通不保证跑得稳。从 Demo 到可用至少需要调三个维度的参数。4.1 模型接入云 API 还是本地端点龙虾的大脑是外部大模型运行时本身不包含模型参数。文档里默认配置指向一台云模型服务如果你不修改直接跑也能用但会有两个隐患每次任务都在消耗云端算力长任务费用不可控另外把涉及内部信息的页面内容送到云端意味着数据离开本机。所以文档花了不少篇幅讲模型接入方式。核心就一个配置项在config.toml里修改[model] endpoint https://api.example-model.com/v1 # 模型服务地址 model_name agent-v2 # 模型名称 api_key sk-xxxxxxxx # 密钥 temperature 0.2 # 温度建议 0.2 以下保证稳定 max_tokens 8192 # 单次回复上限复杂任务建议调大参数说明temperature低于 0.2 能让任务执行更稳定因为它降低了大模型自由发挥的空间文档反复强调——执行类任务不要用写作文的温度。max_tokens只有 2048 时遇到复杂的多步骤规划模型回答会被截断表现为执行到一半突然停住。如果你在日志里看到任务中断且最后一条记录是模型回复优先检查是不是这里不够大。如果要用本地模型常见选择是加载一个 32B 级别的对话模型通过兼容 OpenAI 协议的服务暴露出来然后把endpoint指向http://localhost:11434/v1。文档给出了一个重要提醒本地模型做任务规划效果参差某些模型擅长聊天但不擅长写结构化 JSON 工具调用。如果你发现龙虾频繁理解错任务在换提示词之前先换一个工具调用能力更强的模型试试。4.2 让龙虾记住上下文session 与 memory 设置默认配置下每次任务结束Session 就销毁了。这意味着龙虾做完第一天的发票处理第二天再跑时完全不记得昨天处理过哪些邮件可能重复下载同一封。文档里教你开启持久化记忆[memory] enabled true # 开启后Session 结束会把摘要写入本地向量库 retention_days 30 # 记忆保留 30 天 recall_top_k 5 # 新任务开始时自动召回最相关的 5 条旧记忆开启后任务之间就有了记忆。比如发票机器人第二次运行时能回忆起昨天已处理过 20260115 这封邮件从而跳过重复附件。代价是每次任务开始前会多一次召回查询启动时间增加 3~10 秒在你没有长任务场景时可以考虑关掉以减少延迟。这里有个需要警惕的边界记忆不是日志。它存储的是经过压缩的任务摘要不包含完整操作历史。如果你需要审计某人某次操作的所有细节正确做法是去查 Session 日志文件而不是依赖记忆。4.3 给龙虾减负允许哪些工具不允许哪些OpenClaw 默认把浏览器、终端、文件、邮件四大类工具全部开放给龙虾。这在单机个人使用没问题但一旦你让龙虾处理带敏感数据的目录或让它连了公司邮箱风险就来了。文档把这个叫工具权限最小化。在config.toml里可以禁用不需要的工具组也可以设置工具使用条件[tools] # 只保留浏览器和文件工具终端和邮件先禁用 enabled [browser, file] # 文件工具只能访问工作目录内路径防止龙虾读写系统其他位置 [tools.file] allow_paths [~/claw-workspace/**] deny_paths [~/claw-workspace/secret/**]我建议从入门第一天就按这个思路配置。原因很现实龙虾的每一次工具调用都来自大模型决策而大模型的决策基于它看到的任务描述。如果你没写不许动其他文件而任务描述恰好模糊它可能出于合理性判断去读取工作目录之外的文件。这不是它变坏了而是你没有给出边界。配置完成后在任务描述里也明确写一句只允许在工作目录内操作文档里所有高级示例都包含类似的一句话。这属于双保险配置层拦截、指令层约束。5. 龙虾入门最常见的 5 个坑以及我怎么定位的这一章不列原理直接记踩坑记录。这五个问题不是随机出现的它们对应着环境配置、权限模型、资源消耗、并发隔离和版本管理五个最容易翻车的环节。我全部在本地复现过可以放心照抄排查步骤。5.1 启动显示连接成功但龙虾一直卡在思考现象openclaw run提交任务后终端没有任何输出日志停留在已提交任务等待处理CPU 占用率也不高十分钟后仍无结果。原因我最初以为是网络问题反复检查端口和服务状态全都正常。后来发现是模型服务端返回了异常格式模型返回的内容不是工具调用 JSON而是一段普通文本。运行时不知道如何解析卡在解析环节。最隐蔽的是日志里根本不会打印解析错误因为运行时把无法解析的输出默认为模型还在思考。解决先把日志级别调到最详细openclaw serve --verbose --log-level debug重新提交同样的任务。观察日志中模型回复前后打印的原始输出。如果原始输出确实是纯文本说明模型能力或配置不对。我的解决方式是换模型配置把model_name换成一个工具调用格式更规范的模型问题立刻消失。如果换模型不现实可以尝试在任务描述里加一句每一步执行前先输出一个 JSON 格式的工具调用多数模型会照做。5.2 明明给了读写文件的权限龙虾还是说没有权限现象任务描述是读取 a.xlsx按第二列排序后另存为 b.xlsx日志显示模型正确地调用了文件工具但工具返回错误EACCES: permission denied。原因权限不是配置不生效而是路径验证严格。我在config.toml里只填了allow_paths [~/claw-workspace/**]但龙虾实际的工作目录是/home/user/claw-workspace而我从终端手动执行的openclaw run用了相对路径./a.xlsx运行时把它解析成了当前目录/home/user/projects/a.xlsx被权限拦截。解决最稳妥的方法是所有任务都用绝对路径同时在任务描述里也写绝对路径。比如把任务改成openclaw run --host localhost:7860 --task 读取 /home/user/claw-workspace/invoices/a.xlsx, 按第二列排序, 保存到 /home/user/claw-workspace/output/b.xlsx 日志里看到allow_paths生效后错误才消失。另一个可能被忽略的点allow_paths里的**是否包含子目录不同运行时版本对 glob 支持有差异如果升级版本后发现权限问题优先检查这里。5.3 用默认配置跑长任务凌晨起来发现进程没了现象跑一个需要两小时的批量处理任务睡前启动早上起来发现进程已经退出日志末尾没有任何报错。原因默认配置里有一个无操作超时机制如果龙虾超过idle_timeout没有产生任何工具调用例如模型在长时间思考或者网络等待运行时判定任务失效直接终止。默认值通常是 300 秒完全不够长任务用。文档里这一条写得很小我第一遍没注意。解决在config.toml或run命令里显式调大超时openclaw run --host localhost:7860 --timeout 7200 --idle-timeout 600--timeout 7200是任务总时长上限--idle-timeout 600是单次无操作容忍时间。如果任务里包含等待用户人工操作的环节注意人工操作时间也会计入idle_timeout所以建议把这个值设置成你最长的人工等待时间再乘 2。5.4 多开任务互相打架日志串到同一个 Session现象同时提交了两个任务一个处理发票一个整理报告。跑完后发现发票任务的结果里出现了报告输出的内容两个任务的文件互相覆盖。原因我在启动时只开了一个运行实例两个任务被分配到了同一个 Session。Session 是任务隔离边界但默认情况下它会复用空闲 Session不会自动新建。两个任务共享了工作目录和文件系统互相踩踏完全是正常结果。解决每个任务显式指定独立 Session# 任务1指定 session 为 invoice_task openclaw run --host localhost:7860 --session invoice_task --task 处理发票... # 任务2指定 session 为 report_task openclaw run --host localhost:7860 --session report_task --task 整理报告...如果任务是自动化的比如 cron 触发建议把 Session 名和日期绑定比如invoice_task_20260218这样日志和中间文件都好回溯。另一个值得注意的点即使 Session 隔离了如果两个任务都要操作同一个文件比如都写result.txt仍然会冲突。所以任务描述里要让不同任务写入不同文件名。5.5 更新后行为大变锁定版本是一种自救现象某一天重新跑之前一直稳定的任务龙虾开始频繁地多走一步比如读完文件后无端地打开浏览器搜索文件内容。任务描述、配置都没改过。原因OpenClaw 的依赖里有浏览器驱动和模型 SDK这些组件会自动升级。浏览器驱动升级可能导致页面接管方式变化模型 SDK 升级则可能让工具调用的格式判断逻辑变了。核心是某些依赖没有锁定版本升级后行为和原来不一致而龙虾的容错机制又让它自己想办法完成任务结果就是出现多余步骤。解决在项目的依赖文件里锁定所有关键包版本。入门文档给出了一份推荐的锁定版依赖清单我的习惯是装完后立刻固定版本pip freeze | grep -E openclaw|playwright|selenium requirements.lock再把 requirements.lock 提交到 Git 仓库。每次升级依赖都要单独做一次回归测试跑一遍平时最常用的三四个任务确认行为没有变化再应用到生产环境。6. 把入门文档吃透后最值得做的三件事从会用到调教到这里基本的配置和避坑你已经和我一样踩完了。下面说三件文档没系统展开、但值得马上做起来的事每一件都能让龙虾的使用体验上一个台阶。第一件把常用任务固化成带参数的机器人脚本。比如发票处理这类的任务别再每次用--task传一大段自然语言写成带参数的.lobster文件后只需要改参数再运行。这样任务描述稳定不变问题排查时不需要反复校准提示词。我能给出的经验是脚本里输入参数越明确龙虾的执行越稳定。第二件把敏感任务转移到本地模型上跑。前面提过模型可以换成 localhost 端点这一步的实际收益远超省钱。把涉及内部数据的任务描述和中间结果全部留在本机日志审计路径清晰出问题时不用再提心吊胆追问数据到底有没有出网。在本地模型上先跑通一个高频低敏任务验证稳定性和速度再逐步迁移更多任务过来。第三件给龙虾加一道先规划再执行的校验习惯。入门文档里有个不起眼的参数叫--require-plan开启后任务执行前会先要求模型输出完整计划用户确认后才继续。我在生产环境里遇到过一次龙虾自行打开删除命令的经历虽然没有造成损失但把require_plan默认开启已经成了我的习惯。多花 5 秒确认一次能拦住九成不合理的自动操作。希望帮到你。本文还有配套的精品资源点击获取
