企业官网建设流程全解析

简介：《OpenClaw完全使用手册（202602v1）》面向希望上手开源个人AI助手平台的开发者与进阶用户，聚焦本地部署、国内网络环境适配与技能插件扩展三大核心诉求。OpenClaw以本地优先架构运行，可通过Telegram、飞书、钉钉等平台交互，并具备文件读写、终端命令执行、浏览器自动化等执行能力，手册围绕这些能力给出系统化指引。资源包为1个PDF文件，约3.48MB，内容涵盖基础功能、文档处理、浏览器自动化、通讯平台集成、技能插件系统与高级应用场景，并专章讲解国内部署环境准备、模型选择配置及常见问题解决，另附Windows、macOS、Linux、Docker与云服务器多平台部署指南，以及安全加固、权限管理、监控审计与命令速查、配置参考、故障排除等附录。目前已有191人学习，适合需要从零搭建并深度定制个人AI助手的读者按目录逐章查阅。

1. 从一台吃灰的迷你主机说起：OpenClaw 到底能帮你干什么

上个月我把一台 N100 的迷你主机从柜子里翻出来，本来想装个 NAS 就完事，后来发现用它跑 OpenClaw 才是这台机器最舒服的归宿。简单说，OpenClaw 是一个可以完全跑在本地环境里的 AI 助手框架，它把「模型推理」和「技能插件」拆成了两层：底层可以接本地模型，也可以接云端 API；上层通过 skill 插件机制，让助手能真正去操作文件、执行命令、调用外部服务，而不是只会在对话框里聊天。这跟网页版助手最大的区别在于，你的数据、你的脚本、你的工作流都留在自己机器上，插件想怎么改就怎么改。适合谁？一类是手里有闲置 Linux 小主机、想搭个私人自动化助手的后端开发；另一类是不放心把内部文档丢给在线服务、但又确实需要 AI 帮忙处理重复劳动的团队。这篇就按我实际部署和调试的顺序，把安装、配置、skill 编写和几个血泪坑一次讲透。

2. 部署前先把架构想清楚：本地模型还是 API 接入

2.1 OpenClaw 的两层结构决定了你怎么选算力

很多人一上来就问「OpenClaw 只能用接入 API 的方式使用算力吗」，其实不是。它的设计把「推理后端」和「助手运行时」解耦了，你可以理解成两块积木：

• 推理层：负责把自然语言变成模型输出。可以是本地跑的模型服务（比如用 Ollama 拉一个量化模型），也可以是任何兼容 OpenAI 接口规范的远程端点。
• 运行时层：OpenClaw 本体，负责管理会话、加载 skill 插件、调度工具调用、维护上下文。

这个分层带来的直接好处是：你可以在同一台机器上先接本地模型跑通流程，等发现算力不够再换成 API，配置文件里改一个base_url和model字段就行，skill 代码一行不用动。反过来也一样，先用 API 验证业务逻辑，再迁到本地做数据隔离。

选型上我的建议很直接：如果你只是想让助手处理文本、写写脚本、整理文件，本地 7B 到 14B 的量化模型足够；如果你需要它读长文档、做复杂推理、稳定调用多个 skill，本地小模型会频繁翻车，这时候接 API 更省心。别一上来就追求全本地，先跑通再优化，这是我踩过的最大的时间坑。

2.2 硬件和系统的最低门槛

OpenClaw 本体对机器要求不高，真正吃资源的是本地推理。下面这张表是我在几种常见环境下的实测感受，供你判断自己的机器能不能扛：

系统层面，Linux 是最省事的，Windows 用户建议走 WSL2，别硬扛原生环境。安卓端通过 Termux 也能装，但那是应急方案，不适合长期跑，后面避坑章节会细说。

2.3 安装前的依赖清单

在动手之前，把这几样确认好，能省掉后面一半的报错：

# 确认系统版本和架构 uname -a # 确认 Python 版本，建议 3.10 以上 python3 --version # 确认 pip 可用 pip3 --version # 如果要用本地模型，先装好 Ollama ollama --version

