Skip to content

第 5 章 Agent 应用构造与生态 ​

第 4 章拆了 OpenClaw 与 DeepSeek Harness(DSH)两个框架的源码,看清了一个 Agent 运行时骨架里到底有什么。

骨架清楚了,问题就往外挪一层:同样的循环、同样的工具调用,装成什么形态才有人愿意天天用?

这一章换一种读法,不读源码,看货架。

一个 Agent 要真正干活,三样东西得凑齐:有平台承载它,有工具供它调用,有环境让它跑起来。要读写本机文件、接内部系统的通用 Agent,三样缺一不可,缺一样就停在演示阶段。

场景窄的 Agent 是例外。客服问答这类任务只靠云平台就能上线:知识库、渠道、对话编排平台都备好了,不挂 MCP、不碰本地环境也能跑。代价是能力停在平台工具箱以内。

这三样是最小骨架。落到生态层,再按“能力从哪来”切成五类:平台承载对应平台供给,运行环境对应应用供给,工具调用对应工具供给,自写 Server 对应开发供给,轻量封装对应封装供给。

所以我们按这个顺序走。先画生态地图,看清现在有哪几类东西(5.1),再列配置清单说明超级个体该备什么装备(5.2),最后给一套最省事的安装路径(5.3)。

5.1 Agent 应用生态 ​

生态这个词很容易讲空,说某地生态繁荣,等于什么都没说。

我们换一个能落地的切法:分类轴是能力供给形态,从厂商托管到自持轻量。

  • 平台供给(厂商托管):能力由厂商编排好,用户只填提示词(Prompt)和知识库。
  • 应用供给(装在本机):软件跑在自己的机器上,直接操作文件与终端。
  • 工具供给(挂 MCP):能力来自挂载的 MCP 服务端(MCP Server),接的是真实系统。
  • 开发供给(自己写 Server):能力由自己写成 MCP Server,对外发布。
  • 封装供给(说明加脚本):能力来自一份说明加一个脚本,轻到可以随手拷走。

前四类是常见分法,第五类单独拎出来,因为它在 2026 年占了轻量分发的位置。

这五类供给不是五选一,而是一套组合,下面逐类看形态、代表项目与适用边界。

先说清一件事。这不是一套 MECE 分类,底下混着三个正交问题:谁托管、能力由谁写、怎么打包。

同一样东西同时占两类很常见,OpenClaw 装在本机,又能挂 MCP Server。归类的规则只有一条:看你用它解决的那个问题,主要靠什么。

5.1.1 云端应用与智能体平台 ​

云平台的做法很统一。注册账号,打开可视化编辑器,填 Prompt,接知识库,再发布成一个网页、一个 API 或一个渠道机器人。

代表项目分两类。一类是大模型厂商的官方客户端,比如 OpenAI 的 Custom GPTs 和 Anthropic 的 Claude Projects。另一类是多 Agent 编排平台,比如 Dify、Coze(扣子),以及 CrewAI:开源版是代码框架,企业版才提供托管服务。

我们判断,起步验证阶段应该优先用云平台,原因不是便宜,是省掉了环境与运维两件事。

一个具体对比:用 Coze 做一个客服 Agent,接微信公众号或微信客服,两周可以上线(我们的项目经验值,1 名全栈、单一渠道、标准问答,视套餐与审核排期)。同样的功能自建要处理鉴权、限流、渠道回调与会话存储,两个月起步。

云平台还有一层隐性收益,它把渠道对接做完了。Coze 的国内版打通了微信公众号、飞书、抖音等发布通道,具体以平台发布页为准;这些接口自己接一遍,光审核就要排队。

但云平台有共同边界,多数产品默认不解决四件事。

  • 数据不能出内网时,多数云平台用不了。
  • 任务需要跨天保持状态时,默认的托管环境会回收会话。
  • 需要改循环内核时,多数平台不开放这一层。
  • 需要按自己的指标做评测时,平台默认只给通用面板。

自托管或私有化部署(如 Dify 自托管、平台私有化版本)能解掉前两条的一部分。数据不出内网这一条,自托管确实能解;跨天状态要看它有没有接外部存储,只靠默认会话还是会被回收。代价是自己承担运维。

还有一条更现实的成本:资产锁定。Prompt、工作流、知识库都长在别人家的数据库里,平台改计费方式或下线功能,迁移成本可能高于当初的开发成本。

5.1.2 本地部署应用 ​

本地应用指装在自己机器上的客户端与命令行工具。代表项目有 Claude Code、Codex CLI、OpenCode、OpenClaw,以及模型运行时 Ollama。

常见说法把本地部署讲成隐私问题,这个说法只对一半。

隐私仍是收益,但不是决定性差异;决定性的是执行权限。Agent 能读源码、跑测试、看报错、再改一遍,这个闭环在网页对话框里做不出来。

Claude Code 就是这样工作的。它在项目目录里直接读文件,跑单测,根据报错改代码。Codex CLI 与 OpenCode 走同一条路,只是实现细节不同。

OpenClaw 是另一种样本,它是多渠道网关,把 Telegram、Discord、Web 的消息收进同一套会话,进程重启后会话还在。

本书的写作管线就跑在这样一台机器上。主控 Agent 拆章节,写作、审校、试读三个角色并行干活,产物全部落在 git 仓库里。整条链路没有网页界面,只有文件和消息。

本地应用的边界也很清楚,它的稳定性取决于本机环境。Node 版本、Python 版本、代理设置,任何一项不对,经常表现为启动失败或工具调用失败。

反过来说,没有可管的开发机、需要多人协作、或要求企业级合规与审计时,本地部署不是首选,应该回到云平台或混合方案。

注意:本地 Agent 拿到的是当前用户的完整权限,一条误写的删除命令会导致工作目录里的源码与草稿一起丢失。所以在给它 shell 之前,先确认目录在 git 版本控制之下。

5.1.3 MCP 工具生态 ​

MCP 的全称是模型上下文协议(Model Context Protocol)。它由 Anthropic 在 2024 年 11 月提出。到 2026 年,主流客户端与主要厂商的 SDK 都已支持它;这是支持面,不是采用率。

架构是宿主—客户端—服务端。宿主应用(Host)里跑客户端(Client),一个 Client 连一个 Server;一个 MCP Server 可以暴露多个工具、资源与 Prompt。传输走 stdio 与 Streamable HTTP 两种,旧版 HTTP+SSE 已被取代。

这个设计解决了一个老问题。过去每接一个系统,就要在 Agent 里写一遍适配代码;现在写一次 MCP Server,就能被所有支持 MCP 的客户端挂载。

