首次启动与欢迎屏

• 未配置服务商 — 配置状态。此时还不能发送一轮对话。
• 已配置服务商 — 带输入栏的欢迎屏，可以输入提示。

两张屏都不提供 SuperGrok、device-code 界面、preferred_method 选择器，或 MatchaCode 账号。

启动会写入什么

启动时，Matcha CLI 在 ~/.matcha 下写入新文件（可用 MATCHA_HOME 覆盖）。若存在来自 Grok Build 的 ~/.grok，它会把可恢复数据复制迁入 ~/.matcha，并保留旧目录。项目里的 .grok/ 会被读取并迁到 .matcha/；冲突文件不会被静默合并。

随 CLI 附带的操作页会在启动时复制到 ~/.matcha/docs/user-guide/。在 TUI 里输入 /docs 或 /tutorial（别名 /tour、/onboarding）。

欢迎屏主视觉使用产品 wordmark matcha 和英文 tagline A calmer way to ship code. 底部快捷栏显示适用于当前状态的按键。

从你要当作工作区的目录启动

cd /path/to/your/project
matcha

或传入目录：

matcha --cwd ~/projects/my-app

无界面 / CI（matcha -p …）和编辑器 ACP（matcha agent）是其他入口。本文讲的是交互式 TUI。

若未配置服务商

你应看到状态文案：

No model Provider is configured

TUI 里用的完整句子是：

No model Provider is configured. Run `matcha login --provider <id>` or add credentials in config.toml.

主操作是 Configure a model Provider，快捷键 c。l 仍可作为别名；Enter 激活选中的菜单行。另有一行 Quit（q）。

这个状态不会做的事：

• 不绘制 Type a message... / ❯ 输入栏。此处不能提交一轮对话。
• 不显示 grok.com、SuperGrok、device code、浏览器 OAuth 或 always-approve。
• 按 c、l 或 Enter 不会打开登录向导。该操作失败即关闭，并重复上面的 BYOK 句子。

离开 TUI（此屏上的 q 立即退出）并运行：

matcha login --provider xai

然后再次启动 matcha。若你手里的是 openai、anthropic 或其他已支持的服务商 id，换成对应的再跑。Matcha CLI 不会把推理默认到 xAI。

若已配置服务商

你应落到欢迎屏，而不是配置拦截屏。

在典型的 102×43 终端上，你应看到：

• matcha wordmark
• tagline A calmer way to ship code.
• Quit
• 可提交的输入栏 — 聚焦时提示为 ❯；未聚焦时文案是 Type a message...

页脚仍可能写 Logged in with API key。那是 BYOK 状态，不是 MatchaCode 账号。没有 grok.com、SuperGrok、device-code、preferred_method 或 steep an idea 界面。

输入一条简短请求并按 Enter。助手会把内容流式打到提示上方的回滚区（回复、shell 命令、文件编辑）。一轮进行中时，Enter 会排队下一条消息；Esc 取消本轮并保留草稿。

成功启动后的路径

用 MATCHA_HOME 覆盖主目录。使用 Matcha CLI 时不要删除 ~/.grok；遗留的 Grok 套接字和崩溃转储仍留在那里。matcha doctor 可以列出它们，但不会修改。

此屏不提供