逻辑说明：OpenClaw 本体是 Python 写的，所以 Python 版本是第一道门槛，低于 3.9 会在装依赖时直接失败。uname -a是为了确认你是 x86 还是 ARM，ARM 环境下部分预编译包可能缺失，需要源码编译。Ollama 不是必须的，但如果你想走本地推理，提前装好能避免后面来回切换。

参数上没什么可调的，唯一要注意的是 pip 源。国内环境建议换成镜像源，否则装依赖能等到你怀疑人生：

pip3 config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

这条命令是写进用户级配置的，不影响系统其他 Python 环境，后悔了用pip3 config unset global.index-url就能撤。

3. 从零跑通第一个会话：安装、配置与模型对接

3.1 拉取本体与初始化配置目录

OpenClaw 的安装方式取决于你拿到的分发包形态。常见做法是克隆仓库后本地安装：

# 克隆项目到本地 git clone <openclaw-repo-url> openclaw cd openclaw # 创建独立虚拟环境，避免污染系统 Python python3 -m venv venv source venv/bin/activate # 安装依赖 pip install -r requirements.txt

逻辑说明：用虚拟环境是硬性习惯，因为 OpenClaw 的依赖里可能包含特定版本的 HTTP 库和模型 SDK，跟系统里其他项目冲突是迟早的事。source venv/bin/activate之后，你所有的 pip 安装都只作用于这个目录，删掉 venv 文件夹就等于卸载干净。

初始化配置目录一般在首次启动时自动生成，也可以手动建：

# 创建配置目录 mkdir -p ~/.openclaw # 复制示例配置 cp config.example.yaml ~/.openclaw/config.yaml

~/.openclaw/config.yaml是核心配置文件，后面所有模型和 skill 的设置都在这里改。建议先备份一份原始文件，改坏了能快速回滚。

3.2 对接本地模型：以 Ollama 为例

如果你走本地推理，配置大概长这样：

# ~/.openclaw/config.yaml model: provider: openai_compatible base_url: http://127.0.0.1:11434/v1 api_key: ollama model: qwen2.5:7b max_tokens: 2048 temperature: 0.7

逻辑说明：Ollama 默认在 11434 端口提供兼容 OpenAI 的接口，所以provider填openai_compatible就能直接对接。api_key随便填，Ollama 不校验，但字段不能空，否则某些客户端库会报错。model要跟你ollama list里看到的名称完全一致，大小写和标签都不能错。

参数上，max_tokens控制单次回复长度，本地小模型建议别超过 2048，否则生成慢且容易跑偏。temperature是创造性参数，做文件整理、命令执行这类任务时建议调到 0.2 到 0.3，减少它自作主张的概率。

启动 Ollama 并拉模型：

# 启动服务 ollama serve & # 拉取模型，首次会下载几个 GB ollama pull qwen2.5:7b # 验证模型可用 ollama run qwen2.5:7b "你好"

3.3 对接 API：改三个字段的事

如果你决定用远程 API，配置改成这样：

model: provider: openai_compatible base_url: https://your-api-endpoint/v1 api_key: sk-your-key-here model: your-model-name max_tokens: 4096 temperature: 0.5

逻辑说明：跟本地配置唯一的区别就是base_url和api_key。这里要注意，base_url一定要带/v1后缀，很多兼容接口不带这个后缀会 404。api_key建议用环境变量注入，别硬编码在配置文件里：

export OPENCLAW_API_KEY="sk-your-key-here"

然后在配置里写api_key: ${OPENCLAW_API_KEY}，这样配置文件即使被同步或备份，密钥也不会泄露。

3.4 启动并验证第一个会话

配置好之后启动本体：

# 激活虚拟环境 source venv/bin/activate # 启动 OpenClaw python -m openclaw start # 或者用提供的启动脚本 ./scripts/start.sh

启动后如果看到监听端口的日志，说明本体起来了。用 curl 验证一下：

curl -X POST http://127.0.0.1:8000/chat \ -H "Content-Type: application/json" \ -d '{"message": "列出当前目录下的文件"}'