常见 MCP Server 按用途可以分成几类。

  • 代码与仓库:GitHub、GitLab 的 MCP Server,能读仓库、提 Issue、开 PR。
  • 数据库:MySQL、PostgreSQL 的 MCP Server,能查表结构、跑只读 SQL。
  • 文件系统:受限目录的读写服务。
  • 联网检索:Brave Search 的 MCP Server,补上模型的时效性短板。
  • 浏览器:Puppeteer、Playwright 的 MCP Server,能登录、截图、填表。

找工具先看官方仓库 modelcontextprotocol/servers,收录文件系统、GitHub、PostgreSQL 等基础实现。社区清单看 Smithery、awesome-mcp-servers 与 pulsemcp 三个入口。

工具生态的成熟度取决于两件事,一是能不能找到,二是敢不敢信任。

第二条更关键:MCP Server 是真实权限的代理,文件系统 MCP Server 如果把根目录配成 home,Agent 就能读到 ~/.ssh/id_rsa、~/.aws/credentials 这类本机凭证文件。

判断一个 MCP Server 能不能信,至少看三条。

  • 权限范围:按最小权限配置,文件系统只挂工作目录,数据库只给只读账号。
  • 来源审计:看维护者、提交历史与发布记录,来源不明的先在隔离环境跑一遍。
  • 沙箱隔离:用容器或低权限账号运行,把网络与文件访问限制在需要的范围内。

注意:stdio 型 MCP Server 的生命周期绑定客户端进程,客户端退出后 Server 会被一并杀掉。配置里写相对路径,会导致入口文件找不到。

MCP 也有它不适合的场景,有两类。

一是高频大流量搬运,每次调用结果都要回到模型上下文。1 MB 中文约 20–50 万 Token,几兆数据一次就能占满常见窗口,是否超限取决于窗口大小。

二是毫秒级响应场景。模型推理本身是百毫秒到秒级,MCP 的进程间调用不是主要延迟;只要 LLM 在回路里,就做不到毫秒级。量化交易这类场景不能用它做主链路。

想自己写 MCP Server,见 5.1.4。

5.1.4 MCP 开发与服务化 ​

先给一个定义:开发框架指写 MCP Server 的 SDK 与封装层。服务化指把写好的 MCP Server 发布出去、让别的客户端挂载:本地用 stdio,远程用 Streamable HTTP。

在 2026 年做 Agent 应用,很大一部分工作是把业务系统包成 MCP Server。

原因不复杂:模型优先走工具契约,不认你的前端界面。把 ERP、CRM、交易接口包成 MCP Server,比做一个页面更直接,也更容易复用。没有契约的界面只能靠浏览器代操作:登录、截图、填表一步步来,成本高,也容易碎。

框架分两档:底层是官方 SDK,Python 与 TypeScript 各一套,负责协议帧、类型约束与错误码。上层是装饰器封装。

这里说的 FastMCP 指独立的 fastmcp 包(pip install fastmcp),由 PrefectHQ 维护。它与官方 Python SDK 内置的 mcp.server.fastmcp.FastMCP 不是同一个实现:第 3 章用内置版,本节用独立包。

官方 SDK 给你控制力,独立 fastmcp 给你速度。分界在控制粒度:要自定义传输、鉴权、流式返回或精确控制错误码,用官方 SDK;只是把一组业务函数暴露成工具,日常业务封装用 FastMCP 就够了。

下面这个例子把订单查询包成工具。它做了三件事:校验参数、失败返回结构化结果、不让异常冒到协议层。

python
# erp_bridge.py
# 环境:Python 3.10+,pip install "fastmcp>=2.0"(2.0 为 API 下限)
import sqlite3
from contextlib import closing
from fastmcp import FastMCP

DB = "erp.db"
mcp = FastMCP("erp-bridge")

with closing(sqlite3.connect(DB)) as c:
    c.execute("CREATE TABLE IF NOT EXISTS orders (id TEXT PRIMARY KEY, amount REAL, status TEXT)")
    c.commit()

@mcp.tool
def get_order(order_id: str) -> dict:
    """按订单号查询订单。查不到时返回 ok=false,不抛出异常,由 Agent 决定下一步。"""
    with closing(sqlite3.connect(DB)) as c:
        row = c.execute(
            "SELECT id, amount, status FROM orders WHERE id = ?", (order_id,)
        ).fetchone()
    if row is None:
        return {"ok": False, "reason": "order_not_found", "order_id": order_id}
    return {"ok": True, "order": {"id": row[0], "amount": row[1], "status": row[2]}}

if __name__ == "__main__":
    mcp.run()

这段代码在独立 fastmcp 包 4.1.5 上跑通了命中与未命中两条分支(本文实测)。复现步骤:先建表并插入一条 A1001,再分别查 A1001 与 A9999。命中返回 ok=true;查不到返回 ok=false 与 reason=order_not_found。其中三个写法可以照搬,每一个都对应一个容易做错的地方。

工具描述要写给模型看,不要写给人看。第一句“按订单号查询订单”,就是模型选工具时最主要的判据之一。

失败要返回原因,不要抛异常。工具执行出错,可以在返回值里带 isError 与说明文本;异常冒到协议层,就只剩一个泛化错误码,模型看不到为什么失败。不少实现连说明都不给,只回一句调用失败。

返回体要控制大小,查询默认只回必要字段,明细另开一个工具。每一次返回都会进入模型上下文,字段越多,后面的推理越贵。

把入口文件写进客户端配置就能用。

json
{
  "mcpServers": {
    "erp-bridge": {
      "command": "python",
      "args": ["/absolute/path/erp_bridge.py"]
    }
  }
}

分发方式也在变:过去发布一个应用要打包安装程序,现在可以只发一个 MCP Server,用户导入客户端就能用。但 MCP Server 仍要处理协议、依赖与部署,于是有更轻的一档:Skill。

5.1.5 Skill 生态与轻量化分发 ​

Skill 的轻,先体现在结构上。

一个 Skill 就是一个目录:一份 SKILL.md 写清楚什么时候用、怎么用,再加若干脚本负责真正执行。

模型读到说明就知道该调它,执行时调脚本,行为可预期、结果可复现(前提是输入与环境稳定)。机制上,启动时只预载 name 与 description,正文在判定相关后才读入。

生态入口分两类。一类是厂商官方库,Anthropic 把 Agent Skills 做成开放格式并放出官方示例库,可以直接读源码看写法。另一类是社区市场,ClawHub(OpenClaw 的 Skill 市场)与各类 awesome 清单按用途收录可安装的 Skill,来源、更新时间和维护者都能查到。

拿到一个 Skill 常见两种方式:从市场安装,或者把目录拷进本地 skills/。

它和 MCP 的差别,可以按四个维度看。

  • 形态:MCP 是独立进程或远程服务,Skill 是文本加脚本文件。
  • 分发:MCP 要配传输方式、端口或镜像,Skill 拷贝目录就能用。
  • 执行:MCP 走跨进程协议,Skill 由本地 shell 直接跑。
  • 适用:MCP 接企业系统与重型工具,Skill 装个人手法与小型自动化。

