# Telegram · บรรทัดคำสั่ง

Canonical page: https://phishdestroy.io/tgwitness/th/docs/reference/cli/

ค้นหา อ่านบริบท นับกิจกรรม และส่งออกข้อความที่บันทึกไว้จากสคริปต์และเอเจนต์ ด้วยผลลัพธ์ --json รหัสออกที่เสถียร และโทเค็นอ่านอย่างเดียวที่มีขอบเขต

[Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/)

[Documentation index](https://phishdestroy.io/tgwitness/th/llms.txt)

Translation coverage: this edition includes material from the English original.

ค้นหา อ่านบริบท นับกิจกรรม และส่งออกข้อความที่บันทึกไว้จากสคริปต์และเอเจนต์ ด้วยผลลัพธ์ --json รหัสออกที่เสถียร และโทเค็นอ่านอย่างเดียวที่มีขอบเขต

[TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [เอกสารประกอบ](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md)

![การบูรณาการกับระบบเก็บถาวร](https://phishdestroy.io/tgwitness/assets/chapter-integrations.svg?v=367d9d210074)

[MCP แบบอ่านอย่างเดียว](https://phishdestroy.io/tgwitness/th/docs/reference/mcp/) · [การค้นหาข้อความเต็ม](https://phishdestroy.io/tgwitness/th/docs/reference/search/) · [Wiki](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md)

**Preview.** `tgwitness search`, `context`, `messages`, `stats` and `export` read saved observations for scripts and AI agents. They cannot send anything to Telegram, change settings or modify the signed journal. `tgwitness index` and `tgwitness backup` ([below](https://phishdestroy.io/tgwitness/th/docs/reference/cli/#index-and-backup)) work on a local data directory and need no token.

โดยใช้ `--json`, stdout ส่งเอกสาร JSON เพียงหนึ่งชิ้นเท่านั้น (`export` เขียน JSON Lines). ความคืบหน้า คำแนะนำ และข้อผิดพลาดจะถูกส่งไปยัง stderr รหัสออก (exit codes) มีความเสถียร:

| โค้ด | ความหมาย |
| --- | --- |
| `0` | ผลลัพธ์ที่สำเร็จ รวมถึงผลลัพธ์ที่ว่าง |
| `1` | ข้อผิดพลาด: แผงควบคุมไม่สามารถเข้าถึงได้, ข้อมูลอ่านไม่ได้, การส่งออกถูกขัดจังหวะ |
| `2` | ข้อผิดพลาดในการใช้งานหรือคำขอไม่ถูกต้อง: วันที่ไม่ถูกต้อง, ตัวเลือกไม่รู้จัก, ดัชนีการค้นหาไม่ตรง |
| `3` | ไม่สามารถใช้งานได้ในขณะนี้: พื้นที่ทำงานเปิดอยู่ในแผงที่ทำงานอยู่ หรือแผงนั้นขอให้ลองใหม่ในภายหลัง (ข้อจำกัดอัตรา, เวลารอหมด) |
| `4` | การเข้าถึงถูกปฏิเสธ: โทเค็นขาดหาย หมดอายุ หรือถูกเพิกถอน การสนทนาอยู่นอกขอบเขต หรือเครื่องมือที่ไม่อนุญาต |

## สองวิธีในการอ่าน

**ผ่านแผงควบคุม (`--url`)** คำสั่งนี้ใช้ API การเก็บถาวรแบบจำกัดขอบเขตเดียวกันกับ MCP. สร้างการเชื่อมต่อใน **More tools → Integrations → MCP**: เลือกพื้นที่ทำงานและแชท, เครื่องมือและระยะเวลาหมดอายุ แล้วคัดลอกโทเค็นหนึ่งครั้ง การเชื่อมต่อนี้เป็นแบบอ่านอย่างเดียว จำกัด เฉพาะแชทเหล่านั้น จำกัดอัตราที่60 คำขอต่อนาที และสามารถเพิกถอนหรือ หมุนเวียนได้ตลอดเวลา โทเค็นการเข้าสู่ระบบของแผงควบคุมและข้อมูลรับรอง Telegram ไม่สามารถใช้งานได้ที่นี่

```
export TGWITNESS_URL=https://panel.example.org      # default http://127.0.0.1:8787
export TGWITNESS_MCP_TOKEN=tgw_mcp_...              # or --token-file path
tgwitness search 'перевод карта' --json
```

แผงควบคุมระยะไกลต้องใช้ HTTPS; HTTP แบบธรรมดาจะได้รับการยอมรับเฉพาะสำหรับ `127.0.0.1`, `localhost` และ `::1`. ตัวแปรสภาพแวดล้อมของพร็อกซีจะถูกเพิกเฉย และการเปลี่ยนเส้นทางจะถูก ปฏิเสธ ดังนั้น โทเค็นจะส่งถึงเฉพาะที่อยู่ที่คุณระบุเท่านั้น

**โดยตรงจากพื้นที่ทำงานที่ถูกหยุด (`--data-dir`)** อ่านไดเรกทอรีข้อมูลด้วย สิทธิ์การเข้าถึงท้องถิ่นอย่างเต็มรูปแบบ โดยไม่ต้องใช้โทเค็น ใช้กับสำเนาของไดเรกทอรีข้อมูล หรือในขณะที่ การเก็บข้อมูลถูกหยุด บันทึกที่ลงนามจะไม่ถูกเปลี่ยนแปลงเลย; เช่นเดียวกับแผงควบคุม การเปิด พื้นที่ทำงานอาจทำให้ดัชนีที่สร้างขึ้นจากพื้นที่ทำงานนั้นอัปเดตเป็นเวอร์ชันล่าสุด เมื่อแผงควบคุมเปิดพื้นที่ทำงานไว้ คำสั่งจะออกด้วย รหัส `3`; ให้อ่านผ่านแผงควบคุมแทน หากไม่มี `--data-dir`, `TGWITNESS_DATA`, `./data/live` หรือจะใช้ไดเรกทอรีข้อมูลของระบบที่กำลังรันคำสั่งนี้

`--workspace ID` เลือกพื้นที่ทำงาน (ค่าเริ่มต้น `default`). `tgwitness messages
--workspaces` แสดงรายการพื้นที่ทำงานที่คุณสามารถอ่านได้

## คำสั่ง

| คำสั่ง | ผลลัพธ์ |
| --- | --- |
| `tgwitness search QUERY [--chat ID] [--since] [--until] [--any] [--limit N] [--offset N]` | แสดงผลลัพธ์ที่ตรงกันมากที่สุดก่อน โดยพิจารณาจากรูปแบบคำ วลีที่ตรงกันในเครื่องหมายคำพูด โดเมน และ `@username` ([ไวยากรณ์](https://phishdestroy.io/tgwitness/th/docs/reference/search/#search-syntax)) |
| `tgwitness search QUERY --exact [--before SEQ]` | ข้อความตามต้นฉบับ โดยเรียงตามลำดับจากใหม่ที่สุดไปก่อน โดยไม่รวมดัชนี |
| `tgwitness context CHAT_ID MESSAGE_ID [--limit N] [--before SEQ]` | ข้อความที่บันทึกไว้ภายใน 10 ID ข้อความ ทั้งด้านหน้าและด้านหลัง |
| `tgwitness messages [--limit N] [--offset N]` | การสนทนาที่คุณสามารถอ่านได้ |
| `tgwitness messages CHAT_ID [--since] [--until] [--limit N] [--before SEQ]` | ข้อความที่บันทึกไว้จากการสนทนา โดยเรียงตามลำดับจากใหม่ที่สุดก่อน |
| `tgwitness messages CHAT_ID --message ID` | ทุกเวอร์ชันที่บันทึกไว้และบันทึกการลบของข้อความหนึ่งข้อความ |
| `tgwitness stats [--chat ID] [--sender ID] [--since] [--until] [--top N]` | สถิติกิจกรรม, ด้านล่าง |
| `tgwitness export [--chat ID] [--since] [--until] [--output FILE]` | บันทึกข้อมูลการสังเกตการณ์ในรูปแบบ JSON Lines ตามลำดับในบันทึก |

วันที่คือ `2026-10-01` (เที่ยงคืน UTC) หรือเวลา ISO พร้อมเขตเวลา, `2026-10-01T09:00+03:00`. สำหรับ `search`, `messages` และ `export` พวกเขาเลือก เวลาการสังเกตการณ์ หน้าหนึ่งสามารถเก็บได้สูงสุด 50 รายการ: ทำตาม `next_offset` (`--offset`) เพื่อ ค้นหาตามอันดับและ `next_before` (`--before`) ที่อื่น ๆ

Ranked search stops at 1,000 results. The final page may be shorter than `--limit`. When more observations match, the last page says so (`truncated: true` with `--json`); narrow the query, chat or period.

ทุกผลลัพธ์ข้อความจะมี `untrusted_content: true` , พื้นที่ทำงาน, ID การสนทนาและ ID ข้อความ, ลำดับบันทึก, ค่าแฮชของบันทึกที่เก็บไว้ และลิงก์ไปยังแผงควบคุม การแก้ไข, การแจ้งเตือนการลบ และ `missing_on_recheck` เป็นบันทึกที่แยกต่างหาก ข้อมูลใน `stats` แสดงช่วงเวลาที่ผลการค้นหาครอบคลุม

### สถิติกิจกรรม

`stats` นับจำนวนข้อมูลการสังเกตที่บันทึกไว้สำหรับแชทหนึ่งแชท ผู้ส่งหนึ่งคน หรือทุกแชทในขอบเขต:

- ข้อความตามชั่วโมง UTC และตามวันในสัปดาห์ (เริ่มจากวันจันทร์), ชั่วโมงและวันที่คึกคักที่สุด;
- แก้ไข, ลบ และ `missing_on_recheck` แชร์;
- ผู้ส่ง พร้อมด้วยจำนวนข้อความ และเวลาส่งข้อความแรกและสุดท้าย;
- โดเมนที่ปรากฏบ่อยที่สุดและ `@handles`, นับครั้งเดียวต่อข้อความใน ทุกเวอร์ชันที่บันทึกไว้;
- ขอบเขต: `coverage.gap` บันทึก และ เพื่อเข้าถึงพื้นที่ทำงานทั้งหมด ให้ระบุช่วงเวลา ที่ไม่มีสัญญาณชีพจากตัวเก็บข้อมูลที่เชื่อมต่อ (`collector_liveness`).

ช่วงเวลาดังกล่าวใช้เพื่อเลือก**เวลาส่งข้อความที่ Telegram รายงาน** การนับชั่วโมงและวันในสัปดาห์ ช่วยประมาณเขตเวลาของผู้ส่ง ตัวเลขถูกคำนวณตาม คำขอจากบันทึกและไม่ถูกเก็บไว้ ผลลัพธ์แต่ละรายการระบุชื่อหัวบันทึกที่ ครอบคลุมเมื่อการเข้าถึงของคุณครอบคลุมพื้นที่ทำงาน การอ่านจะหยุดลงหลังจาก 5 วินาทีผ่าน แผงควบคุม หรือ `--timeout` วินาทีในระบบท้องถิ่น (ค่าเริ่มต้น 30); หลังจากนั้น `complete` จะเป็น false และ `partial` จะระบุชื่อบันทึกแรกที่ยังไม่ได้อ่าน ในกรณีนี้ จะนับเฉพาะบันทึกที่ใหม่ที่สุดเท่านั้น

### ส่งออก

`export` บันทึก JSON หนึ่งอ็อบเจ็กต์ต่อข้อมูลการสังเกตที่บันทึกไว้ (ข้อความใหม่, ภาพถ่ายหน้าจอ, การแก้ไข, ข้อความที่กู้คืนได้, แจ้งเตือนการลบ, `missing_on_recheck` และบันทึกสื่อที่เก็บไว้ ตามลำดับในบันทึก แต่ละบรรทัดมีฟิลด์เดียวกันกับผลลัพธ์อื่น ๆ พร้อม ข้อความเต็ม ด้วย `--output`, ไฟล์จะถูกเขียนภายใต้ชื่อ `.partial` ชื่อ และ จะเปลี่ยนชื่อได้ก็ต่อเมื่อบันทึกการเสร็จสิ้นของคณะกรรมการ; การส่งออกที่ถูกขัดจังหวะจะไม่ทิ้ง ไฟล์ไว้และจะออกด้วยรหัส `1`. `--output` ไม่เคยเขียนทับไฟล์ที่มีอยู่ ด้วย `--output` และ `--json`, stdout จะแสดงสรุป: จำนวนบันทึก, ลำดับวารสาร ล่าสุด และสำหรับสิทธิ์เข้าถึงพื้นที่ทำงานทั้งหมด จะแสดงส่วนหัวของวารสาร

การส่งออกผ่านแผงควบคุมต้องการการเชื่อมต่อที่อนุญาตให้ส่ง**ข้อความ Export (เฉพาะบรรทัดคำสั่ง)** ; ตัวเลือกนี้ไม่ถูกเลือกไว้เป็นค่าเริ่มต้น ไฟล์นี้เป็นสำเนาทำงาน; สำหรับการส่งต่อที่สามารถตรวจสอบได้ ให้ใช้การส่งออกที่ลงนามในส่วน **Exports** ซึ่งสามารถตรวจสอบได้โดยคำสั่ง `python -m tgwitness.verify`

แผงควบคุมจะตรวจสอบสิทธิ์การเข้าถึงอีกครั้งก่อนส่งแต่ละบันทึก รวมถึงบันทึก การเสร็จสิ้นด้วย สิทธิ์การเข้าถึงที่ถูกเพิกถอนหรือหมดอายุจะทำให้การส่งออกไม่สมบูรณ์ การอ่านหน้าแบบ Lazy จะแบ่งปันขีดจำกัดของ archive worker กับคำขออื่นๆ และมีเวลารอที่จำกัด

### Index and backup

These two commands read the data directory directly and take no token or `--url`.

| คำสั่ง | ผลลัพธ์ |
| --- | --- |
| `tgwitness index status [--workspace ID] [--data-dir DIR] [--json]` | Search index state of one workspace or, by default, every workspace: mode, `ready`, `building` or `not built`, indexed and journal head sequence. Works while the panel runs |
| `tgwitness index rebuild [--workspace ID] [--data-dir DIR] [--json]` | Rebuilds the index from the first journal record. Rewrites only the derived index, never the signed journal. Exits with code `3` while the panel has the workspace open. Nothing is built when the workspace keeps its index in memory or has search off |
| `tgwitness backup FOLDER [--data-dir DIR] [--json]` | Copies the whole data directory into a new or empty folder outside it while the panel keeps running, and writes `backup-manifest.json` with every file's SHA-256 and the journal heads |

`index` accepts `--workspace default` or a workspace ID; the default is `all`. The backup skips temporary exports, SQLite sidecar files and lock files. The folder holds the Telegram session and signing keys, so keep it as private as the data directory. [Backup, restore, and capacity](https://phishdestroy.io/tgwitness/th/docs/reference/deployment/#backup-restore-and-capacity) describes restoring and what the next start records.

## ทักษะของเอเจนต์

[`.agents/skills/tgwitness-cli/SKILL.md`](https://github.com/phishdestroy/TgWitness/blob/main/.agents/skills/tgwitness-cli/SKILL.md) อธิบายให้เอเจนต์ทราบวิธีใช้คำสั่งเหล่านี้ วิธีอ้างอิงบันทึก และวิธีจัดการ กับข้อความที่บันทึกไว้ เอเจนต์ที่อ่าน `.agents/skills` โหลดมันจาก repositori ที่ checkout แล้ว สำหรับ Claude Code ให้คัดลอก `tgwitness-cli` folder ไปยัง `.claude/skills/` ใน โครงการของคุณ หรือ `~/.claude/skills/`.

## MCP และบรรทัดคำสั่ง

ทั้งสองใช้การเชื่อมต่อ การตรวจสอบขอบเขต และข้อจำกัดเดียวกัน ผลลัพธ์ของ MCP ถูกจำกัดไว้ที่ หน้าเดียวขนาด 64 KiB ดังนั้น MCP จึงไม่รองรับการส่งออกข้อมูลแบบจำนวนมาก; ส่วนการส่งข้อมูลผ่านบรรทัดคำสั่งจะส่งข้อมูลแบบสตรีม `get_activity_stats` มีให้ใช้ได้กับทั้งสองระบบ
