企业官网建设流程全解析

1. 本地 Docker 部署 OpenHands 到底解决什么问题

OpenHands（原名 OpenDevin）是一个基于人工智能的软件开发代理平台，它能像真人开发者一样修改代码、执行命令行、浏览网页、调用 API。你给它一句自然语言需求，它会在隔离的沙箱容器里真正动手写文件、跑脚本、装依赖，而不是只吐一段代码让你自己复制。适合谁用？三类人最明显：一是想体验 AI Agent 自动完成多步开发任务的后端/全栈工程师；二是需要把代理跑在隔离环境、不想让它污染本机文件系统的谨慎派；三是希望从外部网络随时访问自己这台开发机的远程办公者。

问题也很直接。官方推荐的启动方式是一条很长的docker run命令，参数多、镜像 tag 容易写错，而且默认只监听本机 3000 端口，出了局域网就访问不到。更麻烦的是 OpenHands 自己还要在容器里再拉起一个 runtime 沙箱容器，所以必须把宿主机的 Docker socket 挂进去，这一步配置错了就会报「无法连接 runtime」之类的错。我试过把这套流程整理成可复制的 Compose 配置，再配合一个稳定的模型接入点，整个链路就顺了。

这篇就按「本地部署 → 模型接入 → 远程访问 → 排障」的顺序走一遍，命令和配置都能直接抄。模型这一环我用的是 TaoToken 的兼容接口，它提供 OpenAI 兼容的 Base URL，OpenHands 在设置里填自定义模型时正好用得上，省得为每个模型单独折腾 SDK。

2. 部署前的前置准备：Docker、目录与 TaoToken 接入点

先说环境。演示用 Ubuntu 22.04，Docker 24+ 和 Docker Compose v2 是硬性要求，因为 OpenHands 依赖 Docker socket 来创建沙箱。检查一下：

docker --version docker compose version

如果 Docker 还没装，用官方脚本装完记得把当前用户加进 docker 组，否则每次都要 sudo：

sudo usermod -aG docker $USER newgrp docker

然后是模型接入。OpenHands 本身不带模型，它需要你提供一个 LLM 提供商的 API Key 和 Base URL。TaoToken 的 API 地址是https://taotoken.net/api，兼容 OpenAI 的/v1/chat/completions协议，所以在 OpenHands 里选「Custom」或 OpenAI 兼容模式，把 Base URL 填成这个地址即可。先去控制台创建一个 API Key：

提示：API Key 只在创建时完整显示一次，复制后立刻存到密码管理器或.env文件里，别直接写进会提交到 Git 的配置。

创建 Key 的入口在控制台的 API Keys 页面，模型对话入口可以用来先验证 Key 是否可用。这两个地址分别是：

• API Keys 管理：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=openhands_docker
• 模型对话验证：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=openhands_docker

拿到 Key 之后，建议在服务器上建一个独立目录放配置，别把 Key 散落在命令行历史里：

mkdir -p ~/openhands && cd ~/openhands touch .env chmod 600 .env

.env里先写两行，后面 Compose 会引用：

LLM_API_KEY=sk-你的TaoToken密钥 LLM_BASE_URL=https://taotoken.net/api

这样做的意义是：命令行里不出现明文 Key，docker compose会自动读取.env，容器重启也不用重新输入。

3. 可复制的 Docker Compose 配置与启动步骤

官方那条docker run命令拆成 Compose 会清晰很多。在~/openhands下新建docker-compose.yml：

services: openhands: image: docker.all-hands.dev/all-hands-ai/openhands:0.14 container_name: openhands-app pull_policy: always ports: - "3000:3000" environment: - SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.14-nikolaik - LOG_ALL_EVENTS=true - LLM_API_KEY=${LLM_API_KEY} - LLM_BASE_URL=${LLM_BASE_URL} volumes: - /var/run/docker.sock:/var/run/docker.sock - ~/.openhands:/.openhands extra_hosts: - "host.docker.internal:host-gateway" restart: unless-stopped

几个参数值得单独说清楚，配错了就是各种玄学报错：

先拉镜像再启动，避免启动时卡在拉取：

docker compose pull docker compose up -d

看日志确认没有报错：

docker compose logs -f openhands

日志里出现类似Uvicorn running on http://0.0.0.0:3000就说明服务起来了。这时候浏览器打开http://localhost:3000，首次会弹设置窗口，让你选 LLM 提供商、模型和 API Key。

在设置里这样填：提供商选 OpenAI 兼容或 Custom，Base URL 填https://taotoken.net/api，API Key 填你的 TaoToken 密钥，模型名按你实际要用的填。保存后配置会写进~/.openhands，下次重启不用重填。如果要用自定义模型，展开高级选项手动输入模型名称和 Base URL 即可。

