thClaws
← กลับสู่คู่มือ

บทที่ 27 — thClaws.cloud

บทที่ 27 · English

thClaws.cloud คือ catalog และ hosted runtime สำหรับ agent ของ thClaws ทำให้แนวคิด folder-คือ-agent (บทที่ 8) กลายเป็นของที่ browse ได้ publish ขึ้น catalog ได้ ติดตั้งลงเครื่องอื่นได้ หรือเช่า hosted workspace มารันก็ได้ จากมุมของ desktop thClaws การใช้ cloud จะรู้สึกเหมือน git สำหรับ AI agent — cloud login ครั้งเดียว แล้ว cloud publish จากโฟลเดอร์ไหนก็ได้ และ cloud get <slug> เพื่อ ติดตั้งงานของคนอื่นมาใช้

ขอบเขตของบทนี้ (ฝั่ง client เท่านั้น). การ browse catalog การ publish agent ของตัวเอง การติดตั้ง agent ลง folder และบล็อก agent.{name, description, uuid} ใน settings.json ส่วน runbook สำหรับการรัน catalog server เองอยู่ใน dev-plan/34 และ source tree thclaws-cloud/ ที่ workspace-private

โมเดล folder-คือ-agent — สรุปคร่าว ๆ

ในทุกที่ที่ thClaws รันได้ AI agent คือโฟลเดอร์ หนึ่ง โดยที่ราก ของโฟลเดอร์มี 3 ไฟล์หลัก:

  • AGENTS.md — คำสั่งของ agent (system prompt + persona)
  • manifest.json — metadata สำหรับ catalog (slug, license, icon, tag) ใช้เฉพาะตอนจะ publish
  • ./.thclaws/ — state ภายในเครื่อง (settings, KMS, session, memory)

เวลาคุณ cd เข้าไปใน folder นั้นแล้วรัน thClaws คือคุณ “รัน agent ตัวนั้น” เวลา publish catalog ก็จะแพ็คไฟล์เหล่านี้ทั้งหมดเป็น tarball เวลาคนอื่น cloud get <slug> เขาก็จะได้ folder เดียวกัน — cloud เป็น แค่ทางขนย้าย folder ระหว่างเครื่อง

ตั้งค่า URL catalog + CLI token

