> ## Documentation Index
> Fetch the complete documentation index at: https://linkly.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 在 ZCode 中使用 Linkly AI

> 将 Linkly AI 本地知识库接入 ZCode，让基于 GLM 的编程 Agent 搜索和阅读你的私有文档

## 可以用来做什么

<AccordionGroup>
  <Accordion title="让 Agent 先读规范再写代码">
    用 Linkly AI 的 `search` 工具找到架构决策记录和需求文档，再用 `read`
    阅读相关章节。ZCode Agent 拿着你的项目约定写代码，而不是靠猜。
  </Accordion>

  <Accordion title="让 Goal Mode 和 Subagents 基于真实资料工作">
    ZCode 通过 Goal Mode 和 Subagents 自主执行长周期任务。接入 Linkly AI
    后，这些任务可以按需检索本地资料——多步骤的重构或迁移始终锚定在你真实的文档上。
  </Accordion>

  <Accordion title="一套知识库在所有工作区共享">
    在用户级配置一次 Linkly AI，所有 ZCode
    工作区都能访问同一批本地文档。无需重复上传附件，也无需为每个项目单独配置。
  </Accordion>
</AccordionGroup>

## 前置条件

* 已安装 [ZCode](https://zcode.z.ai)
* Linkly AI Desktop 已启动，MCP 服务正在运行

## 配置步骤

<Tabs>
  <Tab title="本地 MCP HTTP（推荐）" icon="globe">
    <Steps>
      <Step title="打开 MCP 服务器页面">
        打开 ZCode **设置**，进入 **MCP 服务器** 页面，点击 **新建 MCP 服务器**。
      </Step>

      <Step title="选择作用域">
        选择 **用户** 让 Linkly AI 在所有工作区可用，或选择 **工作区**
        仅在当前项目中可用。
      </Step>

      <Step title="填写配置并添加">
        填写以下信息：

        * **类型**：`HTTP`
        * **名称**：`linkly-ai`
        * **URL**：`http://127.0.0.1:60606/mcp`

        点击 **添加** 完成，然后确认服务器列表中 `linkly-ai` 的开关已打开。
      </Step>
    </Steps>
  </Tab>

  <Tab title="远程 MCP" icon="cloud">
    需要先完成[远程访问配置](/docs/zh/use-in-remote)，桌面端隧道显示 <Badge stroke color="green">● 已连接</Badge>。

    <Steps>
      <Step title="打开 MCP 服务器页面">
        打开 ZCode **设置**，进入 **MCP 服务器** 页面，点击 **新建 MCP 服务器**。
      </Step>

      <Step title="填写远程配置">
        填写以下信息：

        * **类型**：`HTTP`
        * **名称**：`linkly-ai`
        * **URL**：`https://mcp.linkly.ai/mcp`
      </Step>

      <Step title="添加鉴权请求头">
        展开 **请求头（可选）**，添加：

        * **Key**：`Authorization`
        * **Value**：`Bearer <你的 API Key>`

        API Key 在 [Linkly AI 控制台](https://linkly.ai/dashboard/integrations)
        创建，以 `lkai_` 开头。点击 **添加** 完成。
      </Step>
    </Steps>
  </Tab>

  <Tab title="CLI Stdio（备选）" icon="terminal">
    需要先[安装 Linkly AI CLI](/docs/zh/use-cli)，然后直接编辑 ZCode 的配置文件：

    * 用户级：`~/.zcode/cli/config.json`
    * 工作区级：`<项目根目录>/.zcode/config.json`

    ```json theme={null}
    {
      "mcp": {
        "servers": {
          "linkly-ai": {
            "command": "linkly",
            "args": ["mcp"],
            "env": {}
          }
        }
      }
    }
    ```

    <Note>
      两个文件同名但层级不同——用户级配置在 `.zcode/cli/` 目录下，工作区级配置直接在
      `.zcode/` 目录下。编辑错文件是这里最常见的失误。
    </Note>

    也可以在界面中完成同样的配置：在 **MCP 服务器** 页面点击 **新建 MCP 服务器**，**类型**
    保持 `stdio`，**命令** 填 `linkly`，**参数** 填 `mcp`。
  </Tab>
</Tabs>

## 安装 Skills

ZCode 支持 Agent Skills，你可以顺便安装 Linkly AI Skills，教会 Agent 如何高效使用这些工具：

```bash theme={null}
git clone https://github.com/LinklyAI/linkly-ai-skills.git ~/.zcode/skills/linkly-ai
```

回到 **设置 → 技能** 点击 **刷新**，然后在输入框输入 `$` 选择 `linkly-ai` 即可调用。

<Tip>更多安装方式和 Skills 的工作原理，参见[使用 Skills](/docs/zh/use-skills)。</Tip>

## 开始使用

配置完成后，直接在 ZCode 中提问，Agent 会自动调用 Linkly AI 工具。例如：

* "搜索我的文档，找找这个模块的架构决策"
* "读一下我的 API 规范，检查这个实现是否符合"

## 常见问题

<AccordionGroup>
  <Accordion title="在 .agents/mcp.json 中配置的服务消失了">
    同一作用域内 `.zcode` 配置优先：只要 ZCode 从 `.zcode` 配置文件中读到了任何
    MCP 服务，该作用域下的 `.agents/mcp.json`
    就会被整体跳过，而不是合并。请把这些服务迁移到 `.zcode` 配置文件中。
  </Accordion>

  <Accordion title="HTTP 方式连接失败">
    检查 Linkly AI Desktop 是否正在运行、MCP 服务是否已启动。可以在终端执行
    `curl http://127.0.0.1:60606/mcp` 测试连通性。
  </Accordion>

  <Accordion title="服务在列表中但工具不可用">
    被停用的服务会在配置对象中写入 `"enable": false`。在 **MCP 服务器**
    页面重新打开开关，或从配置文件中删除该字段。
  </Accordion>

  <Accordion title="Stdio 方式报找不到 linkly 命令">
    确认已[安装 Linkly AI CLI](/docs/zh/use-cli)，且 `linkly` 命令在 PATH
    中可用。可执行 `linkly --version` 验证。
  </Accordion>
</AccordionGroup>