4. 验证请求：从 hello.sh 到生成一个计算器

配置保存后别急着上复杂任务，先用最小例子验证整条链路通不通。在对话框输入：

请编写一个 bash 脚本 hello.sh，打印 "hello world!"

正常情况下左侧显示你的提示词，右侧 OpenHands 会规划步骤、创建文件、执行脚本，最后把输出贴回来。这一步能跑通，说明模型接入、沙箱创建、命令执行三个环节都正常。

再验证一个多文件任务，输入：

用 HTML + JavaScript 创建一个简单的计算器，支持加减乘除

它会生成index.html等文件，然后你让它运行：

启动这个项目并给我访问链接

OpenHands 会在沙箱里起一个静态服务器，把链接输出到对话框。你可以用 VSCode 打开生成的文件本地跑一遍，确认计算器逻辑正确。不满意就继续在对话框里追加需求，它会基于当前工作区迭代修改。

这一步如果卡住，八成是模型返回格式不对或沙箱没起来。先看docker compose logs里有没有 runtime 相关报错，再确认 Base URL 末尾没有多余的/v1（TaoToken 的地址填到/api即可，具体路径以文档为准）。接入文档里有完整的参数说明：

• 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=openhands_docker

5. 远程访问配置与常见错误排查

本地跑通后，远程访问是下一个需求。默认 OpenHands 只监听本机，外部网络访问不到。这里有两种思路：一是把服务绑到0.0.0.0并通过防火墙/安全组放行端口，适合有公网 IP 的云主机；二是用内网穿透把本地端口映射出去，适合家里或公司内网的机器。

第一种方式改 Compose 的端口映射即可，ports已经是3000:3000，容器内监听0.0.0.0，所以宿主机层面能访问。云主机上确认安全组放行了 3000 端口，然后直接用http://公网IP:3000访问。注意这种方式没有 HTTPS，生产环境建议前面挂一层 Nginx 做 TLS 终止。

第二种方式用内网穿透工具，把本地 3000 端口映射成一个公网地址。配置时协议选 HTTP，本地地址填 3000，创建后拿到公网 URL，在任意设备浏览器打开就能看到 OpenHands 界面，重新配置模型即可使用。随机域名会定期变化，长期用建议保留一个固定二级子域名，把隧道改成固定地址，这样远程访问的 URL 就不会变。

排障清单，按出现频率排序：

报错一：Cannot connect to the Docker daemon容器内访问不到 Docker socket。检查/var/run/docker.sock是否挂载，宿主机 Docker 服务是否运行，以及当前用户是否有权限。

报错二：Failed to create sandbox或 runtime 超时多半是SANDBOX_RUNTIME_CONTAINER_IMAGE的 tag 和主镜像不匹配，或者宿主机磁盘空间不足拉不下 runtime 镜像。用docker images确认两个镜像都在。

报错三：模型返回 401 或 404API Key 错了或 Base URL 填错。先用模型对话入口单独验证 Key，再回来检查 OpenHands 设置里的地址。注意别把/api和/v1混着拼。

报错四：重启后模型配置丢失~/.openhands没挂载成卷。补上 volumes 里的那行，重建容器。

报错五：远程访问白屏或连接被拒端口没放行，或内网穿透隧道没启动。先在宿主机curl localhost:3000确认服务活着，再排查网络层。

6. 长期编码与 Agent 场景的接入建议

如果你只是偶尔跑几个任务，按上面的流程就够了。但如果打算把 OpenHands 当成日常编码代理长期用，比如让它持续处理仓库里的 issue、自动重构、跑测试，那模型调用的稳定性和成本就变成主要矛盾。这时候建议单独规划一下接入方式，Coding Plan 这类面向长期编码和 Agent 场景的方案会更合适，额度和调用策略都是按持续使用设计的：

• Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=openhands_docker

另外几个实操经验：把~/.openhands定期备份，里面存着会话历史和设置；沙箱容器会占磁盘，跑久了用docker system prune清理无用镜像和容器；如果 OpenHands 要访问私有仓库，记得在沙箱里配好凭证，别把 token 硬编码进提示词。Claude Code 这类命令行代理和 OpenHands 可以配合用，前者适合终端里的快速改动，后者适合需要浏览器和沙箱的复杂任务，接入方式在文档里有说明。

整套流程走下来，核心就三件事：Compose 把参数固化、TaoToken 提供稳定的模型接入点、远程访问解决随时随地可用。配置一次，后面就是提需求等结果了。