# 本地 AI Agent

这一页写给安装在你电脑上的 AI Agent：Claude Code、Cursor、VS Code、Codex、OpenCode、Antigravity、Zed、Devin Desktop、WorkBuddy、OpenClaw、Hermes Agent，以及其他 MCP 客户端。

大多数客户端直接连接 Lune 托管的 MCP 服务器 `https://mcp.luneresearch.com`。只能启动本地进程的客户端则运行已发布的 stdio 包。两种方式都需要访问密钥，除非客户端能通过浏览器让你登录。

## 最快的方式

登录控制台，打开[安装页面](https://luneresearch.com/dashboard/install)，选择你的应用。步骤里会给出该应用的准确命令或配置，访问密钥已经填好。

在终端里运行[命令行应用](https://luneresearch.com/zh-Hans/docs/cli)的 `lune install`，也能为 Claude Code、Cursor、VS Code、Codex 或 OpenCode 完成配置。

## 手动配置

先创建访问密钥。在[凭证页面](https://luneresearch.com/dashboard/settings/credentials)打开 **API 密钥**，点击**新建密钥**。马上复制，控制台只显示一次。

### 托管服务器

Claude Code 可以直接使用下面这段配置。其他客户端用的是同样的字段，只是放在不同的键下，或者换了格式（比如 Codex 用 TOML，写作 `http_headers`），安装页面会给出每个客户端的准确格式。

```json
{
  "mcpServers": {
    "lune": {
      "type": "http",
      "url": "https://mcp.luneresearch.com",
      "headers": { "Authorization": "Bearer lune_your_access_key" }
    }
  }
}
```

如果客户端支持对远程服务器使用 OAuth，可以去掉 `headers`。客户端第一次连接时会在浏览器里打开 Lune 登录。

Hermes Agent 读取的是 YAML。在 `~/.hermes/config.yaml` 的 `mcp_servers` 下添加 Lune（安装页面给出了这段配置），然后在会话里运行 `/reload-mcp`。

### 本地 stdio 服务器

适用于必须运行本地进程的客户端。需要 Node.js 22 或更高版本，访问密钥从 `LUNE_API_KEY` 读取：

```json
{
  "mcpServers": {
    "lune": {
      "command": "npx",
      "args": ["-y", "@retrograde-labs/lune-mcp-server"],
      "env": { "LUNE_API_KEY": "lune_your_access_key" }
    }
  }
}
```

在终端里试运行：

```sh
LUNE_API_KEY=lune_your_access_key npx -y @retrograde-labs/lune-mcp-server
```

第一次运行会下载这个包，之后使用缓存的副本。stdio 服务器没有浏览器登录，所以始终需要密钥。

## 常见问题

**我需要安装什么吗？**
用托管服务器不需要。stdio 包会在客户端第一次启动它时通过 `npx` 自动安装。

**一个密钥可以在多台设备上用吗？**
可以，但每台设备各用一个密钥，笔记本丢了或卖了时只需撤销那一个。[凭证页面](https://luneresearch.com/dashboard/settings/credentials)会列出你的密钥。

**怎么知道助手现在能做什么？**
问它「你有哪些 Lune 工具？」完整列表见[工具](https://luneresearch.com/zh-Hans/docs/mcp#工具)。

## 出现问题时

- 助手说自己没有 Lune 的工具时，完全退出应用再重新打开。大多数客户端只在启动时加载工具。
- 很多应用在**设置 → 工具**或**设置 → MCP** 下提供 MCP 连接日志，这是确认 Lune 是否接上的最快办法。
- 丢了密钥？在凭证页面撤销它，再创建一个新的。旧密钥会在五分钟内失效。
- 错误码和处理方法见[故障排查](https://luneresearch.com/zh-Hans/docs/troubleshooting)。