# Craft Agent

來源: https://docs.aicentos.com/zh-TW/clients/craft-agent

Language: zh-TW

> 在 Craft Agent 裡接入 aicentos —— 自訂 OpenAI 相容連線，桌面端與 craft-cli 通用

Craft Agent 的 LLM 連線支援 `Custom` 類型，官方描述是「任意 URL，任意 OpenAI 相容或 Anthropic 相容端點」。把 Base URL 指向 aicentos，桌面端和 `craft-cli` 都能走。

## 準備工作

先在控制台為 Craft Agent 建一個專用 Key（建議命名 `craft-agent`），方便按 Key 查看用量。

* 控制台：[https://aicentos.com](https://aicentos.com)
* 建立 Key：[https://aicentos.com/keys](https://aicentos.com/keys)
* 錢包儲值：[https://aicentos.com/wallet](https://aicentos.com/wallet)

安裝桌面端：

```bash
curl -fsSL https://thecraftagents.com/install-app.sh | bash
```

也支援 headless server 與純命令列用法。

## 需要填寫的設定

| 欄位       | 值                                                                          |
| -------- | -------------------------------------------------------------------------- |
| 連線類型     | Custom（自訂）                                                                 |
| 協議       | `openai-completions`，或 `anthropic-messages`                                |
| Base URL | `https://aicentos.com/v1`（OpenAI 相容）/ `https://aicentos.com`（Anthropic 相容） |
| API Key  | 控制台建立的 Key                                                                 |
| 模型       | 控制台「模型廣場」中的模型名                                                             |

## 設定步驟

桌面端：打開設定裡的 LLM 連線，新增一條，類型選 Custom，按上表填寫。

命令列等價寫法：

```bash
export AICENTOS_API_KEY="sk-你的-API-Key"
craft-cli run --provider openai \
  --base-url https://aicentos.com/v1 \
  --api-key "$AICENTOS_API_KEY" \
  --model 你的模型名 \
  "你好"
```

也可以直接改設定檔 `~/.craft-agent/config.json`：

```json
{
  "llmConnections": [
    {
      "providerType": "pi_compat",
      "baseUrl": "https://aicentos.com/v1",
      "customEndpoint": { "api": "openai-completions" },
      "models": [{ "id": "你的模型名" }],
      "defaultModel": "你的模型名"
    }
  ]
}
```

金鑰不寫在明文設定裡，存在同目錄的 `credentials.enc`。用介面填一次即可，不要手改這個檔案。

## 測試

```bash
craft-cli run --provider openai \
  --base-url https://aicentos.com/v1 \
  --api-key "$AICENTOS_API_KEY" \
  --model 你的模型名 \
  "用一句话自我介绍"
```

能正常返回即通。再回控制台看用量，確認請求記到了這個 Key 上。

## 注意事項

* `providerType` 保持 `pi_compat`，這是它的自訂端點識別；改成內建 provider 的名字會走官方模型。
* `models` 要手填，它不會自動拉模型列表。名字必須與控制台「模型廣場」完全一致（參考 [支援的模型](https://docs.aicentos.com/zh-TW/billing/models-list)）。
* 走 Anthropic 相容端點時 Base URL 是 `https://aicentos.com`，不帶 `/v1`，`--provider` 改成 `anthropic`。
* 桌面端的選單位置隨版本變化，找不到時以 `config.json` 的寫法為準。

## 相關連結

* [Craft Agents 文件](https://thecraftagents.com/docs)
* [craft-agents 儲存庫](https://github.com/craft-ai-agents/craft-agents-oss)