我们的选型判据只有一条。需要跨语言、跨机器、多人共享鉴权就选 MCP,只是把一段固定流程固化下来就选 Skill。

一个 Skill 的最小结构如下。

text
skills/csv-dedupe/
├── SKILL.md
└── scripts/dedupe.py

SKILL.md 的头部是元信息,正文是步骤。

markdown
---
name: csv-dedupe
description: 按指定列去重 CSV,保留首次出现的行。适用于清洗导出的联系人名单。
---

运行 `scripts/dedupe.py --in a.csv --out b.csv --key email`。

脚本按 key 列判重,保留首次出现的一行。
key 列不存在或文件为空时,以退出码 1 退出,不生成输出文件。

这份说明里有两处是给模型看的。description 决定它会不会被选中,退出码约定决定它出错时模型怎么反应。

脚本正文只依赖标准库。

python
# scripts/dedupe.py
import argparse, csv, sys

p = argparse.ArgumentParser()
p.add_argument("--in", dest="src", required=True)
p.add_argument("--out", dest="dst", required=True)
p.add_argument("--key", required=True)
a = p.parse_args()

with open(a.src, newline="", encoding="utf-8") as f:
    rows = list(csv.DictReader(f))
if not rows or a.key not in rows[0]:
    sys.exit(1)

seen, kept = set(), []
for r in rows:
    if r[a.key] not in seen:
        seen.add(r[a.key])
        kept.append(r)

with open(a.dst, "w", newline="", encoding="utf-8") as f:
    w = csv.DictWriter(f, fieldnames=rows[0].keys())
    w.writeheader()
    w.writerows(kept)

运行 python scripts/dedupe.py --in a.csv --out b.csv --key email:输出只保留首次出现的行;无数据行或 key 列不存在时,以退出码 1 退出,不生成输出文件。

轻量带来的是分发成本低:拷一个目录就能走,不用配依赖。边界也在这里:Skill 的可靠性靠脚本本身,不靠模型自觉;说明写得含糊,模型就会选错工具。

把五类供给放进一张表,读者可以对着自己的场景看,边界更清楚。

表 5.1 五类供给对照

类型代表项目适用场景主要边界
平台供给OpenAI Custom GPTs、Claude Projects、Dify、Coze、CrewAI(企业版)快速验证、渠道接入、没有运维团队数据不出内网、跨天长任务、改循环内核受限
应用供给Claude Code、Codex CLI、OpenCode、OpenClaw、Ollama需要读写文件、跑命令的本地任务依赖本机环境,Agent 拿到的是用户权限
工具供给GitHub、GitLab、MySQL、文件系统、Playwright 等 MCP Server把 Agent 接到现有系统找到与信任的成本,高频大流量不适合
开发供给MCP 官方 SDK、FastMCP把内部业务系统封装成工具要处理协议、依赖与部署
封装供给Skill(SKILL.md + 脚本)固化个人流程、轻量分发可靠性取决于脚本本身

五类供给在真实项目里是搭配使用的。以一个技术顾问的日常工作为例:客户入口放在 Coze(平台供给),本地开发用 Claude Code 与 OpenClaw(应用供给),GitHub、MySQL 与浏览器通过 MCP Server 接入(工具供给),内部的报价系统自己包成一个 MCP Server(开发供给),每周的报表整理固化成一份 Skill(封装供给)。同一件事,五类供给各出了一份力。

组合原则是分工:云平台做入口和验证,验证通过的核心流程再往本地搬。

读者可以照这张表对号入座,再按这条原则组合自己的环境。

到这里,地图画完了。五类供给各管一段,组合起来才构成一个能干活的环境。

参考

5.2 超级个体基本配置推荐 ​

5.1 的生态地图解决了“有什么”的问题,本节解决“装什么”的问题,两者不是一回事。知道市场上有哪些工具,不等于知道自己的机器上该放哪几样。

我们的判断是,配置不在多,在稳,每多装一个工具,就多一条要维护的链路。版本升级、登录过期、依赖冲突,都会消耗你的时间。

四个抽屉分别是:底座层(Agent 网关与 Skill 池)、比特入口(代码、模型与办公数据)、感知层(搜索与浏览器)、记忆与文档层(本地向量与文档处理)。它们对应 Agent 干活时的四类动作:被调度、取资源、看世界、记事情,顺序也按这个来,不是按价格或热度排。真正的硬依赖只有一条:Node.js 之上才有 OpenClaw 与 Playwright,gh、hf、gog 与它们互不依赖,可以并行装。

动手前先确认机器:内存 16 GB 起步,最好 32 GB,硬盘给模型和缓存留出 100 GB(经验值,非实测)。不够的话,先解决硬件,再谈装什么,完整口径见 5.2.6。

完整的安装流程见 5.3。本节按 5.2.1 的原则过四个抽屉,每个工具只回答四件事:定位、装什么、验什么、注意什么。

5.2.1 只装有命令行入口的工具 ​

先立一条原则:能给 Agent 用的工具,必须有命令行入口(CLI)。理由很直接:Agent 的强项是调用确定性命令,读取结构化输出,再按退出码决定下一步。

这里的“入口”不限于二进制程序。库和 SDK 只要有固定的安装方式、能用一条命令验证,同样算数,tavily-python、python-docx 这类就属于此列。判断标准没有变,仍是能不能被脚本调用、能不能用一条命令验证。

图形界面需要人点,没有脚本入口、只能靠人点的 GUI 不适合交给 Agent:它只能靠截图和坐标去猜,猜中一次不难,猜中一百次很难。Playwright 这类工具有 API 与选择器,属于可脚本化的浏览器自动化,不在此列。登录弹窗、按钮改版、加载延迟,都会让流程失效。

判断一个工具值不值得装,我们看三条。第一,有没有稳定入口,参数和输出格式是否写进了文档。第二,退出码是否可靠,成功和失败能不能被脚本区分。第三,安装能否脚本化,版本能否用一条命令查出来。

三条都满足,才进入基础清单;只满足前两条的,放进候选区,等有明确任务再装。不要因为“以后可能用得上”就提前塞进环境。

举个常见例子:某个 SaaS 只提供网页后台,Agent 想批量导出数据,只能模拟点击。第一次或许能跑通,第二次遇到验证码就停了。这类工具不是不能用,而是不该放进基础清单。

这条原则也决定了安装顺序:先 CLI,后浏览器,浏览器是补充手段,不该当作默认做法;顺序反过来,你会把大半时间花在容易失效的页面选择器上。

5.2.2 Agent 网关与 Skill 池 ​

第一个抽屉是底座层,它决定 Agent 能不能被可靠调度,以及能不能按需加载能力。它和 5.2.4 的 Playwright 都依赖 Node.js,先确认 node -v 有输出;没有的话,Node 安装见 5.3.2。

