1. 先把 OpenClaw 本地部署这件事说清楚OpenClaw 是一个开源的 AI 智能体交互网关框架你可以把它理解成模型和业务之间的调度台上游接各种大模型服务下游接 CLI、Web UI、飞书这类 Channel中间做路由、权限和审计。它本身不训练模型也不绑定某一家厂商所以本地部署时最常被问到的就是两件事——怎么把服务跑起来以及模型通道怎么配。这篇聚焦本地部署场景围绕 CLI 和 Docker 两种启动方式给出 TaoToken 统一 Key 接入时的config.toml与settings.json配置骨架并演示 Ollama 本地模型接入后的连通性验证动作。适合已经装过 Node.js、想在自己机器上把 OpenClaw 跑通并且希望模型通道可切换本地 Ollama 和云端 API 都能用的开发者。整套流程我在 Ubuntu 22.04 和 macOS 上都走过一遍下面按可复制的顺序展开。需要提前说明的是OpenClaw 对运行环境有硬性要求Node.js ≥ v20.12推荐 22.x LTSPython ≥ 3.9Git 和 curl 必备。模型侧要求上下文窗口 ≥ 16K tokens接口协议兼容 OpenAI-style 的/v1/chat/completions否则会直接抛500 Internal Error。这两条是后面所有配置的前提。2. TaoToken 前置统一 Key 与 API 通道准备OpenClaw 的模型层支持多 provider但如果你想让本地 Ollama 和云端模型共用一套调用逻辑用一个统一的 API 通道会省很多事。TaoToken 在这里扮演的就是统一 Key 统一入口的角色你只需要在配置里填一个 base_url 和一个 Key就能在 OpenClaw 里切换不同模型而不用为每个厂商单独改代码。具体操作分三步。第一步打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册并登录。第二步进入控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在 API Keys 页面创建一个新 Key复制保存好这个 Key 只会完整显示一次。第三步确认你的 API 通道地址是 https://taotoken.net/api 后面配置里的 base_url 就填它。注意Key 不要直接写进会提交到 Git 的配置文件里。建议用环境变量注入或者放在.env中并加入.gitignore。下面配置骨架里我会用${TAOTOKEN_API_KEY}这种占位写法你替换成实际值或环境变量引用即可。如果你后续要做长期编码或 Agent 类任务可以了解下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它更适合高频调用的场景。单纯验证模型连通性的话用模型对话页 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 先测一下通道是否正常再回来配 OpenClaw能少走弯路。3. CLI 方式部署config.toml 配置骨架CLI 原生部署适合快速验证和开发调试启动快、配置透明。先创建工作区并初始化mkdir ~/openclaw-demo cd ~/openclaw-demo npm create openclawlatest初始化完成后项目根目录会生成配置文件。OpenClaw 的配置职责分散在几个文件里新手最容易踩的坑就是改错文件导致健康检查失败。这里明确一下config.toml管模型 provider 和网关基础参数settings.json管运行时行为和 Channel 开关。两者不要混着写。下面是接入 TaoToken 统一通道的config.toml骨架# config.toml [server] host 127.0.0.1 port 18789 cors_origin [http://localhost:3000, http://127.0.0.1:3000] [model] # 使用 OpenAI 兼容协议接入 TaoToken 统一通道 provider openai-compatible base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} model gpt-4o-mini max_tokens 4096 stream true [auth] enabled false # 开发阶段关闭生产环境务必开启几个关键点解释一下。provider写openai-compatible是因为 TaoToken 的 API 通道兼容 OpenAI 协议OpenClaw 会按标准/v1/chat/completions去请求。base_url填 https://taotoken.net/api 不要多加/v1OpenClaw 内部会自己拼路径。model字段填你要用的模型名切换模型只改这一行。如果你同时想保留本地 Ollama 作为备选可以在config.toml里加一段[model.ollama] provider ollama base_url http://localhost:11434/v1 model qwen2.5:7b max_tokens 4096然后在settings.json里指定默认走哪个{ runtime: { default_model_profile: openai-compatible, log_level: info, health_check_interval: 30 }, channels: { cli: { enabled: true }, webui: { enabled: false } } }这样配置的好处是日常调试用本地 Ollama 省钱需要更强模型时切到 TaoToken 通道改一个字段就行不用动代码。4. Docker 方式部署settings.json 与 compose 骨架Docker 部署适合生产预演和多服务协同隔离性强一键启停。镜像体积偏大2GB 以上但换来的是环境一致性。先准备docker-compose.ymlversion: 3.9 services: openclaw: image: openclaw/gateway:latest container_name: openclaw-gateway ports: - 18789:18789 - 3000:3000 volumes: - ./config.toml:/app/config.toml:ro - ./settings.json:/app/settings.json:ro environment: - TAOTOKEN_API_KEY${TAOTOKEN_API_KEY} - OLLAMA_HOSThttp://host.docker.internal:11434 extra_hosts: - host.docker.internal:host-gateway healthcheck: test: [CMD, curl, -f, http://localhost:18789/health] interval: 30s timeout: 5s retries: 3 restart: unless-stopped这里有两个容易忽略的点。第一容器内访问宿主机的 OllamaLinux 下要用host.docker.internal并配合extra_hosts映射否则localhost指向的是容器自己。第二config.toml和settings.json用只读挂载:ro避免容器内进程意外改写配置。Docker 场景下的settings.json建议把日志和健康检查调细一点{ runtime: { default_model_profile: openai-compatible, log_level: debug, health_check_interval: 15, request_timeout: 60 }, channels: { cli: { enabled: false }, webui: { enabled: true, port: 3000 } }, security: { cors: { origin: [http://localhost:3000] }, auth: { enabled: true } } }启动命令export TAOTOKEN_API_KEY你的Key docker-compose up -d docker-compose logs -f openclaw看到HTTP Server listening on 127.0.0.1:18789和Health Check: passed就说明容器起来了。5. Ollama 本地模型接入与连通性验证Ollama 接入是本地部署里最实用的组合零编译、模型自由度高。先启动 Ollama 并拉模型注意上下文长度要手动扩默认只有 4K不满足 OpenClaw 的 16K 要求OLLAMA_CONTEXT_LENGTH32768 ollama run qwen2.5:7b然后在另一个终端验证 Ollama 本身是否正常curl http://localhost:11434/health # 预期返回 {status:ok} ollama list # 确认 qwen2.5:7b 在列表中接着验证 OpenClaw 到模型的连通性。CLI 方式下直接发一个请求curl -X POST http://127.0.0.1:18789/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2.5:7b, messages: [{role: user, content: 用一句话介绍你自己}], stream: false }如果返回的 JSON 里choices[0].message.content有正常中文回复说明链路通了。再跑一次全链路自检npx openclawlatest check预期输出包含三行Model Provider: ollama、HTTP Server: listening on http://127.0.0.1:18789、Health Check: passed。到这一步本地 Ollama 接入就算完成了。想验证 TaoToken 通道是否也通把请求里的model换成config.toml里配的云端模型名再发一次同样的 curl能返回内容就说明统一 Key 通道工作正常。6. 本篇常见错排查部署过程中报错集中在几个固定位置按下面顺序排查基本能覆盖。Provider not found检查config.toml里provider字段拼写。ollama必须全小写写成Ollama或OLLAMA都会失败。用 TaoToken 通道时写openai-compatible不要写成openai。500 Internal Error多半是模型服务不支持 streaming 或 tool calling。先把config.toml里的stream改成false试一次如果通了就是流式协议不兼容。Ollama 老版本对 tool calling 支持不完整升级到 0.4.5 以上。健康检查一直失败按顺序查三件事。ollama list确认模型存在curl http://localhost:11434/health确认 Ollama 活着netstat -tuln | grep 18789确认端口没被占用。Docker 场景额外确认extra_hosts配了没有。CORS 报错、Web UI 打不开config.toml的cors_origin和settings.json的security.cors.origin要一致且必须包含你实际访问的地址http://localhost:3000和http://127.0.0.1:3000是两个不同 origin都要写。Key 无效或 401确认TAOTOKEN_API_KEY环境变量在启动进程的 shell 里已 exportDocker 场景确认 compose 文件里透传了。Key 前后不要带空格或引号。上下文超限报错Ollama 默认 4K必须用OLLAMA_CONTEXT_LENGTH32768启动或者用--num_ctx 32768参数。这个不设长对话一定崩。7. 配置收敛与后续接入把上面几步串起来看OpenClaw 本地部署本质是三段式环境对齐Node/Ollama 版本、配置收敛config.toml 和 settings.json 职责分清、协议适配OpenAI-style 接口 CORS 上下文长度。95% 的部署问题都出在这三段的某一环而不是框架本身。如果你在排障或接入过程中卡住建议直接对照 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 重新生成一个 Key 测试同时翻一下接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里的协议说明确认 base_url 和路径拼接方式。想先单独验证模型通道是否正常用模型对话 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 发一条消息最快。长期跑编码或 Agent 任务的话Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 在调用频率和成本上更合适。最后留一个实操建议把config.toml里的model字段做成环境变量引用比如model ${DEFAULT_MODEL}这样本地 Ollama 和云端通道之间切换只需要改一个环境变量不用每次动配置文件。这个习惯在多环境部署时能省掉大量重复劳动。