逻辑说明：这个请求会走完整的「接收消息 → 模型推理 → 返回结果」链路。如果返回正常文本，说明模型对接成功；如果返回超时，多半是模型服务没起来或者base_url写错；如果返回 401，检查api_key。

到这一步，一个能对话的 OpenClaw 就跑起来了。但真正让它有用的，是下一步的 skill 插件。

4. 写一个能干活儿的 skill：插件机制与实战

4.1 skill 的加载逻辑和目录约定

OpenClaw 的 skill 本质上是一个带元信息的 Python 模块，放在指定目录下会被自动扫描加载。常见约定是项目根目录下的skills/文件夹，每个 skill 一个子目录：

skills/ file_organizer/ __init__.py skill.py manifest.yaml

manifest.yaml描述这个 skill 叫什么、干什么、需要什么参数，本体靠它决定什么时候把任务路由过来。skill.py里是实现逻辑。这个设计的好处是插件之间完全隔离，删掉一个目录就等于卸载一个 skill，不会影响本体。

4.2 一个文件整理 skill 的完整实现

下面这个例子实现「把指定目录下的文件按扩展名分类到子文件夹」：

# skills/file_organizer/skill.py import os import shutil from pathlib import Path def organize(directory: str, dry_run: bool = True) -> dict: """ 按扩展名整理目录下的文件 :param directory: 目标目录 :param dry_run: 为 True 时只打印计划，不实际移动 """ target = Path(directory).expanduser().resolve() if not target.is_dir(): return {"error": f"{target} 不是有效目录"} plan = {} for item in target.iterdir(): if item.is_file(): ext = item.suffix.lower().lstrip(".") or "no_ext" plan.setdefault(ext, []).append(item.name) if dry_run: return {"dry_run": True, "plan": plan} moved = 0 for ext, files in plan.items(): sub = target / ext sub.mkdir(exist_ok=True) for name in files: shutil.move(str(target / name), str(sub / name)) moved += 1 return {"dry_run": False, "moved": moved, "groups": list(plan.keys())}

逻辑说明：dry_run参数是这个 skill 最关键的设计，默认 True 意味着第一次调用只返回计划不实际动文件，确认无误后再传 False 执行。expanduser()处理~路径，resolve()把相对路径转成绝对路径，避免因为工作目录不同导致操作错地方。返回结构统一用 dict，方便本体把结果转成自然语言回复。

对应的manifest.yaml：

name: file_organizer description: 按扩展名整理指定目录下的文件 parameters: - name: directory type: string required: true description: 要整理的目录路径 - name: dry_run type: boolean required: false default: true description: 是否只预览不执行

参数说明：required决定模型是否必须提供这个参数，default是模型没给时的兜底值。description写清楚很重要，模型是靠这段文字判断什么时候该调用这个 skill 的，写得含糊它就会乱调。

4.3 调试 skill 的常用手段

skill 写完不生效，先看本体日志里有没有加载记录。常见做法是启动时加--log-level debug：

python -m openclaw start --log-level debug

然后在日志里搜 skill 名字，能看到「loaded」「skipped」「error」三种状态。如果显示 skipped，多半是manifest.yaml格式有问题；如果显示 error，看堆栈定位到具体行。

单独测试 skill 逻辑，不用每次都走模型：

# 直接调用函数验证 from skills.file_organizer.skill import organize print(organize("~/Downloads", dry_run=True))

这样能把「skill 本身有没有 bug」和「模型有没有正确调用 skill」两个问题分开排查，效率高很多。

5. 避坑与排查：那些让我重装三次的问题

5.1 模型返回正常但 skill 从不触发

现象：对话能正常回复，但让它整理文件，它只会说「好的，我来帮你整理」然后就没有然后了。

原因：manifest.yaml里的description写得太泛，或者参数描述跟用户说法对不上，模型判断不出该调用哪个 skill。

解决：把description写成具体的动作描述，比如「当用户要求按文件类型分类、整理下载目录时调用」，而不是「文件整理工具」。参数描述也尽量贴近用户口语，模型匹配靠的是语义相似度。

