1. OpenHands CLI 配置加载链路到底卡在哪OpenHands 的 CLI 交互设计里最容易被忽略、也最容易出问题的环节不是命令解析而是配置加载链路。你敲下openhands之后程序会按顺序去几个位置找 settings环境变量、项目级配置文件、用户级~/.openhands目录、最后才是内置默认值。任何一层写错CLI 要么起不来要么起来了但模型请求发不出去。我见过太多人卡在同一个地方CLI 能进交互界面输入问题后转圈半天最后抛一个local proxy failed或者reading choices相关的报错。表面看是网络问题实际是 settings 里的 Base URL 和 Key 没对齐。OpenHands 的 CLI 本身不绑定某一家模型服务它读的是你 settings 里写的 provider 配置所以把这一层改到统一通道是让整个交互会话稳定建立的关键动作。这篇笔记聚焦的就是这条链路settings 文件长什么样、字段怎么填、CLI 启动时按什么顺序读、改完之后怎么验证会话真的通了。适合已经在用 OpenHands 做本地开发、但被模型接入配置反复折腾的人。你会拿到可直接复制的 settings 片段以及一套从改配置到发请求的完整验证动作。先说清楚 OpenHands CLI 的定位。它是无头模式的前端负责把你在终端里的输入打包成请求发给后端 agent 服务再把 agent 的响应流式吐回终端。它操作本地文件系统会话状态持久化在~/.openhands下。所以 CLI 的交互体验好不好一半取决于命令设计另一半取决于 settings 里模型通道配得对不对。命令设计是 OpenHands 官方的事模型通道是你自己的事——这篇就解决后者。配置加载的优先级实测下来大致是这样命令行显式传入的参数 环境变量 当前工作目录下的项目配置 用户主目录的全局配置 内置默认。这意味着你在项目里放一个 settings 文件会覆盖全局的。很多人改了全局配置却没生效就是因为项目目录下有个旧的 settings 在“抢答”。排查时第一步永远是确认当前生效的是哪个文件。2. 把 settings 改到 TaoToken 的前置准备在动 settings 之前先把两样东西准备好一个可用的 API Key和一个明确的 Base URL。TaoToken 的 API 入口是https://taotoken.net/api注意这里不带任何查询参数就是干净的 API 根路径。Key 在控制台的 API Keys 页面生成格式通常是一串以特定前缀开头的字符串。为什么要在 settings 层面做这件事而不是每次启动时用环境变量临时指定因为 OpenHands CLI 的交互会话是长生命周期的你start一个会话之后后续所有chat、run都复用这个会话的模型配置。如果配置只存在于当前 shell 的环境变量里换个终端窗口、或者用脚本自动化调用时就会丢。写进 settings 文件才是持久的、可复现的。这里要区分两个概念模型通道和模型 ID。通道指的是请求发到哪个 API 端点、用哪个 Key 鉴权模型 ID 指的是具体调用哪个模型比如claude-sonnet-4-20250514这种。TaoToken 作为统一通道可以承接多种模型 ID 的请求所以你的 settings 里这两块要分开写清楚。通道配错请求根本到不了模型 ID 配错请求到了但返回模型不存在的错误。前置准备清单第一去控制台生成一个 API Key复制保存好它只显示一次第二确认你要用的模型 ID这个 ID 要和你实际想调用的模型一致第三找到你当前生效的 settings 文件位置通常是~/.openhands/settings.json或者项目根目录下的配置文件。如果你不确定可以先跑一次 CLI看它启动日志里打印的配置路径。还有一个容易踩的坑OpenHands 不同版本对 settings 的字段命名不完全一致。有的版本用llm.api_key有的用api_key有的把 Base URL 叫base_url有的叫api_base。所以下面给的片段你要对照自己版本的文档微调字段名但结构逻辑是一样的。改之前先备份原文件这是基本习惯。3. 可复制的 settings 配置片段下面这份 JSON 是 OpenHands CLI 常见的 settings 结构把模型通道指向 TaoToken。字段名请对照你的版本核对但值的填法可以直接用。{ llm: { provider: openai-compatible, model: claude-sonnet-4-20250514, api_key: sk-你的TaoToken密钥, base_url: https://taotoken.net/api, temperature: 0.7, max_tokens: 4096 }, cli: { interactive: true, history_file: ~/.openhands/history, auto_save_session: true }, workspace: { root: ., allow_file_write: true } }关键字段逐个说。provider填openai-compatible因为 TaoToken 的 API 走的是兼容 OpenAI 的请求格式这样 OpenHands 的客户端库能直接复用。base_url填https://taotoken.net/api不要在后面加/v1或者斜杠具体路径由客户端库拼接。api_key填你生成的那串。model填你要用的模型 ID。如果你用的是 TOML 格式的配置部分版本支持等价写法是这样[llm] provider openai-compatible model claude-sonnet-4-20250514 api_key sk-你的TaoToken密钥 base_url https://taotoken.net/api temperature 0.7 max_tokens 4096 [cli] interactive true auto_save_session true改完之后如果你之前设置过环境变量OPENAI_API_KEY或OPENAI_BASE_URL建议先清掉避免环境变量覆盖文件配置导致你以为改了其实没改。在 Linux/macOS 下用unset OPENAI_API_KEY OPENAI_BASE_URLWindows PowerShell 下用Remove-Item Env:OPENAI_API_KEY。还有一个细节~/.openhands目录的权限。如果这个目录是 root 创建的而你用普通用户跑 CLI读配置会失败报权限错误。确认一下ls -la ~/.openhands属主应该是你自己。会话历史文件也在这个目录下权限不对会导致会话无法持久化。配置写好后别急着进交互模式。先用一个最简单的单次命令验证通道是否通比如让 CLI 跑一个不涉及文件操作的小任务。这样能把“配置问题”和“agent 逻辑问题”分开排查起来快很多。4. 启动 CLI 并验证会话建立验证分三步走每步都有明确的成功标志任何一步失败都能定位到具体环节。第一步检查配置是否被正确加载。跑一个打印配置的命令或者直接启动 CLI 看它输出的模型信息。如果 CLI 启动时打印的 model 和 base_url 跟你写的一致说明加载链路通了。如果不一致回去检查是不是有更高优先级的配置文件在覆盖。openhands config show预期输出里应该能看到base_url: https://taotoken.net/api和你的模型 ID。如果这里显示的还是默认值或者旧值说明你改的文件不是当前生效的那个。第二步发一个最小请求验证鉴权。用单次命令模式让 agent 做一个纯文本任务不碰文件系统openhands run --task 用一句话说明什么是命令行界面成功的话终端会流式输出一句回答。这一步验证的是 Key 有效、通道可达、模型 ID 正确。如果这里报 401就是 Key 问题报连接失败就是 Base URL 问题报模型不存在就是 model 字段问题。第三步进交互模式验证会话持久化openhands chat进入后输入一个问题比如“帮我看看当前目录下有哪些文件”观察 agent 是否能正常调用工具、返回结果。然后输入exit退出再重新openhands chat看它是否能恢复上一个会话的上下文。能恢复说明~/.openhands下的会话状态写入正常。三步都通过说明你的 CLI 交互会话已经稳定建立在 TaoToken 通道上了。这时候再去跑复杂的多轮任务比如让 agent 读代码、改文件、跑测试才有意义。基础通道不稳上层任务全是玄学问题。实测下来最容易在第二步翻车。很多人第一步配置看着对第二步请求就 401原因是 Key 复制时带了空格或者把 Key 写进了错误的字段。复制 Key 之后建议用echo检查一下有没有多余字符。5. 常见报错对照排查这一节按真实报错信息来对照你遇到哪条就查哪条。401 Unauthorized鉴权失败。九成是 Key 问题。检查api_key字段有没有填、有没有多余空格、是不是过期了。还有一种情况是 Key 填对了但provider字段写错导致客户端用了错误的鉴权头格式。确认provider是openai-compatible。local proxy failed / connection refused连接失败。检查base_url是不是https://taotoken.net/api有没有多写或少写路径。如果你本地配了 HTTP 代理环境变量先清掉再试代理会拦截请求导致连不上。这个报错和网络环境有关但根因往往是配置里的地址不对。Error reading choices / unexpected response format响应解析失败。通常是base_url指向了一个返回非标准格式的端点或者模型 ID 不被通道支持。确认你的 model ID 是通道支持的并且 base_url 没有指向某个具体的模型路径。OAuth / token refresh failed如果你之前用过需要 OAuth 的 providersettings 里可能残留了 OAuth 相关字段。把这些字段删掉只保留 api_key 方式。OAuth 和 API Key 两种鉴权方式混在一起会冲突。model not found模型 ID 写错或者该 ID 在当前通道下不可用。对照通道支持的模型列表核对拼写注意大小写和版本号后缀。permission denied on ~/.openhands目录权限问题。用chown -R $(whoami) ~/.openhands修复属主或者删掉重建。排查顺序建议固定下来先看配置加载对不对config show再看鉴权通不通最小请求最后看会话状态重启恢复。这个顺序能把问题范围一步步缩小避免在错误的方向上浪费时间。如果你用的是 Claude Code 类的工具链配置三件套永远是 Base URL、Key、Model ID缺一不可。CC Switch 或 Cline MCP 这类工具在切换 provider 时也是改这三个值。把这套逻辑吃透换任何工具都能快速接上。6. 把通道固定下来让 CLI 真正好用配置改通只是开始真正让 CLI 好用的是把通道固定成默认行为。我的做法是在项目根目录放一份 settings把模型通道写死这样团队里每个人 clone 下来就能用不用各自配环境变量。敏感信息用环境变量注入settings 里只写占位符避免 Key 进版本库。具体做法settings 里api_key字段留空或者写${TAOTOKEN_API_KEY}然后在 shell 启动脚本里 export 真实 Key。OpenHands 加载配置时会做变量替换。这样既保证了配置的可复现又不泄露密钥。会话历史的管理也值得花点心思。~/.openhands/history会越积越大定期清理或者按项目分目录存放。如果你同时跑多个项目的 agent 任务混在一起的历史会让上下文串味。可以在项目 settings 里指定独立的 history 路径。最后说一个实用技巧把常用的 CLI 调用封装成 shell 函数或者 Makefile 目标。比如make ask Q...映射到openhands run --task $Q这样日常调用更顺手。CLI 的价值就在于可脚本化把它嵌进你的工作流比每次手动敲完整命令高效得多。通道配好之后你可以放心地把更多任务交给 agent读代码库、生成测试、改配置文件。这些任务的稳定性都建立在最开始那条 settings 加载链路正确的基础上。回头看你踩过的那些坑多半不是 agent 不够聪明而是配置没对齐。把这一层做扎实后面的交互体验会顺很多。
