1. OpenHands 是什么为什么要在 Docker 里配 TaoTokenOpenHands 是一款开源 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 --pullalways \ -e SANDBOX_RUNTIME_CONTAINER_IMAGEdocker.all-hands.dev/all-hands-ai/runtime:0.13-nikolaik \ -e TAOTOKEN_API_KEYsk-你的TaoTokenKey \ -e LOG_ALL_EVENTStrue \ -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/apiOpenHands 会自己拼路径不要手动加/v1。5.3 模型不存在或 model not foundmodel字段填的模型名不在可用列表里。去模型对话页确认当前 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 配好剩下的就是描述清楚你的需求让代理去执行。
OpenHands 配 TaoToken：开源AI编程工具的自然语言编程配置指南
1. OpenHands 是什么为什么要在 Docker 里配 TaoTokenOpenHands 是一款开源 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 --pullalways \ -e SANDBOX_RUNTIME_CONTAINER_IMAGEdocker.all-hands.dev/all-hands-ai/runtime:0.13-nikolaik \ -e TAOTOKEN_API_KEYsk-你的TaoTokenKey \ -e LOG_ALL_EVENTStrue \ -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/apiOpenHands 会自己拼路径不要手动加/v1。5.3 模型不存在或 model not foundmodel字段填的模型名不在可用列表里。去模型对话页确认当前 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 配好剩下的就是描述清楚你的需求让代理去执行。
