团队一起用 teamai-cli，卡住的通常不是工具本身，而是顺序。很多人先各自装、各自填 key，等到要共用一份配置时才发现模型来源不一致、密钥归属说不清，前面每个人的本地改动基本都要重来。建议把接入拆成有先后的五步：先固定运行环境与命令入口，再确定模型来源，再定密钥的提供方与保管方式，之后才谈共享配置与个人覆盖，最后用一次双人任务验收。每一步的判据都能通过命令输出、日志或仓库状态直接看到，不依赖口头约定。

如果只是个人试用，装完填上 key 就能跑，不必按这个顺序。但只要是多人协作、后面还要共用一份配置，建议固定成：运行环境 → 模型来源 → 密钥归属 → 共享配置 → 双人验收。判断有没有做对，看两点：任意成员执行版本查看命令得到一致结果；配置文件里没有明文密钥，密钥只从环境变量或团队的密钥管理系统注入。顺序做反时，返工通常出现在模型字段和密钥轮换这两处。

先把运行环境与命令入口固定下来

这一步的目标是让所有人调用的是同一个来源、同一套依赖。来源不同时，命令行为、配置文件路径、默认参数都可能不一样，后面排查问题会互相干扰。

先确认版本和入口位置。建议统一执行下面两条，并把输出贴进团队约定的记录位置，而不是只留在各自终端里：

which teamai-cli
teamai-cli `--version`
teamai-cli doctor

安装来源需要写清楚：是从内部制品库拉取、用包管理器安装，还是用发布页提供的二进制包。二进制包通常可以核对哈希，包管理器安装则要确认锁定的是哪个版本区间。不同来源混用时，which 的结果可能一个指向全局软链、一个指向虚拟环境内部，这属于典型的不一致。

团队内约定版本的记录位置，建议放在仓库根目录一个固定文件里，比如 tools.md、README 的「环境基线」一节，或 .tool-versions、.python-version 这类由工具链自动读取的文件。记录内容至少包括：版本号、安装来源、必要时的哈希或校验方式。风险点在于只写「装最新版」——换成不同机器就可能出现两个版本。

第二步确定模型来源：自建端点还是外部服务

模型来源决定要填哪些字段、走什么网络出口，也会牵动后面所有配置，所以放在密钥之前定。团队里如果一半人指向自建端点、一半人指向外部服务，后面共享配置几乎没法写。

两种来源的字段骨架大致如下，具体字段名以实际文档和 teamai-cli `--help` 为准，这里给的是通用结构：

# 自建端点
model_provider = "self-hosted"
base_url       = "https://内部域名/v1"
model          = "团队约定的模型名"
# 是否需要 TLS 校验、超时秒数，按实际端点行为确认

# 外部服务
model_provider = "external"
model          = "团队约定的模型名"
# 认证字段通常与密钥一起在下一步注入

用一条最小请求验证连通，先别接业务逻辑：

teamai-cli chat `--model` "团队约定的模型名" `--prompt` "ping"

判读方式可以按常见错误码粗分：连接超时或 DNS 解析失败，说明网络出口或域名不对；返回 401、403，说明认证信息有问题，先别急着改 URL；返回 404，多半是路径或模型名不匹配。这一步只验证「能通」，不追求稳定。

第三步把密钥的提供方与保管方式定下来

要明确三件事：谁负责发密钥、密钥放在哪、多久换一次。这三件事没定，后面共享配置一写就会出现明文密钥入库的情况。

注入方式建议用环境变量，示例：

# 仅当前 shell 会话生效，退出即失效
export TEAMAI_API_KEY="占位符"
teamai-cli chat `--prompt` "ping"

本地开发可以把变量放进 .env.local 这类文件，前提是该文件已被忽略。检查方式：

git check-ignore -v .env.local
git grep -n -I "sk-" -- . ':!*.md'

第二条命令用来粗略扫一遍仓库里有没有疑似密钥串，-I 会跳过二进制文件。它扫不到密钥管理系统的内容，所以只作为提交前的自检，不是审计手段。

轮换时需要同步改动的位置，建议提前列成清单：各成员本地环境变量或 .env.local、CI 或流水线里的 secret、共享配置中引用的变量名（只写变量名，不写值）、文档里的占位符示例。风险点是把真实密钥写进共享配置或文档示例，轮换时又忘了改其中一处。

第四步再谈共享配置与个人覆盖

到这一步才处理「团队配置可复用、个人差异不污染仓库」。常见的加载顺序是：内置默认值 → 共享配置文件 → 本地个人文件 → 环境变量。后者覆盖前者，具体优先级以实际行为为准，建议先用一条命令确认。

# 共享配置，入库，例如 teamai.toml
model_provider = "external"
model          = "团队约定的模型名"

# 本地覆盖，不入库，例如 teamai.local.toml
timeout = 120

覆盖规则示例：共享配置里写团队统一使用的模型名，个人文件里只放超时、日志级别这类不影响结果一致性的字段。如果个人文件里改了模型名，就相当于绕过了共享约束，验收时会暴露出来。

验证覆盖是否生效，用带来源说明的查看命令：

teamai-cli config get model
teamai-cli config show `--source`

子命令名称以 teamai-cli config `--help` 输出为准。看到最终值以及它来自哪个文件，才算这一步做完。

第五步用一次双人任务验收接入顺序

验收的目的不是跑通功能，而是检查前四步有没有留下隐式依赖——比如某个人机器上恰好有某个环境变量，别人没有。

建议安排两名成员，执行同一个任务：

1. A 只用共享配置、不设任何本地覆盖，执行一次带实际输入的任务。
2. B 在共享配置基础上加一条本地覆盖（例如超时或日志级别），执行同一条任务。
3. 两人各自把 config show `--source` 的输出和任务日志贴回同一个地方，对比模型来源、模型名和密钥来源标识。

每步期望看到的输出：版本查看命令结果一致；连通性验证没有连接超时和 401、403；日志里不出现明文密钥；配置来源能指到预期的文件。

失败时的回退方向：版本或命令入口对不上，回第一步；连不通、域名解析异常，回第二步；401、403 或密钥来源不明确，回第三步；模型名或超时值来源与预期不符，回第四步。若两人都通过但换第三个人就失败，通常说明存在没写进记录的环境变量，按同样路径再查一遍即可。