ของสองอย่างที่ผูก desktop เข้ากับ catalog server:

  1. Cloud URL — settings.json::cloud.url ค่า default คือ public instance (https://thclaws.cloud) จะ override ไปชี้ที่ http://localhost หรือ self-hosted instance ของตัวเองก็ได้
  2. CLI token — สตริง thc_… จากหน้า dashboard ของ catalog ถูก เก็บใน OS keychain (ไม่เคยอยู่ใน settings.json)

Desktop GUI

Settings → thClaws.cloud มีช่องให้ใส่ทั้งสองตัว วาง URL วาง token ที่ได้จากปุ่ม Mint CLI token ในหน้า dashboard แล้วกด Save — คำสั่ง ทุกอันในบทนี้ก็พร้อมใช้ทันที

CLI

$ thclaws cloud login                # ถาม token แบบ interactive
$ thclaws cloud login --token thc_xxxxx
$ thclaws cloud status               # แสดง URL ที่ resolve แล้ว + ว่ามี token หรือยัง
$ thclaws cloud logout               # ลืม token ที่เก็บไว้

cloud login รับ flag --cloud-url URL ด้วย หากต้องการ override URL โดยไม่ต้องแก้ settings.json

เปิดดู catalog

จาก REPL หรือ Chat tab:

❯ /cloud status
thClaws.cloud — https://thclaws.cloud (token: ✓ stored)

❯ /cloud list
- hello-world           v0.1.0  Hello-world demo agent (jimmy)
- legal-doc-reviewer    v0.4.2  Reviews contracts paragraph-by-paragraph (acme)
- weekly-research       v1.0.0  Saturday-morning newsletter writer (rin)
...

❯ /cloud list --mine
- weekly-research       v1.0.0  Saturday-morning newsletter writer (you)

จาก shell (ข้อมูลเดียวกัน เหมาะกับการเขียน script):

$ thclaws cloud list
$ thclaws cloud list --mine

แต่ละแถวคือ agent หนึ่งตัวใน catalog ส่วน slug คือสิ่งที่ต้องส่งให้ cloud get

ติดตั้ง agent ลง folder

❯ /cloud get hello-world
Downloading hello-world (v0.1.0) …
Extracted to /Users/jimmy/agents/hello-world/
  ✓ AGENTS.md
  ✓ manifest.json
  ✓ skills/greet.md
Done. cd hello-world && thclaws to run.

/cloud get (หรือ thclaws cloud get hello-world) จะ extract tarball ของ agent ลง current directory รูปแบบ CLI มี target dir เพิ่มได้:

$ thclaws cloud get hello-world ~/agents/hello-world

กลไก folder-safety

cloud get จะไม่ยอม overwrite folder ที่ไม่ว่าง ยกเว้นจะเป็น agent ตัว เดียวกัน (match ด้วย UUID ดูด้านล่าง) หรือใส่ --force กฎ เป็นแบบนี้:

สถานะของ folder ปลายทาง พฤติกรรม
ว่าง ติดตั้งใหม่
มี AGENTS.md / manifest.json และ agent.uuid ตรงกัน อัปเดตทับได้ — เก็บ .thclaws/ session state เดิมไว้
มี AGENTS.md / manifest.json แต่ UUID ไม่ตรง abort พร้อม error — folder นี้เป็นของ agent อื่น
มีไฟล์อื่น ๆ ที่ไม่เกี่ยวข้อง (note, scratch ฯลฯ) abort ยกเว้นจะใส่ --force

ออกแบบไว้แบบนี้โดยตั้งใจ — กันพิมพ์ผิดแล้วเขียนทับงานที่ทำค้างไว้ หรือ agent ของคนอื่นใน directory เดียวกัน

Publish agent

เวลาคุณสร้าง agent ใน folder หนึ่งและอยากให้มันขึ้น catalog:

$ cd ~/agents/my-research-bot
$ thclaws cloud publish              # อัปโหลด cwd
$ thclaws cloud publish --dry-run    # preview เนื้อหา tarball ไม่อัปโหลด
$ thclaws cloud publish ./other-dir  # publish folder อื่น

publish ทำ 3 อย่าง:

  1. Tar + gzip folder ทั้งก้อน — secret, session, KMS page และ directory ./.thclaws/ ถูกตัดออกอัตโนมัติ คุณ re-publish ทุกวันได้ โดยไม่ทำให้ประวัติแชทรั่ว
  2. Upload ขึ้น catalog ด้วย CLI token ของคุณ
  3. Stamp identity ของ agent กลับลง settings.json (ดูหัวข้อถัดไป)

ถ้า manifest.json หายหรือ invalid publish จะ abort พร้อม error ที่ชัด minimum field ที่ต้องมี: id, name, description, version

บล็อก agent identity ใน settings.json

บล็อก top-level agent ใน ./.thclaws/settings.json เก็บ identity ของ folder นี้บน catalog:

{
  "agent": {
    "id": "my-research-bot",
    "name": "My Research Bot",
    "description": "Saturday-morning newsletter writer",
    "uuid": "1f9c1d70-3a26-43c4-9c40-1b1b6e3e3a01"
  }
}
  • id / name / description — คัดลอกมาจาก manifest.json ตอน publish ใช้โดย catalog UI และโดย safety check ของ cloud get
  • uuid — assign โดย catalog ครั้ง แรก ที่ publish จาก folder นี้ แล้วเขียนกลับลง settings.json ครั้งต่อไปที่ publish จะไปลง catalog row เดิม (เพิ่ม version) UUID คือสิ่งที่ cloud get ใช้ match ว่า “folder นี้คือ agent ตัวเดียวกันมั้ย”

ปกติไม่ต้องแก้บล็อกนี้เอง GUI Settings → Agent identity มี panel ให้แก้ name / description (สะดวกก่อน publish — description จะไปโผล่ในรายการ catalog) แต่ตั้งใจซ่อน uuid ไว้

Fork agent ที่ดาวน์โหลดมา

ถ้า cloud get agent ของคนอื่นมาแล้วอยาก fork ในชื่อตัวเอง:

$ thclaws cloud unbind        # ล้าง settings.json::agent.uuid
$ # แก้ AGENTS.md, manifest.json — เปลี่ยน `id` เป็นชื่อที่ว่าง
$ thclaws cloud publish        # ได้ UUID ใหม่

ถ้าไม่ unbind ก่อน publish ครั้งต่อไปจะพยายาม update catalog row ของ เจ้าของเดิม (และจะ fail ด้วย permission error — catalog gate การ publish ตาม author)

Hosted workspace (เช่าแทนที่จะติดตั้ง)

ถ้าไม่อยากติดตั้ง agent บนเครื่อง laptop ตัวเอง catalog ก็รัน agent เป็น hosted workspace ให้ได้ — หนึ่ง container ต่อหนึ่ง workspace มี URL ให้เปิดในเบราว์เซอร์ มี chat UI จริงที่ backend ใช้ engine ตัวเดียวกับที่คุณรันใน local

จาก web UI ของ catalog:

  1. browse ไปหน้า detail ของ agent
  2. กด Install on hosted
  3. catalog จะ spin up workspace คัดลอกไฟล์ของ agent เข้าไป แล้ว redirect ไป chat UI ที่ /u/<handle>/<slug>/

Hosted workspace รองรับทั้ง BYOK (วาง provider key เองที่ Settings → Hosted keys) และ thClaws.cloud gateway (proxy แบบ pay-per-use ที่มี credit billing ดูด้านล่าง) ตอนสร้าง workspace มี radio toggle ให้เลือก

Gateway แบบ pay-per-use (ทางเลือกแทน BYOK)

สำหรับผู้ใช้ที่ไม่อยาก manage account ของ Anthropic / OpenAI / Gemini เอง thClaws.cloud มี gateway ให้ — เติม credit ครั้งเดียวแล้ว เรียก model อะไรก็ได้ผ่าน gateway.thclaws.cloud/<provider>/... โดย ใช้ token gw_v1_… Gateway จะ forward ไป upstream meter response แล้วหักจาก balance

วิธีใช้ gateway จาก thClaws desktop:

  1. mint gateway access key ใน catalog UI: /gateway/keys → Mint new gateway key → copy สตริง gw_v1_…
  2. เติม credit: /credit → เลือก pack ($5 / $20 / $100) pack ใหญ่ มี bonus credit
  3. ตั้งให้ thClaws ชี้ไปที่ gateway: bash export ANTHROPIC_API_KEY=gw_v1_… export ANTHROPIC_BASE_URL=https://thclaws.cloud/gateway/anthropic export OPENAI_API_KEY=gw_v1_… export OPENAI_BASE_URL=https://thclaws.cloud/gateway/openai/v1 # …ทำเหมือนกันกับ GEMINI_*, OPENROUTER_* (หรือใช้ช่อง *_API_KEY / *_BASE_URL ใน GUI Settings → Providers ก็ได้)
  4. รัน thClaws ตามปกติ call จะไปผ่าน gateway ค่าใช้จ่ายโผล่ใน /credit/usage

สำหรับ workspace hosted gateway จะถูก wire ให้อัตโนมัติเมื่อเลือก Gateway ตอนสร้าง workspace — runner จะได้ env var ที่ inject ให้ แล้วโดยไม่ต้อง copy-paste

Tier gating ของ model

Model ถูกแบ่งเป็น 3 tier — starter, pro, enterprise ค่า model_tier ของ account (ตั้งใน catalog dashboard) ควบคุมว่า gateway จะยอมรับ model ใดบ้าง Account starter จะได้ Haiku / gpt-4o-mini / Gemini Flash ส่วนการเรียก Sonnet ด้วย starter account จะคืน 403 จาก gateway พร้อมลิงก์ upgrade Tier กับ balance แยกกัน — มี credit $100 ก็ไม่ได้ปลด enterprise model ให้ starter account

สรุปอ้างอิงคำสั่ง

คำสั่ง ที่ใช้ ทำอะไร
thclaws cloud login [--token …] CLI เก็บ CLI token ลง keychain
thclaws cloud logout CLI ลืม token ที่ cache ไว้
thclaws cloud status CLI / /cloud status แสดง URL ที่ resolve + state ของ token
thclaws cloud list [--mine] CLI / /cloud list browse catalog
thclaws cloud get <slug> [<dir>] [--force] CLI / /cloud get ติดตั้งลง folder
thclaws cloud publish [<dir>] [--dry-run] CLI อัปโหลดจาก folder
thclaws cloud unbind CLI ล้าง agent.uuid ให้ publish ครั้งต่อไปสร้าง row ใหม่ใน catalog
Settings → thClaws.cloud GUI URL + CLI token
Settings → Agent identity GUI แก้ agent.name / description ของ folder นี้
/credit (web) Catalog UI เติม credit + ดู balance + ดูราคา model
/gateway/keys (web) Catalog UI mint access key gw_v1_…
/credit/usage (web) Catalog UI ค่าใช้จ่ายรายการ + แยกตาม workspace

thClaws.cloud ไม่ใช่อะไร

ตั้งความคาดหวังเรื่องสำคัญสองสามข้อ:

  • ไม่ใช่ที่ host model Agent ใน catalog ยังคงเรียก inference จาก Anthropic / OpenAI / Gemini อยู่ — ผ่านทั้ง BYOK key ของคุณเอง หรือ cloud gateway ในฐานะ proxy เก็บเงิน thClaws.cloud ไม่ได้ train หรือ serve LLM เอง
  • ไม่ใช่ที่เก็บ session ประวัติแชทยังคงอยู่ใน ./.thclaws/sessions/ บนเครื่องที่ run agent ตัวนั้น cloud เก็บ ไฟล์ agent ไม่ใช่ประวัติบทสนทนา
  • ไม่จำเป็นต้องใช้ ทุกบทก่อนหน้าบทนี้ทำงานได้โดยไม่ต้องใช้ network เลย cloud เป็นของเสริม — ติดตั้ง thClaws เขียน AGENTS.md ก็ได้ agent ใช้งานได้แล้วโดยไม่ต้องสมัครอะไร