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

# 自訂密鑰

> 保存私密存取密鑰，讓 Happycapy 使用外部工具時不需要把密鑰暴露在對話裡。

自訂密鑰是用於 Happycapy 之外服務的私密存取密鑰，例如 GitHub、Notion、Fly.io、Stripe 或你自己的內部工具。

當某個工具需要 token 或 API key 時，請在 **Settings > Sandbox > Custom secrets** 中新增，而不是把密鑰貼到對話裡。Happycapy 會在每次訊息啟動時，把密鑰作為環境變數注入沙箱。

## 什麼時候使用自訂密鑰

當 Happycapy 需要代表你存取某個服務或工具時，就適合使用自訂密鑰。

常見例子包括：

* 檢查 GitHub 倉庫、Pull Request 或 workflow 執行記錄
* 建立或更新 Notion 頁面
* 在 Fly.io 等平台部署或檢查應用程式
* 執行會呼叫你自己的 Stripe、分析、資料庫或內部 API 的腳本
* 使用需要從環境變數讀取憑證的命令列工具

## 新增密鑰

1. 打開 **Settings**。
2. 進入 **Sandbox**。
3. 找到 **Custom secrets**。
4. 點擊 **Add**。
5. 填寫 **Key**、**Value** 和 **Description**。
6. 點擊 **Create**。

<Frame>
  <img src="https://mintcdn.com/happycapy/3Agk_CtGKKqauJRe/images/integrations/custom-secrets-settings.png?fit=max&auto=format&n=3Agk_CtGKKqauJRe&q=85&s=ee2a7b86e5ffb93a49b5ca42c0825528" alt="Happycapy 沙箱設定中的 Custom secrets 設定" width="2326" height="1508" data-path="images/integrations/custom-secrets-settings.png" />
</Frame>

## 每個欄位是什麼意思

| 欄位              | 簡單解釋                         | 範例                                                  |
| --------------- | ---------------------------- | --------------------------------------------------- |
| **Key**         | Happycapy 和工具用來找到這個密鑰的名稱。    | `GITHUB_TOKEN`                                      |
| **Value**       | 真正的私密 token、API key 或密鑰值。    | 貼上來自 GitHub、Notion 或其他服務的值。                         |
| **Description** | 簡短說明，讓 Happycapy 知道這個密鑰用於什麼。 | `GitHub access for checking PRs and workflow runs.` |

Description 最好寫成簡短指令，而不只是標籤。

好的寫法：

```text theme={null}
GitHub token for using the gh CLI and GitHub API in my repositories.
```

太模糊：

```text theme={null}
github token
```

## 常見範例

| Key                  | 用途                                           |
| -------------------- | -------------------------------------------- |
| `GITHUB_TOKEN`       | 讀取倉庫、檢查 Pull Request、使用 GitHub API，或執行 `gh`。 |
| `NOTION_TOKEN`       | 透過 Notion API 處理 Notion 頁面或資料庫。              |
| `FLY_API_TOKEN`      | 使用 `flyctl` 部署或檢查 Fly.io 應用程式。               |
| `STRIPE_API_KEY`     | 測試會呼叫你自己 Stripe 帳號的腳本。                       |
| `INTERNAL_API_TOKEN` | 從腳本呼叫你的公司或專案 API。                            |

這些名稱只是範例。請始終使用對應工具、SDK 或 CLI 期望的 key 名稱。

## Happycapy 如何使用密鑰

新增自訂密鑰後，你不需要把具體值貼到對話裡。正常描述任務即可。

```text theme={null}
Use GitHub to check the latest failed workflow run and summarize what broke.
```

```text theme={null}
Use the Notion API to create a task list from this meeting summary.
```

Happycapy 可以知道這個環境變數存在，並根據 Description 理解它的用途。密鑰值會在介面中保持隱藏。

## 提示

不要把私密 token 直接貼到對話裡。

盡量使用清晰、標準的 key 名稱。很多工具會查找固定的環境變數名稱。

Description 要寫具體。說明服務、工具和預期用途。

刪除不再需要的密鑰。

如果某個工具找不到密鑰，檢查 key 名稱是否和工具期望的一致。

## 相關資源

* [CLI 工具](/zh-Hant/integrations/cli)：使用會從環境變數讀取憑證的命令列工具。
* [MCP](/zh-Hant/integrations/mcp)：透過 MCP 伺服器把 Happycapy 連接到外部工具和系統。
* [Files](/zh-Hant/features/files)：管理沙箱中的上傳檔案和產生輸出。