★ FEATURED ARTICLE 1. 为什么本地部署 AI Agent 平台成了 2025 年的选型分水岭如果你正在搜「OpenClaw 本地部署 AI Agent 平台选型」大概率已经踩过或正在纠结这几个坑云端 Agent 按 token 计费账单像坐火箭客户数据要过第三方服务器合规部门不签字想换个模型发现工具调用代码全得重写。OpenClaw 是一个开源、本地优先的 AI Agent 运行时平台它把推理循环、工具调用、记忆、安全沙箱全部放在你自己的机器上跑适合对数据主权敏感、用量大、需要深度定制的团队和个人开发者。我先把结论摆出来本地部署不是「回到石器时代」而是把 AI 能力的所有权拿回来。云端方案OpenAI Assistants、Vertex AI Agent Builder 这类开箱即用是真的但每 token 计费、数据必须经过第三方、功能被平台锁死也是真的。OpenClaw 的定位是在「可控性」和「便捷性」之间找平衡——它不像完全自研那样什么都得从头造也不像云端那样交出控制权。这篇文章不聊虚的直接交付三样东西一份可复制的 docker-compose 配置片段、一套模型接入的 Base URL 与 API Key 环境变量模板、以及一条用 curl 验证 Agent 工具调用链路是否打通的检查步骤。选型决策部分我会从数据主权、开源可控、成本三个角度拆开讲每个角度都配上可跟做的操作。先说数据主权。云端 Agent 意味着你的每一行提示词、每一次工具调用结果都要经过模型供应商的服务器。即使对方承诺不留存、不训练你也无法从技术上验证。金融、医疗、法律行业的合规要求往往直接禁止数据出境或经过第三方。OpenClaw 本地部署后所有数据落在你自己的 VPC、物理服务器或边缘节点除了你主动配置的外部连接没有任何隐性外泄通道。你可以用防火墙白名单彻底阻断外网做到物理隔离。再说开源可控。OpenClaw 的核心是一个轻量级 Agent 执行引擎模型适配器、工具调用器、记忆模块、安全过滤器全部以插件形式挂载。这意味着你可以按需裁剪——想跑在树莓派上就把重插件去掉想上生产就加 gVisor 沙箱和审计日志。模型层支持任何兼容 OpenAI API 的端点不管是本地 Ollama、vLLM还是私有化部署的商用模型切换时工具代码不用动因为适配器层会把不同模型的响应统一成标准格式。最后说成本。云端按 token 计费用量越大边际成本越高本地部署是一次性硬件投入加电费用量越大边际成本越低。对于每天几万次推理的场景本地部署的年成本可能只有云端的几十分之一。当然本地部署有运维成本需要人管模型服务、数据库、监控这笔账要算清楚。选型时我一般建议团队按「数据敏感度」和「定制需求」两个维度打分两项都高的直接上 OpenClaw 这类本地方案数据不敏感、用量小、只想快速验证的云端更省事。下面进入实操先把 OpenClaw 跑起来。2. TaoToken 前置统一接入层解决多模型切换的痛点本地部署 OpenClaw 之后下一个问题马上来了模型从哪来你可能有本地 Ollama 跑的开源模型也可能需要调用一些商用模型做复杂推理还可能团队里每个人用的模型不一样。如果每个模型都单独配一套 Base URL 和 Key配置会变得非常乱切换模型时容易出错。这时候需要一个统一的模型接入层。TaoToken 提供的就是这样一个统一入口你只需要记住一个 Base URL 和一套 API Key就能在 OpenClaw 里接入多种模型切换模型时只改 Model ID不用动其他配置。它的 API 地址是 https://taotoken.net/api兼容 OpenAI 的接口规范所以 OpenClaw 的模型适配器可以直接对接。为什么要在 OpenClaw 前面加这一层三个原因。第一配置收敛。OpenClaw 的配置文件里模型部分只需要写一个 endpoint不用为每个模型维护不同的地址和密钥。第二切换成本低。今天用这个模型做推理明天想换另一个只改 model 字段就行工具调用代码完全不用动。第三便于团队协作。团队成员共用一套接入配置新人上手时不用挨个申请各家 API Key。具体怎么配OpenClaw 的模型配置支持 openai_compatible 类型你只需要填三个东西Base URL、API Key、Model ID。Base URL 填 https://taotoken.net/apiAPI Key 从控制台生成Model ID 填你要用的模型标识。这三件套在后面的 docker-compose 和环境变量模板里都会出现。这里要提醒一句API Key 不要硬编码在配置文件里用环境变量注入。OpenClaw 支持从环境变量读取配置前缀是 CLAW_。你可以把 Key 放在 .env 文件里docker-compose 启动时自动加载这样配置文件可以进版本库Key 不会泄露。如果你还没生成 Key可以去控制台创建一个。生成后先别急着填我们先把 OpenClaw 的 docker-compose 配置写好再统一注入。接下来进入可复制配置环节我会给出完整的 docker-compose 片段和模型接入的环境变量模板。3. 可复制配置docker-compose 片段与模型接入环境变量模板这一节是全文的核心操作部分所有配置都可以直接复制。我假设你在 Ubuntu 22.04 上操作已经装好 Docker 和 Docker Compose v2。如果你还没装先执行sudo apt update sudo apt install docker.io docker-compose-v2 -y sudo systemctl enable docker sudo systemctl start docker如果你要用 GPU 加速本地模型还需要装 NVIDIA Container Toolkitcurl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \ sed s#deb https://#deb [signed-by/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g | \ sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list sudo apt update sudo apt install -y nvidia-container-toolkit sudo nvidia-ctk runtime configure --runtimedocker sudo systemctl restart docker装好基础环境后创建项目目录并写 docker-compose 文件mkdir -p ~/openclaw-deploy cd ~/openclaw-deploy下面是 docker-compose.yml 的完整片段包含 OpenClaw 核心服务、PostgreSQL、Redis 和 Chroma 向量库version: 3.9 services: openclaw-core: image: openclaw/openclaw:1.2.0 container_name: openclaw-core restart: unless-stopped ports: - 8080:8080 environment: - CLAW_DB_HOSTpostgres - CLAW_DB_PORT5432 - CLAW_DB_NAMEopenclaw - CLAW_DB_USERclaw - CLAW_DB_PASSWORD${CLAW_DB_PASSWORD} - CLAW_REDIS_HOSTredis - CLAW_REDIS_PORT6379 - CLAW_MODEL_BASE_URL${CLAW_MODEL_BASE_URL} - CLAW_MODEL_API_KEY${CLAW_MODEL_API_KEY} - CLAW_MODEL_ID${CLAW_MODEL_ID} - CLAW_VECTOR_HOSTchroma - CLAW_VECTOR_PORT8000 depends_on: postgres: condition: service_healthy redis: condition: service_started networks: - claw-net postgres: image: postgres:16-alpine container_name: openclaw-postgres restart: unless-stopped environment: - POSTGRES_DBopenclaw - POSTGRES_USERclaw - POSTGRES_PASSWORD${CLAW_DB_PASSWORD} volumes: - pg-data:/var/lib/postgresql/data healthcheck: test: [CMD-SHELL, pg_isready -U claw -d openclaw] interval: 10s timeout: 5s retries: 5 networks: - claw-net redis: image: redis:7-alpine container_name: openclaw-redis restart: unless-stopped command: redis-server --appendonly yes volumes: - redis-data:/data networks: - claw-net chroma: image: chromadb/chroma:0.5.0 container_name: openclaw-chroma restart: unless-stopped ports: - 8000:8000 environment: - CHROMA_SERVER_CORS_ALLOW_ORIGINS* volumes: - chroma-data:/chroma/chroma networks: - claw-net volumes: pg-data: redis-data: chroma-data: networks: claw-net: driver: bridge注意几个关键点。第一openclaw-core 的环境变量里CLAW_MODEL_BASE_URL、CLAW_MODEL_API_KEY、CLAW_MODEL_ID 这三个就是模型接入三件套值从 .env 文件读取。第二所有服务在同一个 claw-net 网络里容器之间用服务名互相访问比如 openclaw-core 连数据库用 postgres:5432不用写 localhost。第三PostgreSQL 配了 healthcheckopenclaw-core 会等数据库就绪再启动避免启动顺序问题。接下来写 .env 文件把敏感信息和模型接入配置放进去cat .env EOF # 数据库密码自己改一个强密码 CLAW_DB_PASSWORDchange_me_to_a_strong_password # 模型接入三件套 CLAW_MODEL_BASE_URLhttps://taotoken.net/api CLAW_MODEL_API_KEYsk-your-taotoken-api-key CLAW_MODEL_IDgpt-4o-mini EOF把 CLAW_MODEL_API_KEY 换成你在控制台生成的真实 KeyCLAW_MODEL_ID 换成你要用的模型标识。Base URL 固定填 https://taotoken.net/api不要加末尾斜杠。如果你还想在 OpenClaw 里配置多个模型做路由可以在项目目录下再写一个 claw_config.yaml用 openai_compatible 类型接入model: primary: type: openai_compatible model: ${CLAW_MODEL_ID} endpoint: ${CLAW_MODEL_BASE_URL} api_key: ${CLAW_MODEL_API_KEY} parameters: temperature: 0.2 max_tokens: 4096 fallback: type: openai_compatible model: qwen2.5-7b-instruct endpoint: ${CLAW_MODEL_BASE_URL} api_key: ${CLAW_MODEL_API_KEY} parameters: temperature: 0.1 max_tokens: 1024 routing: - pattern: .*(分类|标签|提取).* model: fallback - default: primary这份配置里primary 和 fallback 都指向同一个 Base URL只是 Model ID 不同。路由规则按输入内容匹配分类类任务走轻量模型其他走主模型。这样既省 token 又保证效果。配置写好后启动服务docker compose up -d等大约 30 秒检查核心服务状态curl http://localhost:8080/api/v1/health期望输出类似{status:ok,version:1.2.0,services:{postgres:up,redis:up,chroma:up}}如果 postgres 显示 down先看日志docker compose logs postgres多半是密码或端口问题。如果 openclaw-core 起不来看docker compose logs openclaw-core常见的是环境变量没读到检查 .env 文件是否在 docker-compose.yml 同目录。到这里OpenClaw 和模型接入层都配好了。下一节我们验证 Agent 的工具调用链路是否真的打通。4. 验证请求用 curl 检查 Agent 工具调用链路是否打通配置写完不代表链路通了。很多人卡在「服务起来了但 Agent 调用工具时静默失败」这一步。这一节我用 curl 一步步验证从健康检查到模型连通性再到工具调用最后看完整对话。第一步确认 OpenClaw 核心服务健康curl -s http://localhost:8080/api/v1/health | jq .如果 jq 没装先sudo apt install jq -y。输出里 status 是 okservices 里 postgres、redis、chroma 都是 up说明基础组件没问题。第二步验证模型接入层是否连通。OpenClaw 提供了一个模型探测接口curl -s -X POST http://localhost:8080/api/v1/models/probe \ -H Content-Type: application/json \ -d {model_id:$CLAW_MODEL_ID} | jq .期望输出{model_id:gpt-4o-mini,reachable:true,latency_ms:312}如果 reachable 是 false先检查 .env 里的 CLAW_MODEL_BASE_URL 和 CLAW_MODEL_API_KEY 是否正确再确认服务器能不能访问外网。注意 Base URL 不要带末尾斜杠Key 不要有多余空格。第三步创建一个测试 Agent只挂一个简单的工具用来验证工具调用链路。先写 Agent 定义文件cat test_agent.json EOF { name: link_test_agent, description: 用于验证工具调用链路的测试 Agent, model: gpt-4o-mini, system_prompt: 你是一个测试助手。当用户询问时间时必须调用 get_current_time 工具获取不要自己编造。, tools: [ { name: get_current_time, type: builtin, config: { timezone: Asia/Shanghai } } ], memory: { type: conversation, max_turns: 5 } } EOF通过 API 部署这个 Agentcurl -s -X POST http://localhost:8080/api/v1/agents \ -H Content-Type: application/json \ -d test_agent.json | jq .期望返回{id:agent-link-test-001,name:link_test_agent,status:active}记下返回的 id下一步要用。第四步发起一次对话触发工具调用curl -s -X POST http://localhost:8080/api/v1/agents/agent-link-test-001/chat \ -H Content-Type: application/json \ -d {messages:[{role:user,content:现在几点了}]} | jq .期望输出里能看到工具调用记录和最终回答{ response: 现在是北京时间 2025-06-15 14:23:45。, trace_id: trace-link-abc123, tool_calls: [ { tool: get_current_time, status: success, latency_ms: 12 } ], usage: { prompt_tokens: 156, completion_tokens: 24, total_tokens: 180 } }关键看 tool_calls 数组里 status 是不是 success。如果是 success说明 Agent 的推理循环、工具调用、模型接入三层链路全部打通。如果 tool_calls 是空数组说明模型没有触发工具调用检查 system_prompt 里有没有明确指示使用工具。如果 status 是 error看 error 字段的具体信息。第五步用 trace_id 查完整调用链确认每一步的耗时和状态curl -s http://localhost:8080/api/v1/traces/trace-link-abc123 | jq .输出会展示从用户输入到模型推理、工具调用、结果回填、最终生成的完整链路。这一步在生产排障时非常有用能快速定位是模型慢、工具慢还是网络慢。到这里验证流程走完。如果你用的是本地 Ollama 模型把 .env 里的 CLAW_MODEL_BASE_URL 改成 http://host.docker.internal:11434/v1CLAW_MODEL_ID 改成 llama3.1:8b其他步骤一样。注意容器内访问宿主机服务要用 host.docker.internalLinux 上可能需要在 docker-compose 里加 extra_hosts 映射。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节对照真实报错给出排查路径。这些错误我在部署 OpenClaw 和接入模型时都遇到过按顺序排查基本能解决。报错一401 Unauthorized完整报错长这样{error:{code:invalid_api_key,message:Incorrect API key provided,type:invalid_request_error}}原因通常是 API Key 不对。排查步骤第一确认 .env 里的 CLAW_MODEL_API_KEY 没有多余空格或换行用cat -A .env | grep API_KEY看行尾有没有 ^M。第二确认 Key 没有过期或被撤销去控制台重新生成一个。第三确认 docker-compose 真的读到了 .env执行docker compose config | grep API_KEY看解析后的值。第四如果 Key 里有特殊字符用单引号包起来。报错二local proxy failed完整报错Error: local proxy failed: dial tcp 127.0.0.1:7890: connect: connection refused这个错误说明 OpenClaw 容器里配置了本地代理但代理服务没起来。排查第一检查 .env 或 docker-compose 里有没有 HTTP_PROXY、HTTPS_PROXY 环境变量有的话删掉。第二检查 OpenClaw 配置文件里有没有 proxy 字段注释掉。第三容器内访问宿主机服务应该用 host.docker.internal 或服务名不要用 127.0.0.1因为容器里的 127.0.0.1 指向容器自身。第四如果确实需要走网络代理确保代理服务在容器网络内可达并且地址填对。报错三reading choices完整报错Error: failed to parse model response: reading choices: unexpected end of JSON input这个错误说明模型返回的内容不是合法 JSONOpenClaw 解析失败。排查第一确认 Base URL 填的是 https://taotoken.net/api不要带 /v1 或末尾斜杠路径不对会导致返回 HTML 错误页。第二确认 Model ID 是接入层支持的模型标识填错模型名可能返回空响应。第三用 curl 直接打接入层接口看原始返回curl -s -X POST https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $CLAW_MODEL_API_KEY \ -H Content-Type: application/json \ -d {model:$CLAW_MODEL_ID,messages:[{role:user,content:hi}]} | head -c 500如果这里返回正常 JSON说明接入层没问题问题在 OpenClaw 的解析配置。如果这里也报错说明 Key 或 Model ID 有问题。第四检查 OpenClaw 版本1.2.0 之前对某些模型的响应格式兼容性不好升级到最新版。报错四OAuth 相关错误完整报错Error: oauth token exchange failed: invalid_grant这个错误通常出现在用 OAuth 方式接入模型时。排查第一确认你用的是 API Key 方式而不是 OAuthOpenClaw 的 openai_compatible 类型只需要 API Key。第二如果配置文件里残留了 oauth 字段删掉。第三检查系统时间是否准确OAuth token 对时间敏感时间偏差超过 5 分钟会失败用date确认。第四如果确实需要 OAuth确认回调地址配置正确且授权码没有重复使用。报错五工具调用超时完整报错Error: tool call timeout after 30000ms: get_current_time排查第一检查工具本身的实现如果是外部 API确认网络可达。第二调大超时时间在 Agent 定义的 tools 配置里加 timeout_ms 字段。第三如果是本地工具检查有没有死循环或阻塞操作。第四OpenClaw 1.3 版本支持异步工具调用长时间任务可以改成异步模式Agent 不会卡死。报错六向量检索返回空完整报错{response:根据现有知识库我无法回答这个问题。,tool_calls:[{tool:vector_search,status:success,results:0}]}工具调用成功但结果为空。排查第一确认索引真的建好了用curl http://localhost:8000/api/v1/collections看 Chroma 里的集合。第二确认 embedding 模型一致索引用什么模型查询也要用同一个。第三调低 min_score默认 0.6 可能太高改成 0.4 试试。第四确认查询语句和文档内容语义相关太短的查询可能匹配不到。排查完这些基本能覆盖 90% 的部署问题。如果还遇到其他报错先看docker compose logs openclaw-core的完整堆栈再对照 trace 里的每一步状态。6. 语义一致 CTA从验证到长期编码的接入路径链路验证通过后下一步就是把它用起来。根据你的场景有三条路径可以走。如果你还在排障和接入阶段需要反复查文档和生成 Key建议先去 API Keys 页面把 Key 管理好再去接入文档把 OpenClaw 的完整配置过一遍。文档里有针对不同模型和不同部署方式的详细说明比本文的片段更全。API Keys 地址是 https://taotoken.net/api-keys接入文档在 https://taotoken.net/doc。如果你想先验证模型效果不想马上写代码可以用模型对话页面直接测试。把 OpenClaw 里要用的 prompt 和工具描述贴进去看模型能不能正确触发工具调用、返回格式对不对。验证通过再落到 OpenClaw 配置里能省很多调试时间。模型对话入口是 https://taotoken.net/chat。如果你是长期做编码和 Agent 开发用量比较大建议了解 Coding Plan。它针对高频调用场景做了优化适合把 OpenClaw 作为日常开发基础设施的团队。Coding Plan 详情在 https://taotoken.net/coding-plan。如果你用 Claude Code 做开发想把 OpenClaw 和 Claude Code 的 Anthropic 兼容接口对接可以参考 ClaudeCodeAnthropic 的配置说明https://taotoken.net/claude-code-anthropic。控制台入口在 https://taotoken.net/console所有 Key 和用量都在这里管理。最后说一个实操经验OpenClaw 的配置文件建议进版本库但 .env 文件一定要加到 .gitignore。团队协作时每个人用自己的 Key配置文件共用。这样既保证配置一致又不会泄露密钥。模型切换时只改 .env 里的 CLAW_MODEL_ID重启 openclaw-core 容器即可生效工具代码一行不用动。这就是统一接入层带来的实际收益。
阅读完成 · 觉得有帮助？