5.2 本地模型把 skill 参数编错

现象：skill 被触发了，但传进来的directory是「我的下载文件夹」这种自然语言，不是真实路径。

原因：小模型对参数格式的理解能力有限，尤其是 7B 以下的模型。

解决：两个方向。一是换更大的模型，14B 以上明显改善；二是在 skill 里做参数清洗，把常见口语映射成真实路径：

PATH_ALIASES = { "下载": "~/Downloads", "桌面": "~/Desktop", "文档": "~/Documents", } def normalize_path(raw: str) -> str: for key, real in PATH_ALIASES.items(): if key in raw: return os.path.expanduser(real) return os.path.expanduser(raw)

这个映射表按自己习惯维护，比指望模型每次都输出标准路径靠谱得多。

5.3 Termux 里装完跑不起来

现象：在安卓 Termux 里按教程装完，启动就报缺少编译好的 wheel。

原因：Termux 是 ARM 环境，部分依赖没有预编译包，pip 会尝试源码编译，而 Termux 默认缺编译工具链。

解决：先pkg install python clang rust把工具链补齐，再装依赖。但说实话，Termux 方案只适合临时验证，长期跑建议还是用 Linux 小主机，性能和稳定性都不是一个量级。

5.4 配置文件改了不生效

现象：改了config.yaml里的模型，重启后还是用旧的。

原因：OpenClaw 可能同时读了项目目录下的配置和~/.openclaw/config.yaml，优先级搞反了。

解决：用--config显式指定配置文件路径，避免歧义：

python -m openclaw start --config ~/.openclaw/config.yaml

同时检查环境变量里有没有覆盖配置的项，环境变量优先级通常高于文件。

5.5 长对话后响应越来越慢

现象：刚开始很快，聊了几十轮之后每次回复要等很久。

原因：上下文越堆越长，本地模型处理长上下文的开销是线性甚至超线性增长的。

解决：在配置里设置上下文窗口上限和历史裁剪策略：

context: max_history: 20 strategy: sliding_window

max_history控制保留最近多少轮对话，sliding_window是滑动窗口裁剪，超出就丢最旧的。做任务型对话时这个值可以设小一点，10 到 15 轮足够。

6. 进阶：让 skill 组合起来干复杂活儿

单个 skill 能做的事有限，OpenClaw 真正有意思的地方是让模型自己编排多个 skill。比如「把下载目录里的图片挑出来，压缩后放到归档文件夹」这个任务，可以拆成三个 skill：list_files、compress_image、move_files，模型根据 manifest 里的描述依次调用。

这里有个技巧：在 skill 的 description 里写明前置条件和输出，模型编排的准确率会明显提升。比如compress_image的描述写成「输入是图片文件路径列表，输出是压缩后的文件路径列表，需在 list_files 之后调用」，模型就能理解调用顺序。

验证 skill 组合是否按预期执行，我习惯在本地开一个追踪日志：

# 在 skill 入口加一行追踪 import logging logging.basicConfig(filename="skill_trace.log", level=logging.INFO) def compress_image(paths: list) -> dict: logging.info(f"compress_image called with {len(paths)} files") # ... 实际逻辑

跑完之后看skill_trace.log，调用顺序、参数、返回一目了然。这个习惯帮我定位过好几次「模型跳过了某个 skill 直接编结果」的问题。

还有一个容易被忽略的点：skill 的返回值尽量结构化，别返回一大段自然语言。模型拿到结构化数据后自己会组织语言回复用户，你返回自然语言反而容易让它二次加工出错。我一般返回{"status": "ok", "data": {...}}这种格式，需要展示给用户的文本让模型自己生成。

从那以后我每次写完新 skill，都强制走一遍「dry_run 预览 → 单测函数 → 接入对话验证 → 看追踪日志」这四步，再也没出现过 skill 误操作文件的情况。希望这些经验帮到你，少走点我踩过的弯路。

本文还有配套的精品资源，点击获取