1. 先搞清楚 OpenClaw 到底在跑什么OpenClaw 是一个可以部署在本地机器或云服务器上的开源 AI Agent 框架核心由三块组成Gateway 负责通信调度Dashboard 提供可视化控制台Skills 则是 Agent 能调用的能力插件集合。它和普通聊天工具最大的区别在于运行位置和权限边界——普通工具跑在云端、权限受限、不能持久执行OpenClaw 跑在你自己的环境里能读写文件、调用系统命令、请求外部 API还能长时间后台运行。这意味着它适合想真正把 Agent 用起来的人需要自动化处理本地任务、想接入自己的业务系统、或者要做一个能持续干活的执行体。但也正因为权限高部署方式必须认真对待不建议直接装在日常办公电脑上独立服务器或容器隔离环境才是正确姿势。这篇就按从零到跑通的顺序把 Node.js 和 Docker 两条路都走一遍配置骨架直接给报错排查也一并列出来。2. 部署前先把 TaoToken 通道准备好OpenClaw 本身是框架它要调用大模型能力才能让 Agent 真正干活。这里我用 TaoToken 作为统一的模型接入通道好处是一个 Key 可以覆盖多种模型不用在配置文件里来回换不同厂商的地址和密钥。你需要先去官网注册并拿到 API Key然后确认两件事一是 Key 有余额或额度二是你要用的模型名称在文档里有对应说明。具体操作路径打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册登录后进入控制台在 API Keys 页面创建一个新 Key。创建时建议给 Key 起个能识别的名字比如 openclaw-local方便后面排查是哪个环境在用。拿到 Key 之后先别急着写进配置用一条 curl 验证通道是否通curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: claude-3-5-sonnet, messages: [{role: user, content: ping}], max_tokens: 16 }如果返回里有正常的 choices 内容说明 Key 和网络都没问题。这一步很关键因为后面 OpenClaw 报错时你要能区分是框架问题还是通道问题。模型对话的调试入口在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 可以在网页上直接试模型是否可用。长期跑编码类 Agent 的话Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 有更细的额度说明按自己用量选就行。3. Node.js 环境准备与 OpenClaw 安装3.1 系统基础依赖以 Ubuntu 22.04 为例先更新系统并装基础工具sudo apt update sudo apt install -y git curl unzip build-essentialbuild-essential 别省后面有些 skill 依赖原生模块编译缺了会报 node-gyp 相关错误。3.2 安装 Node.js 18OpenClaw 要求 Node 18 以上推荐用 nvm 管理版本避免和系统自带 Node 冲突curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 18 nvm use 18 nvm alias default 18验证node -v # 应输出 v18.x.x npm -v如果 node -v 还是旧版本检查 ~/.bashrc 里 nvm 的加载语句是否生效重新 source 一次。3.3 安装 OpenClaw CLI最快的方式是全局安装npm install -g openclaw openclaw --version看到版本号就说明 CLI 装好了。如果你要改源码或写自定义 skill走源码方式git clone https://github.com/openclaw/openclaw.git cd openclaw npm install -g pnpm pnpm install pnpm build源码方式后续命令前面要加 pnpm比如 pnpm openclaw onboard。4. 配置文件骨架与启动验证4.1 config.toml 骨架OpenClaw 的配置分两层全局配置和 Agent 配置。全局配置一般在 ~/.openclaw/config.toml骨架如下[gateway] host 127.0.0.1 port 18789 log_level info [model] provider openai-compatible base_url https://taotoken.net/api api_key sk-你的Key default_model claude-3-5-sonnet timeout_seconds 60 [agent] name local-agent workspace /home/youruser/openclaw-workspace max_concurrent_tasks 2 [security] allow_shell false allow_file_write true allowed_paths [/home/youruser/openclaw-workspace]几个点要注意base_url 填 https://taotoken.net/api 即可不要带多余路径allow_shell 默认关掉等确认 Agent 行为可控后再按需开allowed_paths 一定要限制在工作目录别写根目录。4.2 settings.json 骨架部分 skill 和 Dashboard 会读 settings.json放在工作目录下{ skills: { enabled: [http-request, file-read], disabled: [shell-exec] }, logging: { level: info, file: ./logs/agent.log }, dashboard: { enabled: true, port: 18790 } }4.3 初始化与启动配置写好后执行 onboardingopenclaw onboard --install-daemon这一步会初始化 Gateway、生成本地配置、注册后台服务。完成后检查状态openclaw gateway status正常输出包含 running、healthy、listening on port 18789。如果没起来直接看日志openclaw gateway logs启动 Dashboardopenclaw dashboard浏览器访问 http://127.0.0.1:18790能看到 Agent 状态、会话记录、Skills 管理和 Gateway 连接情况就说明主链路通了。5. Docker 方式部署与连通性测试5.1 Docker 环境准备服务器上装 Dockercurl -fsSL https://get.docker.com | sh sudo usermod -aG docker $USER newgrp docker docker --version5.2 用 Docker 跑 OpenClaw先建工作目录和配置mkdir -p ~/openclaw-docker/{config,workspace,logs}把上面第 4 节的 config.toml 放到 ~/openclaw-docker/config/ 下注意 workspace 路径改成容器内路径 /workspace。然后启动容器docker run -d \ --name openclaw \ -p 18789:18789 \ -p 18790:18790 \ -v ~/openclaw-docker/config:/root/.openclaw \ -v ~/openclaw-docker/workspace:/workspace \ -v ~/openclaw-docker/logs:/workspace/logs \ --restart unless-stopped \ openclaw/openclaw:latest查看日志确认启动docker logs -f openclaw看到 gateway listening 和 dashboard ready 就对了。5.3 连通性测试不管哪种方式跑通后做一次端到端验证。在 Dashboard 里新建一个会话发一条指令让 Agent 读一个文件并总结echo OpenClaw test content ~/openclaw-docker/workspace/test.txt然后在 Dashboard 输入读取 workspace 下的 test.txt 并告诉我内容。如果 Agent 返回了文件内容说明模型通道、Gateway、Skill 三层都通了。这一步验证的是 Agent 可控性——它只在你允许的路径下操作没有越权。6. 常见报错排查Gateway 起不来先看 openclaw gateway logs。最常见的是 Node 版本不对低于 18和端口被占用。端口检查用 ss -tlnp | grep 18789被占用就改 config.toml 里的 port。Dashboard 打不开如果是服务器部署检查防火墙和安全组是否放行了 18790。本地的话确认 dashboard 进程在跑ps aux | grep dashboard 看一眼。模型调用返回 401Key 写错或没带 Bearer 前缀。检查 config.toml 里 api_key 格式重新用第 2 节的 curl 验证一次通道。Skill 不生效先确认 settings.json 里 enabled 列表包含该 skill然后看日志有没有 schema 校验失败。改完配置要重启 Gatewayopenclaw gateway restart。Agent 行为不可控检查 security 段allow_shell 是否误开allowed_paths 是否范围过大。建议先用只读类 skill 跑通再逐步放开。Docker 容器反复重启docker logs 看具体错误多半是挂载路径权限问题给 workspace 目录加写权限chmod -R 755 ~/openclaw-docker/workspace。7. 接入文档与后续动作跑通之后建议把 Key 管理和接入细节再过一遍。API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 可以随时轮换 Key接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里有各模型的参数说明和兼容格式。如果你要接 Claude Code 这类编码 Agent参考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 的配置方式base_url 和 Key 的填法跟本文一致。控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里能看用量和调用记录排查问题时对照日志时间点很有用。整套跑下来验收标准就五条CLI 正常、Gateway running、Dashboard 可访问、至少一个 skill 生效、Agent 能完成一次完整任务。满足这五条你的 OpenClaw 就算真正搭起来了。