我们选 OpenClaw 作为这一层的参考实现,它是一个开源的多渠道 Agent 网关,负责消息接入、会话状态和 Skill 调度。Telegram、Discord、Web 这些消息渠道,都可以接到同一套 Agent 上。说得具体一点:你在 Telegram 发一句,Agent 在服务器上执行,结果回到 Telegram。这就是网关在干的活。

安装完成后,先看三个命令,顺序别乱:先确认版本在,再看清单,最后看依赖。

bash
openclaw --version
openclaw skills list
openclaw skills check

skills list 是清单视图,每行标 ready 或 needs setup;后者不是坏了,是缺 API Key 或外部命令。skills check 是检查视图,输出 Eligible / Visible / Missing requirements 三类结果。它统计的是 Skill 能不能被加载,不等于环境坏了。多 Agent 主机上两个命令都要带 --agent <id>;不带时 stderr 会提示 no explicit owner,命令照常退出 0,但结果会落到默认 Agent 上,不能当作本机的检测结论。

Skill 的形态、目录结构,以及它和模型上下文协议(Model Context Protocol,MCP)的分工,5.1.5 已经讲过,这里只落到操作:先搜、再装、装前读脚本。

装 Skill 之前先搜,避免重复造轮子。

bash
openclaw skills search github
openclaw skills search playwright

搜到之后用 openclaw skills install 安装。来源可以是 ClawHub,也可以是 git 仓库或本地目录。团队内部写的 Skill,建议放 git 仓库,版本可追溯。

bash
openclaw skills install skills-sh:owner/repo/skill-name

注意:安装来源不明的 Skill,脚本会以你的用户权限运行,可能直接删除文件或泄漏密钥。安装前必须读一遍脚本内容。

底座层不追求数量,装十个用不上的 Skill,不如留三个每天都会调用的;数量多只会让 Agent 的选择变差,也会让排错变难。

5.2.3 代码、模型与办公数据 ​

第二个抽屉是比特入口,Agent 要取代码、取模型、取数据集,也要读写办公套件里的邮件、日程和文档,都需要一个统一的命令行入口。

gh ​

GitHub 是代码与协作的主场,gh 是它的官方命令行工具。仓库检索、Issue 追踪、PR 提交、Release 下载和 API 调用,它都覆盖。

安装命令按平台分开。

bash
# macOS
brew install gh

# Ubuntu
sudo apt update && sudo apt install gh

# Windows
winget install --id GitHub.cli

发行版仓库里的 gh 版本通常偏旧:截至 2026-11,Ubuntu 22.04 的 apt 源只到 2.4.0。装完先 apt policy gh 对一下版本,缺子命令时改按 GitHub 官方的 apt 源安装。

装完先验证版本,再登录。gh auth login 是交互式的,它会让你选 GitHub.com 或企业实例,再选浏览器登录或粘贴令牌(Token)。这一步不能省。

bash
gh --version
gh auth login
gh auth status

Agent 无人值守运行时,不适合走交互。更稳的做法是提前配好 GH_TOKEN 环境变量,并只给最小权限。令牌不要放进命令历史,也不要写进仓库。用环境变量或系统的密钥管理工具。

令牌的权限要按任务拆,只读仓库用一个令牌,提 PR 用另一个令牌,不要把所有权限塞进同一个变量。这样即使某个脚本出错,影响也能被限制在一个仓库里。

登录完成后,Agent 就能直接查仓库、读 Issue、提 PR。

bash
gh repo list --limit 20
gh issue list --repo owner/repo --state open
gh pr list --repo owner/repo --state open
gh api repos/owner/repo

这些命令的输出都是文本或 JSON,加 --json 可以指定字段,脚本解析会轻松很多。

bash
gh pr list --repo owner/repo --state open --json number,title,author

hf ​

Hugging Face 是模型与数据集的主要来源,hf 是官方 CLI,旧的 huggingface-cli 已经被它替代。

需要现成的 Hub 操作 Skill 时,直接查:

bash
openclaw skills search huggingface

安装用官方脚本,macOS 也可以用 Homebrew。

bash
curl -LsSf https://hf.co/cli/install.sh | bash -s

# macOS(可选)
brew install hf

装完登录并确认身份,三条命令足够。

bash
hf auth login
hf auth whoami
hf version

取模型时先只下需要的文件:7B 模型 bf16 权重约 15 GB,量化后 4–5 GB,13B 约 26 GB,70B 约 140 GB,整仓下载很浪费时间。

bash
hf download Qwen/Qwen2.5-7B-Instruct \
  --include "*.json" --include "*.safetensors" \
  --local-dir ./models/qwen2.5-7b

--include 可以多次指定,只取配置和权重。想先看仓库里有什么,可以用 hf download <repo> --dry-run 或网页端确认文件列表。

注意:默认缓存目录放在系统盘时,连续下载多个模型会导致磁盘写满,建议用 HF_HOME 指向大容量数据盘。

gog ​

办公数据这一类用 gog。它是 Google Workspace 的本地命令行工具,覆盖 Gmail、Calendar、Drive、Contacts、Sheets 和 Docs。安装走 Homebrew,包名是 gogcli,装出来的命令叫 gog。

bash
brew install gogcli
gog --version

首次使用要配置 OAuth 凭据,命令会把授权信息存到本地,后续调用不用重复登录。client_secret.json 由你自己创建:在 Google Cloud Console 里建 OAuth 客户端,类型选 Desktop app,下载下来的文件默认就叫这个名字。

bash
gog auth credentials /path/to/client_secret.json
gog auth add you@gmail.com --services gmail,calendar,drive,contacts,docs,sheets
gog auth list

验证看 gog auth list:退出码为 0,且列表里能看到刚授权的账号,这一段才算验完。

注意:凭据文件等同于账号权限,不要提交到仓库,也不要放进同步盘。

之后就能查邮件、列日程、搜云端文件。

bash
gog gmail search 'newer_than:7d' --max 10
gog calendar events primary --from 2026-11-01T00:00:00 --to 2026-11-07T23:59:59
gog drive search "Agent 架构" --max 10

5.2.4 搜索与浏览器 ​

第三个抽屉是感知层,模型的训练数据有截止时间,实时信息必须靠外部工具补。

搜索 ​

搜索我们优先选 Tavily,它面向 Agent 设计,返回的是压缩后的正文片段,不是整页 HTML。

这点很关键:整页 HTML 里导航、广告、脚本常常占去大半(因站而异,不做数字承诺),Token 会被大段占掉;片段式返回能提高信噪比,也能降低调用成本。

搜索结果的质量主要看查询怎么写。把问题写成一句完整的话,通常比三五个关键词更稳;具体写法还要看搜索引擎与查询类型。需要最新信息时,明确写出时间范围,别让模型自己猜。

