企业官网建设流程全解析

1. OpenHands 是什么，为什么要在 Docker 里配 TaoToken

OpenHands 是一款开源 AI 编程工具，核心能力是让开发者用自然语言描述需求，由 AI 代理在隔离沙箱里读写文件、执行命令、跑测试，最终把代码改动落到工作区。它适合三类人：想用自然语言驱动开发流程的独立开发者、需要批量处理 Issue 的团队、以及想研究 AI Agent 执行链路的工程师。OpenHands 在 SWE-bench 这类真实仓库任务评测里表现靠前，说明它不是只会聊天的玩具，而是能真正改代码的执行体。

但 OpenHands 本身不带模型，它需要一个 LLM 提供商来驱动推理。默认配置里你要么填官方 API，要么自己接一个兼容 OpenAI 协议的服务。问题就出在这里：很多人在 Docker 里跑起来后，卡在“模型选哪个、Key 填哪里、Base URL 怎么写”这三步上，界面报错又不够直白，来回折腾半小时还没跑通第一条自然语言指令。

这篇就聚焦 Docker 环境下的接入配置，交付一份可复制的 config.toml 骨架，把统一 Key 和 API 通道配好，再给出启动验证和常见报错排查动作。你跟着做，能快速跑通“用中文描述需求 → OpenHands 自动改代码”的完整流程。TaoToken 在这里的角色是提供一个兼容 OpenAI 协议的统一入口，省去你分别对接多家模型的麻烦。

2. 前置准备：TaoToken Key 与 OpenHands 运行环境

在动手改配置之前，先把两样东西准备好：一个可用的 API Key，以及能跑 Docker 的机器。

2.1 获取 TaoToken API Key

打开 TaoToken 控制台，进入 API Keys 页面创建一个新 Key。建议按项目命名，比如openhands-dev，方便后续区分。创建后立刻复制保存，页面刷新后就不再完整显示。

注意：Key 只显示一次，丢了只能重建。不要把它写进会提交到 Git 的配置文件里，用环境变量或本地.env承载。

拿到 Key 后，记下两个地址：API 基础地址是https://taotoken.net/api，模型对话入口在控制台的模型对话页，接入文档在文档页。这两个页面后面排查问题时会用到。

2.2 确认 Docker 与端口

OpenHands 官方推荐用 Docker 运行，因为它需要在容器里再起一个沙箱运行时。确认你的 Docker 版本不要太旧：

docker --version docker info | grep -i "server version"

如果docker info报权限错误，把当前用户加入 docker 组，或者命令前加sudo。端口方面，OpenHands 默认用 3000，确认没有被占用：

lsof -i :3000

有输出就说明被占了，换一个端口，比如 3001，后面启动命令里对应改掉。

3. 可复制的 config.toml 骨架与统一 Key 配置

OpenHands 的模型配置可以走界面填，也可以走配置文件。界面填适合快速试，配置文件适合反复重建容器时保持一致。下面这份config.toml骨架你可以直接抄，改掉 Key 和模型名即可。

3.1 config.toml 完整骨架

在宿主机建一个配置目录，比如~/openhands-config，把配置写进去：

[core] workspace_base = "/workspace" cache_dir = "/tmp/cache" max_iterations = 50 runtime = "docker" [llm] model = "gpt-4o" api_key = "sk-你的TaoTokenKey" base_url = "https://taotoken.net/api" temperature = 0.2 max_output_tokens = 4096 [llm.custom] provider = "openai" api_version = "2024-02-01" [sandbox] timeout = 120 use_host_network = false

几个关键点解释一下。base_url指向 TaoToken 的 API 地址，OpenHands 会按 OpenAI 兼容协议发请求。model填你要用的模型名，具体支持哪些可以在模型对话页确认。temperature建议 0.2 左右，编程任务不需要太发散。max_iterations控制代理最多迭代多少轮，太小任务做不完，太大容易空转烧额度。

3.2 用环境变量注入 Key

把 Key 写死在 toml 里不安全，改成从环境变量读：

[llm] model = "gpt-4o" api_key = "${TAOTOKEN_API_KEY}" base_url = "https://taotoken.net/api"

然后启动容器时把环境变量传进去。这样配置文件可以进版本库，Key 留在本地。

3.3 启动容器并挂载配置

把配置目录挂载到容器里，同时把 Docker socket 挂进去，让 OpenHands 能起沙箱：

