1. 本地跑通 OpenHands 后模型通道到底卡在哪OpenHands 是一个把「大模型决策 工具执行」放进循环里的 AI Agent 框架它能读写文件、跑 bash、执行 Python靠的是每一轮把当前状态喂给 LLM再拿回下一步动作。适合谁适合已经在本地把 OpenHands 拉起来、能打开界面、但一让它干活就报模型调用失败或一直转圈的开发者。我见过太多人卡在同一个地方容器起来了Web 界面能开任务一提交就提示鉴权失败、base_url 不通、或者模型名对不上。问题根源在于 OpenHands 的模型适配层是分层的。它用 LiteLLM 做统一封装上层是 LLM 类和 LLMRegistry配置则来自 config.toml 和运行时注入的 settings。你如果只改了环境变量却没同步 config.toml或者把 key 写进了错误的 sectionAgent 的 step() 拿不到可用的 LLM 实例整个循环第一步就断了。这篇就聚焦「配置文件 统一 Key/API 通道」这条线给你一份能直接复制的 config.toml 骨架再走一遍从启动到验证 Agent 真正调用通道的闭环。核心检索词先摆出来OpenHands 怎么配置模型、Agent 的 LLM 通道怎么接、config.toml 怎么写、settings.json 放哪、启动后怎么确认 Agent 真的调通了。2. 接入前的准备TaoToken 通道与 Key 的定位在动配置文件之前先把「通道」这件事想清楚。OpenHands 的 LLM 类最终是通过 LiteLLM 发起请求的它认的是标准 OpenAI 兼容接口一个 base_url、一个 api_key、一个 model 名。所以你要做的不是改 OpenHands 源码而是给它一个能稳定响应 OpenAI 格式的入口。TaoToken 在这里扮演的就是这个统一入口。官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 根地址是 https://taotoken.net/api 。注意这个 /api 结尾LiteLLM 拼接路径时会自动补 /v1/chat/completions所以 base_url 填到 /api 这一层就行别自己再加 /v1否则会变成 /api/v1/v1/... 这种重复路径这是最常见的 404 来源。Key 的获取走控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 进去后在 API Keys 页面创建页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建出来的 key 一般以固定前缀开头复制后先存到本地环境变量里别直接硬编码进 config.toml 提交到 git。注意OpenHands 的配置里 api_key 字段支持从环境变量读取推荐用api_key env:TAOTOKEN_API_KEY这种写法避免明文泄露。模型名这块要留意。TaoToken 的模型对话页在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 你可以先在那里确认当前可用的模型标识比如常见的 claude 系列、gpt 系列命名。OpenHands 的 config.toml 里 model 字段要填 LiteLLM 能识别的名字如果走的是自定义 provider通常需要加前缀比如openai/你的模型名配合 custom_llm_provider 指定。这一步填错表现就是启动时报 model not found。3. 可复制的 config.toml 骨架OpenHands 的配置读取优先级大致是命令行参数 环境变量 config.toml 默认值。我们这里以 config.toml 为主环境变量兜底 key。下面这份骨架你可以直接改。[core] # 工作目录容器内路径按你实际挂载调整 workspace_base ./workspace # 缓存目录 cache_dir ./cache # 运行模式本地用 local 或 docker runtime docker # 最大迭代次数防止 Agent 无限循环烧 token max_iterations 50 [llm] # 模型标识按 TaoToken 模型页确认后填写 model openai/claude-sonnet-4 # 统一通道入口注意结尾是 /api base_url https://taotoken.net/api # 从环境变量读取避免明文 api_key env:TAOTOKEN_API_KEY # 自定义 provider走 OpenAI 兼容协议 custom_llm_provider openai # 温度Agent 任务建议低一点减少乱跑 temperature 0.2 # 单次最大输出 token max_output_tokens 8192 # 超时Agent 多轮调用别设太短 timeout 300 # 失败重试次数 num_retries 3 # 重试等待区间 retry_min_wait 2 retry_max_wait 10 retry_multiplier 2 # 允许 LiteLLM 丢弃模型不支持的参数兼容性关键 drop_params true [agent] # 默认 Agent 类型代码任务用 CodeActAgent default_agent CodeActAgent # 是否开启确认模式调试期可开 enable_auto_lint true [sandbox] # 沙箱超时 timeout 120 # 是否使用宿主网络按需 use_host_network false几个字段单独说清楚。custom_llm_provider openai是让 LiteLLM 按 OpenAI 协议发请求TaoToken 的 /api 入口就是 OpenAI 兼容的所以这里必须对上。drop_params true很重要因为不同模型对 temperature、top_p 的支持不一样LiteLLM 会自动丢掉不支持的参数否则会直接报 400。model字段如果你不确定前缀可以先在模型对话页发一条测试消息确认模型标识的准确写法。如果你更习惯用 settings.json 做运行时覆盖OpenHands 也支持。settings.json 一般放在工作目录或通过挂载注入结构类似{ llm: { model: openai/claude-sonnet-4, base_url: https://taotoken.net/api, api_key: env:TAOTOKEN_API_KEY, custom_llm_provider: openai, temperature: 0.2, drop_params: true }, agent: { default_agent: CodeActAgent } }settings.json 的优先级高于 config.toml适合你在不改主配置的情况下临时切换模型。但要注意如果两边都写了 llm 段settings.json 会覆盖排查问题时先确认到底哪份生效了。4. 启动与验证确认 Agent 真的调通了通道配置写完先设环境变量再启动。Linux/macOS 下export TAOTOKEN_API_KEY你的keyWindows PowerShell$env:TAOTOKEN_API_KEY你的key然后启动 OpenHands。如果你用的是官方 docker 方式大致是docker run -it --rm \ -e TAOTOKEN_API_KEY$TAOTOKEN_API_KEY \ -v $(pwd)/config.toml:/app/config.toml \ -v $(pwd)/workspace:/app/workspace \ -p 3000:3000 \ openhands:latest启动日志里重点看两行一行是 LLM 初始化时打印的 model 和 base_url确认没有拼错另一行是 Agent 注册时打印的 default_agent。如果这两行正常说明配置被读进去了。接下来做真正的验证。打开 Web 界面提交一个最小任务比如「在当前目录创建一个 hello.txt内容写 hello agent」。观察后端日志你应该能看到类似这样的调用记录LLM: model has vision enabled LLM: model supports function calling POST https://taotoken.net/api/v1/chat/completions如果看到 POST 请求打到了 /api/v1/chat/completions并且返回 200说明通道通了。Agent 会进入 step 循环生成 Action写文件→ 执行 → 拿 Observation → 再决策。任务完成后界面会显示 AgentFinishAction。想更直接地验证通道本身可以绕过 OpenHands用 curl 单独打一发curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4, messages: [{role: user, content: reply with ok}], max_tokens: 16 }返回里如果有正常的 choices 结构说明 key 和通道都没问题那 OpenHands 里再报错就一定是配置字段的问题而不是通道问题。这个二分法能帮你快速定位。5. 本篇常见错排查报 401 或 invalid api key九成是环境变量没传进容器。docker run 时-e TAOTOKEN_API_KEY$TAOTOKEN_API_KEY这行如果宿主机没 export传进去就是空字符串。先在宿主机echo $TAOTOKEN_API_KEY确认有值。报 404 或 path not foundbase_url 写错了。正确是https://taotoken.net/api不要写成/api/v1也不要漏掉 /api。LiteLLM 会自己补 /v1/chat/completions。报 model not foundmodel 字段的前缀或名字不对。去模型对话页确认准确标识必要时加openai/前缀。有些模型需要 custom_llm_provider 配合别只改 model 不改 provider。报 400 unsupported parameter模型不支持某个参数。把drop_params true加上让 LiteLLM 自动丢弃。如果还报检查是不是 temperature 和 top_p 同时传给了不支持并存的模型。Agent 一直转圈不结束不是通道问题是 max_iterations 太大或任务描述太模糊。先把 max_iterations 调到 20 以内任务写具体点。也可能是模型返回的 function call 格式没被正确解析这时看日志里有没有 parse 相关的 warning。改了 config.toml 不生效确认挂载路径对不对容器内路径是不是 /app/config.toml。另外 settings.json 如果存在会覆盖先把它挪走再测。key 泄露风险别把 key 写进 config.toml 明文。用env:前缀读环境变量或者用 OpenHands 支持的密钥管理方式。提交代码前 grep 一遍 key 前缀。6. 后续怎么走从跑通到长期用通道跑通只是第一步。如果你只是偶尔验证模型效果直接在模型对话页试就行地址是 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。但如果你打算把 OpenHands 当成日常编码或 Agent 开发的常驻工具反复手动配 key、切模型会很烦这时候可以看下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它更适合长期编码和 Agent 场景的额度管理。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有针对不同框架的配置示例OpenHands 这类走 LiteLLM 的框架基本都能套。如果你用的是 Claude Code 那套 Anthropic 协议的工具也有对应说明在 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropicutm_campaignrewrite 。最后给个实操建议把 config.toml 里的 llm 段单独抽成一个llm.local.toml用 include 或挂载方式注入这样换模型、换 key 时不用动主配置也不会误提交。跑通之后先拿一个真实的小任务压一压比如让它读一个本地文件、改一行、再跑个测试观察多轮 step 里 token 消耗和延迟心里有数了再上复杂任务。
AI Agent 框架探秘：拆解 OpenHands（7）--- Agent 配置与 TaoToken 接入实战
1. 本地跑通 OpenHands 后模型通道到底卡在哪OpenHands 是一个把「大模型决策 工具执行」放进循环里的 AI Agent 框架它能读写文件、跑 bash、执行 Python靠的是每一轮把当前状态喂给 LLM再拿回下一步动作。适合谁适合已经在本地把 OpenHands 拉起来、能打开界面、但一让它干活就报模型调用失败或一直转圈的开发者。我见过太多人卡在同一个地方容器起来了Web 界面能开任务一提交就提示鉴权失败、base_url 不通、或者模型名对不上。问题根源在于 OpenHands 的模型适配层是分层的。它用 LiteLLM 做统一封装上层是 LLM 类和 LLMRegistry配置则来自 config.toml 和运行时注入的 settings。你如果只改了环境变量却没同步 config.toml或者把 key 写进了错误的 sectionAgent 的 step() 拿不到可用的 LLM 实例整个循环第一步就断了。这篇就聚焦「配置文件 统一 Key/API 通道」这条线给你一份能直接复制的 config.toml 骨架再走一遍从启动到验证 Agent 真正调用通道的闭环。核心检索词先摆出来OpenHands 怎么配置模型、Agent 的 LLM 通道怎么接、config.toml 怎么写、settings.json 放哪、启动后怎么确认 Agent 真的调通了。2. 接入前的准备TaoToken 通道与 Key 的定位在动配置文件之前先把「通道」这件事想清楚。OpenHands 的 LLM 类最终是通过 LiteLLM 发起请求的它认的是标准 OpenAI 兼容接口一个 base_url、一个 api_key、一个 model 名。所以你要做的不是改 OpenHands 源码而是给它一个能稳定响应 OpenAI 格式的入口。TaoToken 在这里扮演的就是这个统一入口。官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 根地址是 https://taotoken.net/api 。注意这个 /api 结尾LiteLLM 拼接路径时会自动补 /v1/chat/completions所以 base_url 填到 /api 这一层就行别自己再加 /v1否则会变成 /api/v1/v1/... 这种重复路径这是最常见的 404 来源。Key 的获取走控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 进去后在 API Keys 页面创建页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建出来的 key 一般以固定前缀开头复制后先存到本地环境变量里别直接硬编码进 config.toml 提交到 git。注意OpenHands 的配置里 api_key 字段支持从环境变量读取推荐用api_key env:TAOTOKEN_API_KEY这种写法避免明文泄露。模型名这块要留意。TaoToken 的模型对话页在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 你可以先在那里确认当前可用的模型标识比如常见的 claude 系列、gpt 系列命名。OpenHands 的 config.toml 里 model 字段要填 LiteLLM 能识别的名字如果走的是自定义 provider通常需要加前缀比如openai/你的模型名配合 custom_llm_provider 指定。这一步填错表现就是启动时报 model not found。3. 可复制的 config.toml 骨架OpenHands 的配置读取优先级大致是命令行参数 环境变量 config.toml 默认值。我们这里以 config.toml 为主环境变量兜底 key。下面这份骨架你可以直接改。[core] # 工作目录容器内路径按你实际挂载调整 workspace_base ./workspace # 缓存目录 cache_dir ./cache # 运行模式本地用 local 或 docker runtime docker # 最大迭代次数防止 Agent 无限循环烧 token max_iterations 50 [llm] # 模型标识按 TaoToken 模型页确认后填写 model openai/claude-sonnet-4 # 统一通道入口注意结尾是 /api base_url https://taotoken.net/api # 从环境变量读取避免明文 api_key env:TAOTOKEN_API_KEY # 自定义 provider走 OpenAI 兼容协议 custom_llm_provider openai # 温度Agent 任务建议低一点减少乱跑 temperature 0.2 # 单次最大输出 token max_output_tokens 8192 # 超时Agent 多轮调用别设太短 timeout 300 # 失败重试次数 num_retries 3 # 重试等待区间 retry_min_wait 2 retry_max_wait 10 retry_multiplier 2 # 允许 LiteLLM 丢弃模型不支持的参数兼容性关键 drop_params true [agent] # 默认 Agent 类型代码任务用 CodeActAgent default_agent CodeActAgent # 是否开启确认模式调试期可开 enable_auto_lint true [sandbox] # 沙箱超时 timeout 120 # 是否使用宿主网络按需 use_host_network false几个字段单独说清楚。custom_llm_provider openai是让 LiteLLM 按 OpenAI 协议发请求TaoToken 的 /api 入口就是 OpenAI 兼容的所以这里必须对上。drop_params true很重要因为不同模型对 temperature、top_p 的支持不一样LiteLLM 会自动丢掉不支持的参数否则会直接报 400。model字段如果你不确定前缀可以先在模型对话页发一条测试消息确认模型标识的准确写法。如果你更习惯用 settings.json 做运行时覆盖OpenHands 也支持。settings.json 一般放在工作目录或通过挂载注入结构类似{ llm: { model: openai/claude-sonnet-4, base_url: https://taotoken.net/api, api_key: env:TAOTOKEN_API_KEY, custom_llm_provider: openai, temperature: 0.2, drop_params: true }, agent: { default_agent: CodeActAgent } }settings.json 的优先级高于 config.toml适合你在不改主配置的情况下临时切换模型。但要注意如果两边都写了 llm 段settings.json 会覆盖排查问题时先确认到底哪份生效了。4. 启动与验证确认 Agent 真的调通了通道配置写完先设环境变量再启动。Linux/macOS 下export TAOTOKEN_API_KEY你的keyWindows PowerShell$env:TAOTOKEN_API_KEY你的key然后启动 OpenHands。如果你用的是官方 docker 方式大致是docker run -it --rm \ -e TAOTOKEN_API_KEY$TAOTOKEN_API_KEY \ -v $(pwd)/config.toml:/app/config.toml \ -v $(pwd)/workspace:/app/workspace \ -p 3000:3000 \ openhands:latest启动日志里重点看两行一行是 LLM 初始化时打印的 model 和 base_url确认没有拼错另一行是 Agent 注册时打印的 default_agent。如果这两行正常说明配置被读进去了。接下来做真正的验证。打开 Web 界面提交一个最小任务比如「在当前目录创建一个 hello.txt内容写 hello agent」。观察后端日志你应该能看到类似这样的调用记录LLM: model has vision enabled LLM: model supports function calling POST https://taotoken.net/api/v1/chat/completions如果看到 POST 请求打到了 /api/v1/chat/completions并且返回 200说明通道通了。Agent 会进入 step 循环生成 Action写文件→ 执行 → 拿 Observation → 再决策。任务完成后界面会显示 AgentFinishAction。想更直接地验证通道本身可以绕过 OpenHands用 curl 单独打一发curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4, messages: [{role: user, content: reply with ok}], max_tokens: 16 }返回里如果有正常的 choices 结构说明 key 和通道都没问题那 OpenHands 里再报错就一定是配置字段的问题而不是通道问题。这个二分法能帮你快速定位。5. 本篇常见错排查报 401 或 invalid api key九成是环境变量没传进容器。docker run 时-e TAOTOKEN_API_KEY$TAOTOKEN_API_KEY这行如果宿主机没 export传进去就是空字符串。先在宿主机echo $TAOTOKEN_API_KEY确认有值。报 404 或 path not foundbase_url 写错了。正确是https://taotoken.net/api不要写成/api/v1也不要漏掉 /api。LiteLLM 会自己补 /v1/chat/completions。报 model not foundmodel 字段的前缀或名字不对。去模型对话页确认准确标识必要时加openai/前缀。有些模型需要 custom_llm_provider 配合别只改 model 不改 provider。报 400 unsupported parameter模型不支持某个参数。把drop_params true加上让 LiteLLM 自动丢弃。如果还报检查是不是 temperature 和 top_p 同时传给了不支持并存的模型。Agent 一直转圈不结束不是通道问题是 max_iterations 太大或任务描述太模糊。先把 max_iterations 调到 20 以内任务写具体点。也可能是模型返回的 function call 格式没被正确解析这时看日志里有没有 parse 相关的 warning。改了 config.toml 不生效确认挂载路径对不对容器内路径是不是 /app/config.toml。另外 settings.json 如果存在会覆盖先把它挪走再测。key 泄露风险别把 key 写进 config.toml 明文。用env:前缀读环境变量或者用 OpenHands 支持的密钥管理方式。提交代码前 grep 一遍 key 前缀。6. 后续怎么走从跑通到长期用通道跑通只是第一步。如果你只是偶尔验证模型效果直接在模型对话页试就行地址是 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。但如果你打算把 OpenHands 当成日常编码或 Agent 开发的常驻工具反复手动配 key、切模型会很烦这时候可以看下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它更适合长期编码和 Agent 场景的额度管理。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有针对不同框架的配置示例OpenHands 这类走 LiteLLM 的框架基本都能套。如果你用的是 Claude Code 那套 Anthropic 协议的工具也有对应说明在 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropicutm_campaignrewrite 。最后给个实操建议把 config.toml 里的 llm 段单独抽成一个llm.local.toml用 include 或挂载方式注入这样换模型、换 key 时不用动主配置也不会误提交。跑通之后先拿一个真实的小任务压一压比如让它读一个本地文件、改一行、再跑个测试观察多轮 step 里 token 消耗和延迟心里有数了再上复杂任务。