配置分两步:先在 Tavily 控制台注册并拿到 API Key,再把 API Key 放进环境变量。API Key 不要写进代码,也不要提交到仓库。

bash
export TAVILY_API_KEY="your-key-here"

export 只对当前终端有效。临时验证可以这样写;长期使用要写进 shell 配置(.zshrc / .bashrc)或密钥管理工具。放 shell 配置之前,先确认你的 dotfiles 仓库没有收录这个文件。

Python 侧安装官方 SDK,最小调用如下。

bash
python3 -m pip install --upgrade tavily-python
python
import os
from tavily import TavilyClient

client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])
result = client.search("OpenClaw Skill 目录结构", max_results=5)

for item in result["results"]:
    print(item["title"], item["url"])

这段代码可以直接运行,前提是环境变量已经设置,依赖已经安装。返回结果里的 results 是列表,每条包含标题、链接和正文片段。

浏览器 ​

浏览器是最后一道补充,Playwright 能驱动 Chromium,完成动态渲染、登录填表、截图和抓取。

安装分三步;Linux 还要补系统依赖,这一步需要 sudo / root 权限。

bash
npm init -y
npm install -D playwright
npx playwright install chromium

# Linux(需 sudo / root)
npx playwright install-deps chromium

验证脚本保存为 check.mjs,内容如下。

javascript
import { chromium } from 'playwright';

const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'networkidle' });
console.log(await page.title());
await browser.close();

运行 node check.mjs,如果输出 Example Domain,说明浏览器已经能正常启动和渲染。

注意:Linux 上缺少 Chromium 的系统库时,page.goto 会直接报错,表现为浏览器启动失败或页面空白,必须先执行 install-deps。

浏览器能做的事很多,但要克制。能用 API 的不要用页面点击,页面结构一变脚本就要重写,更稳的做法是先找官方 API,再用浏览器兜底。

登录态也要单独管理,不要把账号密码写进脚本,也不要把 Cookie 提交到仓库。需要长期登录时,用独立的浏览器配置目录。

Tavily 和 Playwright 装好之后,Agent 怎么用?包成 Skill 或 MCP 工具挂上去,最小目录结构与 SKILL.md 骨架见 5.1.5。

5.2.5 本地向量与文档处理 ​

第四个抽屉是记忆与文档层,Agent 要长期工作,既要把历史信息存下来、按需取回,也要读写 Word、Markdown 和 PDF 这类文档。

向量 ​

我们建议本地跑一个向量嵌入(Embedding)模型,它负责把文本变成向量,响应快,隐私数据也不用出机器。

Ollama 是最省事的本地模型运行时,Linux 用官方脚本安装,macOS 用 Homebrew 或下载客户端。

bash
# Linux
curl -fsSL https://ollama.com/install.sh | sh

# macOS
brew install ollama

装完拉取 bge-m3,再用 ollama list 确认。

bash
ollama pull bge-m3
ollama list

bge-m3 支持多语言,输出 1024 维向量。中文、英文、长文本都能处理,适合做本地知识库的召回。

验证接口是否可用。

bash
curl http://localhost:11434/api/embed \
  -d '{"model":"bge-m3","input":"Agent 的长期记忆"}'

返回 JSON 里会有 embeddings 字段。拿到向量后要存起来,基础清单里我们先给一个默认答案:sqlite-vec。它是 SQLite 的向量扩展,单文件、不用另起服务,适合在本机跑知识库。它目前是 0.1.x(实测 0.1.9),接口还可能变,介意的话先上 Chroma 或 Qdrant。

bash
python3 -m pip install sqlite-vec

验证只要一段代码,能打印出版本号就算装好。

python
import sqlite3, sqlite_vec

db = sqlite3.connect(":memory:")
db.enable_load_extension(True)
sqlite_vec.load(db)
db.enable_load_extension(False)
print(db.execute("select vec_version()").fetchone()[0])

写入和查询之前,要把向量转成 float32 字节,Python 里用 struct.pack 或 numpy 的 astype("float32").tobytes(),直接传浮点列表会报类型错。

它的边界也要说清:按我们的经验值(bge-m3、1024 维、单机、千次级查询),十万级向量以内够用;数据量到百万级,或者需要多进程并发写入,就换 Qdrant、Milvus 这类独立向量数据库。那属于 5.2.1 说的候选区,等真到了那个量级再装,不要提前上一套集群。

模型只负责编码,检索策略、切块大小、重排规则都要另外设计。切块太大,召回会变粗,切块太小,上下文会断裂。

切块大小要按文档类型定,合同、代码和论文的最优粒度完全不同。起点可以先取 500–800 tokens、10%–15% 重叠,再用 20 条真实问题看 Recall@5 微调。没有测试集,调参就是碰运气。

文档 ​

文档处理是这一层的另一半,Agent 经常要读写 Word、Markdown 和 PDF。

我们的基线是 pandoc。它格式支持广,命令行稳定,适合做批量转换。

bash
# macOS
brew install pandoc

# Ubuntu
sudo apt install pandoc

pandoc --version

常见转换如下。

bash
pandoc report.docx -t markdown -o report.md
pandoc report.md -o report.docx

注意:pandoc 输出 PDF 要依赖外部引擎(LaTeX 或 wkhtmltopdf),没装引擎时 PDF 会直接失败;Markdown 与 DOCX 之间互转不受影响。

需要精细控制段落和样式时,用 python-docx。它能读写段落与表格,复杂样式、域和批注的支持有限,比纯文本转换更适合做模板填充。

bash
python3 -m pip install python-docx
python
from docx import Document

doc = Document("report.docx")
for paragraph in doc.paragraphs[:5]:
    print(paragraph.style.name, paragraph.text)

验证一行就够:python3 -c "from docx import Document" 不报错即可,5.2.6 的脚本会查这一项。它只处理 .docx,老的 .doc 要先转格式。

市面上也有一些封装好的 Office 命令行工具,具体命令随实现而变,跨团队使用时容易对不上;这里不点名,是避免为某个版本的实现背书。我们更倾向用有稳定包管理来源的 pandoc 打底,再用脚本补细节。这就是 5.2.1 说的候选区,等有明确任务再装。

5.2.6 配置验收脚本 ​

环境前提在这一小节给全:内存 16 GB 起步,最好 32 GB,硬盘至少留 100 GB 给模型和缓存(经验值,非实测)。要本地跑 7B 以上模型,再考虑独立显卡或统一内存的机器。

装完不等于配好,最后一步是把验收也脚本化。把下面这段保存为 ~/agent-lab/check-env.sh,与 5.3 的安装目录保持一致。它只做一件事:逐个确认清单里的项目是否可用。

bash
#!/usr/bin/env bash
set -u

cd "$(dirname "$0")"

fail=0

