Langcli

Why this agent

Langcli(npm 上叫 langcli-com;厂商站点 langcli.com)是终端里的交互式 AI 编程助手。引用它的上游 README:“Langcli 100% 兼容 Claude Code。所以 Langcli 的用法和标准 Claude Code 完全一样;你现有项目里的 .claude 配置和 skills 都能在 Langcli 里直接用。” 这意味着 espctl 的接入方式和 Claude Code 一模一样 —— 同一个配置文件,同一个形状。

Prerequisites

已安装 Node.js 20+。

Langcli 已通过 npm i -g langcli-com 或官方安装脚本安装:

bash -c "$(curl -fsSL https://assets.langcli.com/installation/install-langcli.sh)"

langcli --version 能跑。
espctl 已安装在磁盘上某个稳定位置(下文需要完整路径)。
(可选,用于远程构建)Aegis 构建服务器地址 + MCP_AUTH_SECRET。

Install snippet (or alternative)

粘进 .claude/settings.json(项目根目录或全局)—— Langcli 读的是和 Claude Code 完全一样的文件:

{
  "mcpServers": {
    "espctl": {
      "command": "/path/to/espctl",
      "args": ["mcp", "serve"],
      "cwd": "/path/to/your/esp-idf/project",
      "env": {
        "CONTROL_BASE_URL": "https://esphome.cloud",
        "MCP_AUTH_SECRET": "your-access-key"
      }
    }
  }
}

替换:

/path/to/espctl —— 你电脑上 espctl 程序的完整路径。
/path/to/your/esp-idf/project —— Langcli 应该操作的项目完整路径。
CONTROL_BASE_URL —— 你的 Aegis 构建服务器地址。
MCP_AUTH_SECRET —— 构建服务器给你的访问密钥。

如果你已经配过 Claude Code,这一步就完成了 —— Langcli 读的就是同一份配置。不需要再编辑 Langcli 自己的什么文件。

或者 —— 拿到预填好的代码片段:

读取 install://langcli 资源。

First-run verification

cd /path/to/your/esp-idf/project
langcli

在会话里问:

你有哪些 espctl 工具?

预期:列出约 40 个 espctl 工具(build、doctor、store_versions 等)。

Troubleshooting

Langcli 启动了但没看到 espctl 工具 —— 确认 .claude/settings.json 在当前目录或 ~/.claude/ 里存在。Langcli 用的是 Claude Code 的发现规则。
和 Claude Code 一样的 MCP 错 —— Langcli 的 MCP 运行时按设计和 Claude Code 兼容;如果 espctl 在 Claude Code 里能用但在 Langcli 里不能,提一个 issue 到 LangcliTeam/langcli。也可以参考 Claude Code 故障排查。
langcli 命令找不到 —— npm i -g langcli-com 装到全局 npm prefix;确认 npm bin -g 在 $PATH 里。

Tested as-of 2026-05-19

Langcli 特有注意事项

README 强调“你现有项目里的 .claude 配置和 skills 在 Langcli 里都能用“。所以你 Claude Code 配套的 skills 在 Langcli 里也能用 —— 不需要移植。
API key 设置走 LangRouter 做模型 provider 路由(DeepSeek、GPT、Claude 等)。这一层和 MCP 服务配置无关,和 espctl 也正交。

Keyboard shortcuts

ESP-IDF MCP 用户手册