★ FEATURED ARTICLE 1. 先搞清楚 OpenClaw 到底在跑什么OpenClaw 这个项目在社区里被叫成“小龙虾”我第一次看到这个名字还以为是某个爬虫框架实际用下来才发现它更像一个“本地智能体调度台”。它的核心定位是把大模型的思考能力和本机的执行能力接在一起让模型不只是聊天而是能真的去开浏览器、读写文件、跑 Python 脚本。适合谁用适合已经会一点命令行、想让 AI 帮自己干重复活的开发者尤其是那些不想把数据传到云端、希望任务在自己机器上闭环的人。理解它的工作流比记命令重要得多。OpenClaw 把整个系统拆成四块大脑是 Model负责理解和规划双手是 Skills负责具体执行比如浏览器操作、文件读写、代码运行耳朵和嘴巴是 Channels负责你跟它交互的入口Web 界面、终端、飞书机器人都算中间还有一个 Gateway相当于中枢神经把上面这些模块串起来。你下达一句“帮我整理下载目录里的 PDF”实际发生的是Gateway 把指令转给 ModelModel 规划出步骤再通过 Skills 去调用文件系统和脚本执行最后把结果回传到 Channel 给你看。这个结构决定了它的安装和配置不是“装完就能用”而是要把 Model、Gateway、Channel 这几段分别接通。很多人卡住不是因为命令敲错而是没意识到自己只启动了 Gateway却没配 Model结果发指令过去没有任何反应。所以下面我会按“环境准备 → 安装 → 配置 → 启动 → 验证 → 排障”的顺序走一遍每一步都给出可复制的命令和配置文件片段你照着做基本能跑通第一个任务。在开始之前先确认你的环境。OpenClaw 对系统没有特别苛刻的要求Linux、macOS、Windows 都能跑但 Windows 下建议用 WSL2因为部分 Skills 依赖的浏览器自动化和脚本执行在原生 Windows 上路径处理容易出问题。Node.js 建议 18 以上Python 建议 3.10 以上这两个是很多 Skill 的运行基础。你可以先用下面两条命令确认版本node -v python3 --version如果 Node 低于 18去官网装一个 LTS 版本即可。Python 这边如果版本太低后面跑代码类 Skill 会报语法错误。环境确认完就可以进入安装环节了。2. TaoToken 前置准备把模型通道先打通OpenClaw 本身不带模型它需要你提供一个能调用的模型接口。这里有两种思路一种是本地跑 Ollama适合对数据隐私要求高、且机器性能够的场景另一种是接一个兼容 OpenAI 协议的云端接口省去本地显存和下载模型的麻烦。我实测下来如果你只是想快速跑通第一个任务用云端接口更省事因为不用等模型下载也不用担心本地显存不够。TaoToken 在这里的角色就是提供这样一个兼容接口。它的 API 地址是https://taotoken.net/api你需要在控制台生成一个 API Key然后在 OpenClaw 的配置里把 Base URL 和 Key 填进去。注意OpenClaw 的模型配置字段通常叫baseUrl和apiKeyModel ID 则填你实际要用的模型名。这三件套——Base URL、Key、Model ID——缺一不可少一个就会在发请求时报 401 或者 model not found。先去控制台把 Key 拿到手地址是https://taotoken.net/api-keys。生成之后复制保存因为有些平台只显示一次。拿到 Key 之后你可以先用一条 curl 命令验证这个 Key 能不能正常调通避免后面在 OpenClaw 里排查半天发现是 Key 本身的问题curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer 你的API_KEY \ -H Content-Type: application/json \ -d { model: 你的模型ID, messages: [{role: user, content: 你好}] }如果返回里有choices字段和正常的中文回复说明通道没问题。如果返回 401检查 Key 有没有复制完整如果返回 model not found检查 Model ID 拼写。这一步过了再进 OpenClaw 配置就顺很多。另外提一句如果你后面打算长期用 OpenClaw 跑编码类或 Agent 类任务可以考虑 Coding Plan它在高频调用场景下比按量计费更划算。不过第一个任务阶段先用按量或试用额度跑通流程就行不用一上来就纠结套餐。3. 可复制配置安装 OpenClaw 并写入 openclaw.json安装 OpenClaw 的方式取决于你用的包管理器。官方推荐用 npm 全局安装命令如下npm install -g openclaw装完之后用openclaw --version确认一下。如果提示命令找不到检查 npm 的全局 bin 目录有没有加到 PATH 里。Windows 下如果用 WSL2就在 WSL 的终端里装不要混用 Windows 的 npm。安装完成后第一步是初始化配置。运行openclaw onboard这个向导会问你几个问题Mode 选 QuickStartModel 这里先选自定义或 OpenAI 兼容然后把前面拿到的 Base URL、API Key、Model ID 填进去。Channel 初次可以选 Skip后面在 Web 界面里再加。向导结束后会在你的用户目录下生成~/.openclaw/openclaw.json。这个文件是核心配置建议直接用编辑器打开核对一遍确保模型段写对了。一个可用的openclaw.json模型配置片段大概长这样{ models: { default: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: 你的API_KEY, model: 你的模型ID } }, gateway: { port: 18789, host: 127.0.0.1 }, channels: { web: { enabled: true } } }注意baseUrl填到/api这一层就行不要自己加/v1OpenClaw 内部会拼接路径。model字段填你实际要用的模型 ID跟前面 curl 测试时保持一致。gateway.port默认是 18789如果这个端口被占用改成别的比如 18790后面访问控制台时用新端口。如果你想把文件读写限制在某个目录里可以在配置里加一个 workspace 字段{ workspace: { root: /home/你的用户名/openclaw-workspace, allowWrite: true } }这样 OpenClaw 执行文件类 Skill 时只会在你指定的目录里操作不会误删系统文件。这个设置我建议一开始就加上尤其是你打算让它跑文件整理任务的时候。配置写完后启动网关openclaw gateway start这个终端窗口要保持运行或者你可以用nohup openclaw gateway start 让它后台跑。启动成功的话终端会打印出监听地址和登录 Token把 Token 记下来下一步登录控制台要用。4. 验证请求跑通第一个任务并看到结果网关起来之后新开一个终端窗口运行openclaw dashboard它会输出一个 URL通常是http://127.0.0.1:18789。用浏览器打开输入刚才启动时生成的 Token 登录。进去之后你会看到一个对话框这就是你指挥小龙虾的地方。第一个任务建议选一个简单但能体现完整链路的比如让它读一个本地文件并总结。先在 workspace 目录里放一个test.txt随便写几段文字。然后在对话框里输入请读取 workspace 目录下的 test.txt用三句话总结内容。如果配置正确你会看到它先规划步骤然后调用文件读取 Skill最后把总结返回给你。这个过程如果卡住通常是 Model 没配通或者 workspace 路径不对。你可以看网关终端的日志里面会打印每次请求的模型调用和 Skill 执行情况。再试一个稍微复杂点的验证浏览器 Skill打开 example.com把页面标题告诉我。这个任务会触发浏览器自动化。第一次运行可能会下载浏览器驱动稍微等一会儿。如果返回了页面标题说明浏览器 Skill 也通了。到这里你的 OpenClaw 基础流程就算跑通了。如果你在验证阶段遇到reading choices相关的报错通常是模型返回格式不符合预期检查一下 Model ID 是不是对话模型有些补全模型不返回 choices 结构。遇到local proxy failed检查 baseUrl 有没有写错或者网络能不能通到taotoken.net。遇到 401回到第 2 步重新验证 Key。5. 本篇常见错排查401、proxy failed、OAuth 逐个拆第一个高频错误是 401 Unauthorized。这个基本就是 Key 的问题三种可能Key 复制时带了空格、Key 已经失效、或者配置里apiKey字段名写错了。OpenClaw 有些版本要求字段叫apiKey有些叫api_key你打开openclaw.json对照官方示例确认一下。另外注意如果你在 curl 里测试通过但 OpenClaw 里报 401大概率是配置文件里的 Key 和 curl 用的不是同一个。第二个是local proxy failed或连接超时。这个错误说明 OpenClaw 尝试请求模型接口时没连上。先确认baseUrl写的是https://taotoken.net/api不要多写斜杠或路径。然后确认你的机器能正常访问这个域名可以用curl -I https://taotoken.net/api看返回码。如果返回 404 是正常的说明域名通了如果直接连接失败检查本地网络或防火墙设置。第三个是reading choices报错。这个通常出现在模型返回体里没有choices字段的时候。原因可能是 Model ID 填成了一个非对话模型或者接口返回了错误信息但被当成正常响应解析了。解决办法是先用第 2 步的 curl 命令确认这个 Model ID 能返回标准对话结构再填回配置。第四个是 OAuth 相关报错。如果你在配置 Channel 时选了需要 OAuth 的渠道比如某些办公 IM但没完成授权流程就会报这个。初次跑通阶段建议 Channel 先 Skip等基础任务跑通了再回来配 IM。如果确实要配确保回调地址和 AppID、AppSecret 都填对并且网关重启过。还有一个容易被忽略的端口占用。如果 18789 被别的程序占了网关启动会失败或 dashboard 打不开。用lsof -i :18789查一下有占用就改配置里的端口然后重启网关。排查的时候养成看日志的习惯。网关终端会实时打印请求和错误大部分问题看日志就能定位到是哪一段没通。如果日志里模型请求返回了具体错误码直接按错误码去查比盲目改配置快得多。6. 后续怎么用从跑通到日常第一个任务跑通之后你可以开始加 Channel比如把 Web 界面换成飞书机器人这样在手机上也能发指令。配置方式是在openclaw.json的channels字段下加对应平台的参数然后openclaw gateway restart。不过建议一次只加一个渠道加完验证通过再加下一个避免多个渠道同时出问题不好定位。Skills 方面默认自带的文件、浏览器、代码执行已经能覆盖不少场景。如果不够用可以在对话框里输入/install 技能名来装社区技能。装之前看一眼技能说明确认它需要的权限和依赖有些技能会要求额外的 Python 包或系统工具。日常使用中我建议把 workspace 目录固定下来所有文件操作都限制在里面这样即使模型规划出错也不会影响到系统其他文件。另外涉及删除、发送邮件这类操作开启人工确认模式让它在执行前先问你一下。这些设置都在openclaw.json里改完重启网关生效。如果你后面调用频率上来了可以关注一下 Coding Plan它在长期编码和 Agent 任务上比单次调用更省心。接入文档在https://taotoken.net/doc里面有各语言的调用示例和字段说明遇到配置问题可以先翻文档。模型对话入口在https://taotoken.net/chat想快速验证某个模型 ID 能不能用直接在那里试一句就行不用每次都写 curl。
阅读完成 · 觉得有帮助？