check() {
  local name="$1"
  shift
  if "$@" >/dev/null 2>&1; then
    printf 'PASS  %s\n' "$name"
  else
    printf 'FAIL  %s\n' "$name"
    fail=$((fail + 1))
  fi
}

check "node" node -v
check "npm" npm -v
check "openclaw" openclaw --version
check "gh" gh --version
check "hf" hf version
check "gog" gog --version
check "tavily" python3 -c "import tavily"
check "playwright" npx --no-install playwright --version
check "ollama" ollama --version
check "sqlite-vec" python3 -c "import sqlite_vec"
check "pandoc" pandoc --version
check "python-docx" python3 -c "from docx import Document"

if [ "$fail" -gt 0 ]; then
  printf '\n%d 项未通过\n' "$fail"
  exit 1
fi
printf '\n全部通过\n'

tavily、sqlite-vec、python-docx 是 Python 包,没有独立命令,所以用 import 验证。playwright 用 npx --no-install,只查本地装没装,不会顺手下载一个;普通 npx 可能把“临时下载成功”误判成“本地已装”。脚本全 PASS 时退出码为 0,任何一项 FAIL 都以退出码 1 结束,所以它既能当人读的报告,也能直接挂在 CI 或安装流程里当门禁。

Skill 的就绪度不进这个脚本,它取决于 API Key 和外部命令,不是装没装。单独查 openclaw skills check --agent <id> --json,看 summary.missingRequirements;多 Agent 主机需带 --agent <id>(原因见 5.2.2)。

运行方式如下。

bash
chmod +x ~/agent-lab/check-env.sh
~/agent-lab/check-env.sh

脚本查的是清单项,每个工具归哪一层、用什么命令验收,见下表。表中每一项都满足 5.2.1 的三条标准;最后一列的验收命令,就是第三条标准的落地。

工具所属层验收命令
Node.js底座层(前提)node -v
npm底座层(前提)npm -v
OpenClaw底座层openclaw --version
GitHub CLI(gh)比特入口gh --version
Hugging Face CLI(hf)比特入口hf version
gog比特入口gog --version
Tavily SDK感知层python3 -c "import tavily"
Playwright感知层npx --no-install playwright --version
Ollama记忆与文档层ollama --version
sqlite-vec记忆与文档层python3 -c "import sqlite_vec"
pandoc记忆与文档层pandoc --version
python-docx记忆与文档层python3 -c "from docx import Document"

清单内项目全部 PASS,只说明这些命令已经装上,登录状态还要单独查。

bash
gh auth status
hf auth whoami
gog auth list
ollama list

失败的项通常分三类:命令没装、PATH 没配、登录没做。先看 command -v 能不能找到,再看版本命令是否正常,最后查登录状态。按这个顺序排,比反复重装快。

上面的登录与模型验证都正常,基础配置才算过关。任何一项失败,先修那一项,不要继续往下装;带着坏掉的依赖往下走,后面每一步都会多一个变量。

配置是手段,不是收藏。工具装齐之后不要急着加更多,先用这套组合跑通一个真实任务,再决定下一步补什么;装完一项勾一项。

下一节 5.3 会把视角往前推一步:既然工具清单有了,怎么用最少的步骤把环境装起来?答案是让 Agent 自己装。

参考

5.3 超级个体的最简安装模式 ​

清单到手,第一道坎就是把它落到机器上。这一步最容易卡住,因为装工具本身就是一串重复劳动。

传统做法是人先学会所有工具,再逐个安装。装一个工具要查一篇文档,装五个就要查五篇,时间全花在重复劳动上。

问题不在工具本身,而在顺序。本节换一个顺序:先只装一个能执行命令的种子 Agent(连同它必需的 Node 运行时),其余工具交给它,人只负责验收。

这套方法只有四步。人工动手只有三处:装 Node、填 API Key、完成登录;另有两处只需确认:只读试探通过后、清单执行前。其余交给这个种子 Agent。文中用两级标记区分:【人工】要你动手,【人工确认】要你看一眼并回话。本节命令与版本以 2026 年 10 月为准:macOS 走 Homebrew,Ubuntu 走 NodeSource。

5.3.1 引导式安装的逻辑 ​

最简模式把驱动权交出去。人只负责搭一个最小可运行环境,后面的安装、配置、验证都由 Agent 接手,人只在关键节点确认。

这个环境里只有一个 Agent,它有终端权限,能读文件,能运行命令,也能看到命令的返回结果和报错信息。

它不需要很聪明,只要能执行,就能把后面的安装跑完,出错时还能根据报错继续尝试,不需要人一步步教。真正的下限是别编参数:连续两次编造命令参数,或同一个错误重复三次,就换一个种子 Agent。

这就是引导(Bootstrapping)的含义。用一个小的、已知的系统,去长出大的系统。编译器用它自己编译自己,包管理器用它自己升级自己,都是同一个思路。

差别不在工具数量。关键在于谁承担试错。人试错要付时间,Agent 试错只付一轮对话,成本结构完全不同。

人试错,一次报错就得停下查文档;Agent 试错,报错只是下一轮输入,改完继续跑,直到通过为止。

前提是权限,而且必须是可约束的权限:没有终端执行权,Agent 只能聊天,不能装机,也不能验证结果。

5.3.2 Node.js 运行时的安装与验证 ​

第一步,【人工】装 Node.js 运行时。人只需要装这一个运行时,其余工具都可以交给 Agent;只有这一层必须先落地,否则后面无从开始。

原因很实际。CLI Agent、Playwright,以及不少 MCP Server 都有 Node 实现,版本不够就会在启动阶段报错,根本进不了安装流程。

先装 Node,后面的工具才有共同的地基。本节要求 Node 24 LTS(24.22.1 ≤ v < 25)或 Node 26 LTS(v ≥ 26.12.1)。这组数字来自 OpenClaw 2026.10.9 版本的 engines,低于它,装得上也跑不起来。Playwright 另有下限,取两者都满足的版本;其他工具各看自己的 engines,不要照搬这组数字。

要自己复核,可以运行:

bash
npm view openclaw engines

macOS 有两条路:Homebrew 和 nvm。用 Homebrew 一条命令就够,装完不需要再配 PATH;如果已经装过旧版本,先升级再继续,不要在两个版本之间来回切换。

bash
brew install node

用 nvm 的话,分两步。先装 nvm:

bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh | bash

装完必须重开终端(或 source ~/.nvm/nvm.sh)。不重开就执行下一步,会报 nvm: command not found,后面的安装会全部卡在第一步,报错信息还很难看出原因。然后装 Node 24 LTS:

bash
nvm install 24

不想多查一次文档,就走 Homebrew 那条路。

Ubuntu 或 Debian 用 NodeSource 的 24.x 源。系统仓库自带的版本往往太旧,装完仍会缺新 API,后面还要返工。