docker run -it --rm --pull=always \ -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.13-nikolaik \ -e TAOTOKEN_API_KEY=sk-你的TaoTokenKey \ -e LOG_ALL_EVENTS=true \ -v /var/run/docker.sock:/var/run/docker.sock \ -v ~/openhands-config:/openhands-config \ -p 3000:3000 \ --add-host host.docker.internal:host-gateway \ --name openhands-app \ docker.all-hands.dev/all-hands-ai/openhands:0.13

启动后浏览器打开http://localhost:3000，进入设置页确认模型和 Base URL 已经按配置加载。如果界面里显示的还是默认值，说明配置文件路径没被识别，检查挂载路径和 OpenHands 读取配置的环境变量。

4. 验证请求：发一条自然语言指令看结果

配置对不对，发一条指令就知道。在 OpenHands 聊天窗口输入一个具体的小任务，比如：

在当前工作区创建一个 hello.py，里面写一个函数 greet(name)， 返回 "Hello, {name}"，然后写一个 pytest 测试文件 test_hello.py 验证它。

发送后观察三件事。第一，界面是否开始流式输出思考过程，说明模型请求通了。第二，工作区面板是否出现新建的文件，说明沙箱执行通了。第三，终端日志里有没有POST /api/... 200这类记录，说明 API 通道正常。

如果一切正常，你会看到 OpenHands 自动创建两个文件，并尝试运行 pytest。运行结果会回显在对话里。这时候你可以继续追问“把 greet 改成支持多个名字”，看它能不能在已有文件上做增量修改。

想单独验证 API 通道是否可用，可以绕过 OpenHands 直接打一次请求：

curl https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-你的TaoTokenKey" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o", "messages": [{"role": "user", "content": "回复 ok"}] }'

返回里有choices字段就说明 Key 和地址都没问题。这一步能帮你快速区分是 OpenHands 配置问题还是 Key 本身的问题。

5. 本篇常见报错排查

跑不通的时候，大部分错误集中在下面几类。按顺序排查，基本能定位。

5.1 401 Unauthorized

最常见。原因通常是 Key 没传进容器，或者传了但名字对不上。检查启动命令里的-e TAOTOKEN_API_KEY=...和 toml 里的${TAOTOKEN_API_KEY}是否一致。如果 Key 里有特殊字符，用单引号包住。还有一种情况是 Key 被复制时带了空格，重新复制一次。

5.2 Connection refused 或超时

容器内访问外部 API 失败。先确认容器能出网：

docker exec -it openhands-app curl -I https://taotoken.net/api

如果这条不通，说明是容器网络问题，检查宿主机的网络设置。如果这条通但 OpenHands 还是超时，检查 toml 里的base_url有没有多写或少写/v1。TaoToken 的基础地址是https://taotoken.net/api，OpenHands 会自己拼路径，不要手动加/v1。

5.3 模型不存在或 model not found

model字段填的模型名不在可用列表里。去模型对话页确认当前 Key 能访问哪些模型，把名字原样抄过来。注意大小写和连字符，gpt-4o和gpt4o是两个东西。

5.4 沙箱起不来，报 Docker socket 错误

启动命令里-v /var/run/docker.sock:/var/run/docker.sock没加，或者宿主机 Docker 版本太旧不支持。确认 socket 文件存在：

ls -l /var/run/docker.sock

如果权限不对，容器里的进程读不到，加--group-add把 docker 组传进去，或者临时用sudo启动容器验证。

5.5 界面能开但发消息没反应

看容器日志：

docker logs -f openhands-app

如果日志里一直刷重试，多半是 API 请求被限流或 Key 额度不足。去控制台看用量。如果日志里报 JSON 解析错误，检查 toml 格式，特别是引号和括号有没有配对。

6. 长期使用建议与入口

跑通之后，如果你打算把 OpenHands 当成日常编码助手，建议做两件事。一是把配置目录纳入版本管理，Key 用环境变量注入，换机器时直接复用。二是控制max_iterations和max_output_tokens，避免一个模糊指令让代理空转太多轮。

对于需要长期跑编码任务或 Agent 流程的场景，可以了解 Coding Plan，它更适合持续性的开发工作负载。日常调试模型行为、确认某个模型是否适合你的任务，用模型对话页快速试。需要管理多个 Key 或查看用量，进控制台。接入细节和参数说明都在接入文档里，遇到协议层面的问题先查那里。

OpenHands 的自然语言编程体验，核心在于模型通道稳定。把 TaoToken 的 Key 和 Base URL 配好，剩下的就是描述清楚你的需求，让代理去执行。