想在团队里推 teamai-cli，建议把顺序倒过来：先把模型来源和密钥归属定清楚，再谈谁能用、怎么协作。模型来源决定每个人要改哪个字段，密钥归属决定哪些内容能进仓库、哪些只能留在本机。这两件事没定，后面往往是每人各自配一套，出了问题也说不清卡在哪一层。

建议先用一条最小验证命令确认配置链路，再把配置写成“共享文件 + 本地覆盖”两层。模型端点可以进共享配置，密钥只走环境变量或本地覆盖文件；两人以内的最小任务跑通后再扩大范围，失败时先看配置加载顺序和实际取值，而不是先怀疑网络。

用工具自带的帮助与版本输出确认命令入口和默认配置路径

先确认这个包本身提供什么入口，不要照抄别处的路径。不同版本子命令集合会变，下面命令的输出以你本地实际为准。

teamai-cli `--version`
teamai-cli `--help`
teamai-cli config `--help`

读 `--help` 输出时，先看最上面那行用法（usage），它给的是调用形式；再看子命令清单，通常按配置、任务/会话、模型或 provider、诊断几类分组。看到 config、doctor 这类子命令，先用 `--help` 展开，而不是猜参数。

默认配置路径一般能从两处看到：一是帮助输出里提到的默认文件，二是诊断类子命令打印的实际路径。常见候选位置包括 ~/.config/teamai-cli/、~/.teamai-cli/，以及项目根目录下的点文件（如 .teamai-cli.toml，名字以实际为准）。如果环境里设置了 XDG_CONFIG_HOME，配置目录通常跟着它走，这点需要结合环境确认。

把模型来源写成一份可被同事复用的配置片段

模型来源建议只定义一次，放在能被同事复用的共享配置片段里；个人差异（比如各自连的内网网关）再走覆盖层。配置文件和环境变量同时存在时，通常环境变量优先级更高，但生效顺序以查最终取值的命令输出为准，别凭印象。

片段骨架只写层级和字段名，具体字段以实际文档为准：

# 共享配置骨架，字段名按实际文档替换
model:
  provider: "..."
  endpoint: "https://your-gateway.example.com/v1"
  name: "..."
  timeout_seconds: ...

defaults:
  model: "..."

如果决定走环境变量，命名通常与字段对应：

export TEAMAI_MODEL_ENDPOINT="https://your-gateway.example.com/v1"
export TEAMAI_MODEL_NAME="..."

验证最终取值：teamai-cli config show，若支持 `--effective` 或 config get model.endpoint 更好。输出里要能看到 endpoint 的实际值，以及它来自哪个文件或环境变量，这样才算了配置写对了地址。

密钥不进仓库：交给环境变量或本地覆盖文件

共享配置可以入库，个人密钥留在本机。加载顺序通常是：默认配置 → 共享配置文件 → 本地覆盖文件 → 环境变量。具体有没有“环境变量覆盖本地文件”这一步，用上一节那条查最终取值的命令确认一遍。

需要加入忽略清单的条目，至少包括：

• 本地覆盖文件：.teamai-cli.local.*、*.local.toml（按实际命名调整）
• 密钥文件：.env、.env.local
• 运行输出：日志文件、调试时导出的配置文件

确认密钥已被进程读到，同时不要打印明文：

env | grep -c TEAMAI_API_KEY
teamai-cli doctor

诊断输出里通常会出现类似 credential: set (source=env) 的行，密钥本身一般会打码；日志里也可以找 credential loaded 这类事件行。如果变量存在但没有这行，说明进程没吃到，常见原因是当前 shell 没重新加载，或子进程没有继承环境。

用一次两人以内的最小任务验证配置真的通了

配置写完后别等人齐，先用一条最小调用暴露断点：

teamai-cli run `--prompt` "reply with pong"

判读方式：成功时输出里会有模型的返回内容，通常还会带上命中的模型名或 provider 标识；失败时一般在请求阶段就中断，只留下 error 行。两者的差异点主要是——成功能看到完整回复且没有 error 级别日志，失败是 error 行在前、回复为空。

失败先看第一行 error，而不是最后一行堆栈。常见断点有三类：缺密钥（提示未设置凭据）、端点不可达（连接被拒或超时）、模型名不匹配（服务端返回未知模型）。这条命令跑通后，再让第二位同事用他自己的密钥执行同一条命令，确认共享配置对别人也生效，而不是只在你机器上有效。

约定后续改动走哪条路径

把改动路径固定下来，避免每次都靠口头同步。

回滚到上一版配置的做法：共享配置如果在版本管理里，回滚就是 revert 对应提交，或把文件恢复到上一版；本地覆盖文件建议改之前先复制一份备份，回滚就是把备份换回来，然后重跑上一节那条最小任务命令确认配置仍然生效。