1. Linux 下 Docker 部署 OpenClaw 到底解决什么问题OpenClaw 是一个把 ClaudeCode 这类编码 Agent 包装成常驻服务的开源项目社区里习惯叫它“龙虾”。它本身不产出模型能力而是负责会话管理、工具调用、渠道接入飞书、Web 仪表盘等再把请求转发给底层的 Agent 运行时。ClaudeCode 是 Anthropic 官方的命令行编码工具能力很强但默认是“一次性交互”的形态你关掉终端它就停了。把两者接起来就能得到一个随时在线、能记住上下文、还能从聊天窗口直接派活的编码助手。apcx 是 ACPAgent Client Protocol协议的客户端工具OpenClaw 通过它来拉起并驱动 ClaudeCode。整条链路是你在飞书或仪表盘发指令 → OpenClaw Gateway 接收 → 通过 acpx 调用 claude-agent-acp → 后者驱动本机已登录的 ClaudeCode 执行任务 → 结果回传。所以这套方案适合三类人想让 ClaudeCode 7×24 待命的后端/运维同学、想把编码 Agent 接进团队 IM 的协作场景、以及想在自己 Linux 服务器上搭一套私有 Agent 网关的折腾党。我实测下来最容易卡住的不是 OpenClaw 本身而是容器里没有 ClaudeCode 的登录态、acpx 找不到 claude-agent-acp 的可执行路径、以及权限模式没放开导致写入被拦。这篇就按“宿主机准备 → 容器构建 → 配置初始化 → 验证调用 → 排错”的顺序把每一步的可复制命令都给你跟着敲基本能一次跑通。需要说明的是ClaudeCode 的模型调用需要一个稳定的 API 入口。如果你本机已经登录了官方账号可以直接复用如果想让 OpenClaw 走统一的网关来管理密钥和额度可以在配置阶段把 Base URL 指向 TaoToken 的 API 地址后面第 3 节会给到具体写法。2. 部署前的宿主机准备与 acpx 安装这一节的目标是让宿主机具备两样东西一个已经登录可用的 ClaudeCode以及全局可执行的 acpx 和 claude-agent-acp。容器会通过 volume 把宿主机的配置目录挂进去所以宿主机这步不能省。先确认 Node 环境。acpx 和 claude-agent-acp 都是 npm 包建议 Node 18 以上node -v npm -v如果版本太低用 nvm 装一个 LTS 版本即可。接着安装 ClaudeCode 本体并完成登录npm install -g anthropic-ai/claude-code claude第一次运行claude会引导你完成认证登录成功后会在~/.claude下生成配置和凭据文件。这个目录后面要挂进容器所以务必确认它存在ls -la ~/.claude然后安装 ACP 相关的两个核心工具。国内网络直接拉 npm 官方源容易超时用 npmmirror 镜像会快很多npm install -g zed-industries/claude-agent-acp --registryhttps://registry.npmmirror.com npm install -g acpxlatest装完后验证一下可执行文件的位置这个路径后面写进 acpx 配置要用which claude-agent-acp which acpx正常会输出类似/usr/local/bin/claude-agent-acp。如果你的输出是/usr/bin/...或 nvm 路径记下来配置里要改成实际路径否则容器内会报 command not found。初始化 acpx 配置它会生成默认的 config.jsonacpx config init默认配置在~/.acpx/config.json。我们要覆盖它把 claude 这个 agent 的命令指向刚才确认的路径并把权限模式设为自动批准否则 OpenClaw 派发的写入类操作会被逐个拦截cat ~/.acpx/config.json EOF { agents: { claude: { command: /usr/local/bin/claude-agent-acp } }, config: { permissionMode: approve-all } } EOF注意approve-all意味着 ACP 请求不再逐条询问。这套配置适合本地或内网可信环境公网暴露的机器请谨慎最好配合访问白名单。到这里宿主机侧就绪。你可以先用acpx单独跑一次确认它能拉起 claude-agent-acp避免问题被带进容器里排查。3. 可复制的 Docker 配置与 OpenClaw 初始化这一节是全文的核心包含 Dockerfile.custom、docker-compose.yml 的改动、.env 环境变量以及 OpenClaw 的 onboard 初始化。所有片段都可以直接复制。先准备 OpenClaw 的源码目录。假设你放在/home/hyn/clawLatest/openclaw进入该目录后创建.envcat .env EOF OPENCLAW_CONFIG_DIR/home/hyn/clawLatest/openclaw/.openclaw OPENCLAW_WORKSPACE_DIR/home/hyn/clawLatest/openclaw/.openclaw/workspace OPENCLAW_GATEWAY_TOKEN你的随机token OPENCLAW_GATEWAY_PORT18789 OPENCLAW_BRIDGE_PORT18790 OPENCLAW_GATEWAY_BINDlan OPENCLAW_TZAsia/Shanghai CLAUDE_AI_SESSION_KEY CLAUDE_WEB_SESSION_KEY CLAUDE_WEB_COOKIE OPENCLAW_ALLOW_INSECURE_PRIVATE_WS EOF生成一个 32 字节的随机 Token 并替换进去别用弱口令export RANDOM_TOKEN$(openssl rand -hex 32) echo 你的安全 Token$RANDOM_TOKEN sed -i s/OPENCLAW_GATEWAY_TOKEN你的随机token/OPENCLAW_GATEWAY_TOKEN$RANDOM_TOKEN/ .env cat .env接着创建自定义 Dockerfile基于官方镜像补装 acpx 和 claude-agent-acpFROM ghcr.io/openclaw/openclaw:latest USER root RUN npm install -g zed-industries/claude-agent-acp --registryhttps://registry.npmmirror.com RUN npm install -g acpx USER node CMD [/docker-entrypoint.sh]然后改docker-compose.yml指定用自定义 Dockerfile并把宿主机的 Claude 和 acpx 配置挂进容器。两个数据卷都要加services: openclaw-gateway: build: context: . dockerfile: Dockerfile.custom volumes: - /home/hyn/.claude:/home/node/.claude - /home/hyn/.acpx:/home/node/.acpx注意宿主机必须先完成 ClaudeCode 登录否则容器内/home/node/.claude是空的ClaudeCode 无法认证。配置就绪后跑一次初始化向导。用--rm --no-deps起一个临时容器手动模式、不装守护进程docker compose run --rm --no-deps --entrypoint node openclaw-gateway dist/index.js onboard --mode local --no-install-daemon向导里几个关键选择安全提示选 Yes安装模式选 Manual工作区目录回车用默认模型提供商这里我选的是本地 Ollama你按实际填 Base URL 和模型名Gateway 端口 18789、绑定 LAN、认证方式 TokenToken 填.env里生成的那个Tailscale 暴露选 Off聊天渠道可以选飞书也可以先跳过搜索提供商选 DuckDuckGo技能依赖先 Skip各类 API Key 都选 NoHooks 勾选 boot-md、bootstrap-extra-files、command-logger、session-memory 这四个核心项zsh 补全按你的 shell 选。初始化完成后启动docker compose up -d --build首次构建会拉镜像装依赖慢一点正常。起来后用docker compose ps确认容器状态是 Up。4. 验证请求从仪表盘到 ClaudeCode 联动容器跑起来不代表链路通了这一节用几条命令把 OpenClaw 到 ClaudeCode 的调用验证一遍。先进容器docker exec -it 容器名称 bash生成仪表盘链接不自动打开浏览器openclaw dashboard --no-open它会输出一个带 Token 的 URL复制到浏览器打开。首次访问会提示设备未批准回到容器里查看并批准openclaw devices list openclaw devices approve ${DEVICE_ID}批准后刷新页面就能进仪表盘。接下来是关键的 ACP 配置。编辑~/.openclaw/openclaw.json加上 acp 段{ acp: { enabled: true, backend: acpx, defaultAgent: claude, allowedAgents: [claude] } }同时在.claude/settings.json里放开权限否则 OpenClaw 通过 acpx 写入时会被拦{ permissions: { defaultMode: bypassPermissions } }改完重启容器让配置生效docker compose restart然后在仪表盘的对话窗口里发一条测试指令比如“列出当前工作区目录下的文件”。如果配置正确你会看到 OpenClaw 把请求转给 acpxacpx 拉起 claude-agent-acpClaudeCode 执行后把结果回传。整个过程在~/.openclaw/logs/audit/commands.log里有审计记录出问题时先看这个日志。如果你希望 OpenClaw 走统一的 API 网关来管理模型调用可以在模型提供商配置里把 Base URL 指向https://taotoken.net/apiKey 用你在控制台生成的密钥模型 ID 按需选择。这样密钥集中管理换模型也不用改容器。5. 常见报错排查401、local proxy failed 与路径问题这一节把几个高频报错和对应处理列出来都是我在实际部署里踩过的。401 Unauthorized多半是 Gateway Token 不匹配。检查.env里的OPENCLAW_GATEWAY_TOKEN和仪表盘 URL 里带的 Token 是否一致以及 onboard 时填的是不是同一个。改完.env要docker compose up -d重建光 restart 不会重读环境变量。local proxy failed / connection refused通常是 acpx 在容器内找不到 claude-agent-acp。进容器执行which claude-agent-acp如果为空说明 Dockerfile 里那步 npm 安装没成功或者~/.acpx/config.json里的 command 路径写错了。容器内路径是/usr/local/bin/claude-agent-acp宿主机路径可能不同配置要以容器内为准。reading choices 相关报错一般是 ClaudeCode 没有登录态。确认宿主机~/.claude里有凭据文件且 volume 映射路径是/home/node/.claude。容器内用户是 node权限不对也会读不到必要时chown -R 1000:1000 ~/.claude。OAuth / 认证失败如果 ClaudeCode 用的是 OAuth 登录容器内可能因为缺少浏览器回调而失败。这种情况建议在宿主机完成登录后再挂载或者改用 API Key 方式认证。权限被拒 / 写入失败检查.claude/settings.json的defaultMode是否为bypassPermissions以及 acpx 配置里的permissionMode是否为approve-all。两处都要放开。排查顺序建议先看docker compose logs -f的容器日志再看~/.openclaw/logs/audit/commands.log的审计日志最后进容器手动跑acpx确认底层工具本身可用。这样能快速定位是 OpenClaw 层、acpx 层还是 ClaudeCode 层的问题。6. 把链路用起来密钥管理与长期运行建议链路跑通之后有几件事值得提前做好能省掉后面很多麻烦。密钥管理上Gateway Token 用openssl rand -hex 32生成别图省事用简单字符串。如果你把 OpenClaw 暴露在内网多台机器访问建议在反向代理层再加一层认证。模型调用的 Key 如果分散在多个容器里后期轮换会很痛苦统一走一个 API 网关比如把 Base URL 指向https://taotoken.net/api会清爽很多密钥在控制台一处管理容器里只留引用。长期运行方面docker compose up -d之后容器默认会随 Docker 重启但建议加restart: unless-stopped策略避免宿主机重启后服务没起来。日志会持续增长command-logger写的审计日志和 session-memory 的会话 JSON 都要定期清理或轮转否则磁盘会被慢慢吃满。如果你打算把 OpenClaw 接进飞书做团队协作群聊策略建议用 Allowlist 白名单模式只响应指定群避免机器人被拉进无关群后乱回。DM 策略用 Pairing 配对模式安全性更好。最后ClaudeCode 的版本更新比较频繁acpx 和 claude-agent-acp 也建议定期升级。升级后记得重新验证一次链路因为协议细节偶尔会有变动。把这套配置固化成脚本或 compose 文件提交到自己的仓库下次换机器部署就是几分钟的事。