bash
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs

注意:把远程脚本直接管道给 sudo bash 执行,脚本会在 root 权限下运行,来源被篡改时会导致系统被植入后门。

这条路装的是系统 Node,全局安装前缀属于 root。要在不加 sudo 的前提下装全局 npm 包,先把这个前缀改到用户目录:

bash
npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"

第二行还要追加到 shell 配置文件,重开终端才长期生效。不改前缀,后面所有 npm install -g 都要加 sudo,包会落到 root 的目录里,升级时容易和系统包管理器打架。

Windows 读者先装 WSL2,再在 WSL2 里按 Ubuntu 的方式安装 Node。原生 Windows 的 winget 安装方式本书不采用:路径和权限模型与书中示例不一致,命令不能直接照抄。

装完必须验证。版本门槛因工具而异,以各自的 engines 为准。Node 低于要求时,npm 只报 EBADENGINE 警告,不拦安装;能否运行取决于工具自身,部分 CLI 会在启动时报错,后面的步骤也就走不下去。

bash
node -p "process.versions.node"
npm -v

node -p 打印不带 v 的完整版本号。输出落在 24.22.1 到 24.x 之间,或不低于 26.12.1,才算通过;v25 即使高于 24.22.1 也不合格,engines 已经把 25 这个大版本排除在外。npm -v 也要能正常输出版本号。两条都通过,Node 这一层就算完成,可以进入下一步。

注意:装完两查,版本与终端重开。版本低于基线不会在安装时失败,只会在启动时暴露;nvm 装完未重开 shell 会报 nvm: command not found。

这一步不要跳。Node 装错,后面每一步都会带着错误往下走,最后表现出来的却是工具本身有问题,排查方向从一开始就错了。

5.3.3 种子 Agent 的安装 ​

第二步,装一个能执行命令的种子 Agent。整套安装都交给它,选错会让后面的步骤全部变成手工,等于白装。

选择标准只有三条:能读当前目录、能执行 shell、能多轮对话。界面漂不漂亮、模型排第几都不重要,能执行才是安装工;如果它连续两次编造参数,就换一个。

本例用 DeepSeek Harness(下称 DSH)。它的 npm 包是 @deepseek-ai/dsh,命令行入口是 dsh。选它是因为安装最轻,后面也能直接换成 Claude Code 或 Codex;版本验证不需要额外配置,模型 API Key 另配,见下文。

bash
npm install -g @deepseek-ai/dsh
dsh --version

dsh --version 能输出版本号,说明全局安装成功。如果命令找不到,先检查全局 bin 目录有没有在 PATH 里,这是最常见的原因。本文实测时为 0.2.1-rc.5,仍是预发布版本:想复现书里的结果,可以锁版本 npm install -g @deepseek-ai/dsh@0.2.1-rc.5;不锁就先跑 npm view @deepseek-ai/dsh dist-tags.latest 看当前 tag。

这里有一个取舍。全局安装最省事,但会装进当前 Node 的前缀目录:换 Node 版本时,旧包不会跟过去。

用 nvm 或 Homebrew 装的 Node 不需要 sudo。用系统 Node(Ubuntu 的 NodeSource、发行版仓库)时,全局安装前缀属于 root,不加 sudo 会直接报 EACCES。本书的选择是不用 sudo npm install -g,而是按 5.3.2 把前缀改到 ~/.npm-global:包归当前用户所有,升级时也不会和系统包管理器打架。反过来,用 sudo 装全局包,权限问题不会当场报错,会留到下一次升级时爆发,排查成本更高。

如果不用 DSH,Claude Code 和 Codex CLI 也能当种子 Agent。两者分别提供 claude 与 codex 命令,安装方式和 DSH 一样,换工具不需要重学流程。

bash
npm install -g @anthropic-ai/claude-code
npm install -g @openai/codex

它们的共同点不是模型,而是都能在当前目录执行命令。两者都有审批机制,可以在执行前拦住危险操作;具体开关见各自的文档。以下仍以 DSH 为例,换工具只替换安装与启动命令。

DSH 的工具能力来自 profile 装载的插件包。装了什么插件,它就能用什么工具,没装的命令它调不到,这一点和普通 CLI 不同。

【人工】模型 API Key 要单独配置,不能和工具安装混在一起。不要把 API Key 写进命令参数,也不要贴进对话或提交到仓库。

注意:API Key 出现在命令参数或截图里,会留在 shell 历史和日志中,导致 API Key 泄漏。

用环境变量,并且只写进当前用户的配置文件。这样 Agent 能从环境里读到,shell 历史里却不会留下明文,日志里也不会出现。

bash
export DEEPSEEK_API_KEY="你的 API Key"

把这一行追加到 ~/.zshrc 或 ~/.bashrc,重开终端生效。不同 shell 的配置文件不同,写错位置等于没配,Agent 读不到 API Key 就会停住。如果 dotfiles 仓库跟踪了这些文件,先把这一行移进不进版本库的本地文件,再 source 进来。

Agent 需要 API Key 时从环境变量读取。你不需要在每次对话里重复它,也不需要在代码里硬编码;换机器时,API Key 只改这一处。

5.3.4 专用目录与只读试探 ​

第三步,在专用工作目录里启动。启动后先试探一次。这一步决定 Agent 的活动范围,也决定出错时能不能收拾,不能省略。

交接要确认三件事:在哪个目录工作、能执行哪些命令、每次执行要不要人确认。这三件事定清楚,再让它动手,否则它会在错误的位置、用错误的权限,做一件看起来正确的事。第一件在本步落地;第二、三件写成 5.3.5 清单里的两行约束:命令范围与确认方式。

不要在主目录启动 Agent。给它一个专用工作目录,项目内的产物(配置、脚本、项目文件)都留在里面。删掉目录只回收这一部分,不等于完全回滚:npm install -g 写的是全局安装前缀(prefix),brew 装进 Homebrew 自己的目录,sudo apt 写系统目录,gh auth login 写 ~/.config/gh,这些都要单独卸载。

模型与登录凭据不在这个目录里:Ollama 的模型默认落在 ~/.ollama,gh 的凭据在 ~/.config/gh。要把模型也收进工地,先设 OLLAMA_MODELS=~/agent-lab/models 再拉取。

bash
mkdir -p ~/agent-lab
cd ~/agent-lab
dsh web

安装后用 dsh web 启动 Web 界面,也可以用 dsh --profile headless "任务" 跑一次性任务:它开一个全新的持久化会话,打印最终答案后退出,不保留交互界面。前者适合边看边确认,后者适合清单稳定后重跑。

这个目录就是它的工地,也是项目产物的回滚点。它能改的文件、能装的脚本,都限制在这里,项目之间不会互相污染。

第一次启动不要下安装指令。先做一次只读试探。看它能不能理解边界,再决定要不要交出写权限,这一步不能凭感觉。

列出当前目录的文件,说明你打算用哪些命令,不要执行任何写操作。

看它怎么回答,比听它自称多强、多可靠更准。它如果说得出目录结构,也说得清命令边界,就可以继续,说明它读懂了任务范围。

如果它一上来就要 sudo,先停下来。安装阶段需要 root 的只有几处:Node、Playwright 的系统依赖、Ollama、pandoc、gh 的包管理器安装。清单之外的 sudo 请求,先停下来问。

【人工确认】试探通过后,人看一眼它的回答,再进入正式交接。不要跳过这一轮只读试探。这一步看起来多余,实际是在确认它有没有读懂边界。

5.3.5 安装清单的交接 ​

第四步,把安装清单写成文件,再交给 Agent。文件是这次任务的合同,也是事后核对的依据,比口头指令更可靠。

清单比一句话可靠,也比聊天记录好复查。一句话容易漏步骤,文件可以反复读,也方便你逐条修改,下次还能接着用。

本节只列增量:分层口径来自 5.2 的四层清单(底座层、比特入口、感知层、记忆与文档层),验收脚本来自 5.2.6,两者要配套使用。顺带分清两个角色:OpenClaw 是要装进环境的第一件工具,DSH 是执行安装的种子 Agent,两者不是同类。

把下面内容保存为 ~/agent-lab/bootstrap.md。它同时写清目标、步骤和约束,Agent 读一遍就能开始,不需要再补充背景。

markdown
环境搭建任务

【目标】
在 ~/agent-lab 内完成工具链安装。除 Node 走用户侧安装外,允许的系统级改动只有四类:Playwright 的浏览器系统依赖(sudo)、Ollama 安装脚本(写 /usr/local/bin 并注册系统服务)、pandoc(发行版包管理器)、gh(发行版包管理器)。全局 npm 包放在用户前缀下,不写系统目录。除此之外不改系统配置。

【步骤】
1. 基线:运行 ~/agent-lab/check-env.sh(5.2.6 那份脚本),记录当前 PASS/FAIL。基线运行不追求全 PASS,返回非零也先记录再继续。
2. 底座层:全局安装 OpenClaw(`npm install -g openclaw`),验证 openclaw --version。
3. 比特入口:按 5.2.3 的命令安装 GitHub CLI 与 Hugging Face CLI(hf),完成后提示我执行 gh auth login 与 hf auth login。
4. 感知层:安装 Playwright 与 Chromium,并补齐系统依赖。
5. 记忆与文档层:安装 Ollama,把 OLLAMA_MODELS 指到 ~/agent-lab/models 后拉取 bge-m3;安装 pandoc。

【约束】
- 开始前先输出完整计划,等我回「继续」再执行。
- 之后每条命令先说明目的,等我回「继续」再执行。
- 只执行本文件列出的命令;清单外的命令先停下来问我。
- 需要 sudo 时先停下来问我(只限目标里的四类系统级改动)。
- 失败时先回滚:撤销本轮新增的包与文件,列出回滚清单,再报告原因。
- 改动 PATH 或 shell 配置文件前先报告,等我确认。
- 最后运行 check-env.sh,输出 bootstrap-report.md,列出每项的实际版本。

【人工确认】然后让 Agent 读这个文件,按清单执行。第一次建议用交互模式(dsh web,见 5.3.4)逐条确认;清单稳定之后,再用 headless 重跑:

bash
dsh --profile headless "按 bootstrap.md 执行,逐步验证,失败就停下来报告"

headless 跑完就退出,不占终端;会话本身仍会持久化,需要时可以接着聊。

这一步的关键是约束,不是清单长度:清单告诉它做什么,约束告诉它不能做什么,两者缺一不可。

交接要确认的第二、三件事就在这里落地:能执行哪些命令、每次执行要不要人确认。清单的【约束】已经写进命令范围和确认方式:只执行文件里列出的命令,每条命令前等回“继续”。

这里没有“一键授权”开关:Agent 能跑哪些命令、能改哪些目录,由运行配置和审批策略共同决定,不是一句口头授权能定下来的。

具体落点看种子 Agent:DSH 的 profile 目录里有 package.json 与 cordis.patch.yml,插件与工具清单在那里配置,命令与审批的开关也在 profile 配置里。本节只给文件位置,字段名以 DSH 的 profile 文档为准。换别的 CLI,就去查它的 profile 或配置文件;装好后还能改,改法以工具文档为准。

【人工】本书主张 gh auth login 由人完成。登录是身份动作,技术上可以交给 Agent,但那样等于把账号交给它,风险由你承担。同理,系统级依赖、全局 PATH、shell 配置文件,都要单独确认。这些改动影响的不只是当前项目,出问题时也很难回滚。

安装完成后,逐项验收,不要只看安装命令的退出码;退出码为 0 不代表工具能用,工具自己报出的版本才算数,这一步不能省。

bash
cd ~/agent-lab
./check-env.sh

check-env.sh 只要求最小集合里的八项 PASS:node、npm、openclaw、gh、hf、playwright、ollama、pandoc。其余四项没装,显示 FAIL 属预期,记 N/A:gog、Tavily SDK、sqlite-vec、python-docx。随后按 5.2.6 补四项登录检查:gh auth status、hf auth whoami、gog auth list、ollama list;gog 没装,同样记 N/A。其余项失败,再回到报告里找原因。

注意:只看到 npm install 成功就认为装好了,会漏掉浏览器内核和系统依赖,导致 Playwright 启动时崩溃。

5.3.6 方法边界与条件(非步骤) ​

这套方法省下的是重复的安装与排错。它没有让安装变简单,只是把重复动作换了一个执行者,复杂度并没有消失。

它也有边界,不是所有机器都能照搬:内网无法访问 npm 和模型仓库时,这套方法跑不通,先解决网络再谈自动化。

公司禁止全局安装时,要改成项目内安装,或者用容器隔离。这些限制不是技术问题,而是策略问题,Agent 无权绕过。

这些情况下,Agent 仍然能帮你查依赖、写脚本,但它不能替你绕过策略,也不该替你做这个决定,边界要人来划。

还有一个隐性成本,装完才意识到。种子 Agent 权限越大,出错的影响面越大,回滚也越困难,权限只给到够用。专用目录、逐条确认、失败回滚,这三条不能省:它们不是流程装饰,而是权限的刹车,缺一条都可能失控。三条已经写进 5.3.5 的【约束】。

这份清单可以固定成 bootstrap.md,换一个种子 Agent,流程照样能跑:清单是资产,Agent 只是执行者。本节给的是最小可运行环境,后面所有复杂配置都从这个环境长出来;下一步进入 Agent 阵列的组合与架构设计(见第 6 章)。

参考

文字 CC BY-NC-SA 4.0 | 代码 Apache-2.0