Skip to content

README.th.md

Latest commit

 

History

History
689 lines (557 loc) · 48.9 KB

README.th.md

File metadata and controls

689 lines (557 loc) · 48.9 KB
Raw
Coding Agent Telegram

Claude Code / Codex / Copilot Coding Agent Telegram 🚀

English | Deutsch | Français | 日本語 | 한국어 | Nederlands | ไทย | Tiếng Việt | 简体中文 | 繁體中文（香港） | 繁體中文（台灣）

เบา รองรับหลายบอต หลายเซสชัน หลายงาน พร้อม AI Coding Agent ทำงานได้ 24/7

ควบคุม AI Coding Agent ที่รันในเครื่องของคุณจากที่ไหนก็ได้ผ่าน Telegram

Experimental MIT License Latest Release Python 3.9+

✨ ทำไมถึงควรใช้

  • ✅ เบา: ไม่ต้องใช้เฟรมเวิร์กหนัก ๆ และตรวจสอบการทำงานได้ง่าย
  • ✅ หลายบอต: รองรับหลายแชต หลายเซสชัน
  • ✅ ใช้ Telegram เพื่อควบคุม Codex / Copilot / Claude Code CLI
  • ✅ ตรวจคำตอบและไฟล์ที่ถูกแก้ได้ง่ายใน code block
  • ✅ ส่งคำถามต่อคิวไว้ได้ระหว่างที่ agent กำลังทำงาน
  • ✅ รองรับ ✏️ ข้อความ, 🌄 รูปภาพ และ 🎙️ ข้อความเสียง

🔁 สลับอุปกรณ์และเซสชันได้ลื่นไหล

เริ่มเซสชันจาก Telegram แล้วค่อยกลับไปทำต่อบนคอมพิวเตอร์ด้วยเซสชัน Codex/Copilot/Claude Code CLI เดิมได้ทันที และใช้ /switch เพื่อสลับกลับไปมาระหว่าง Telegram กับ command line ได้อย่างง่ายดาย

  • ใช้ /switch เพื่อทำงานต่อจากเซสชันในเครื่อง
  • รองรับเซสชันย้อนหลัง

🛠️ ตัวอย่าง flow การใช้งานบนเครื่อง

coding-agent-telegram # หรือรัน ./startup.sh
ใน Telegram:
/project my-project
/new
Fix the failing API test in the current project

→ ติดตั้งด้วยคำสั่งบรรทัดเดียว:

curl -fsSL https://raw.githubusercontent.com/daocha/coding-agent-telegram/main/install.sh | bash

🔐 ความปลอดภัย

  • กำหนด whitelist สำหรับแชตส่วนตัวด้วย ALLOWED_CHAT_IDS

  • อนุญาตให้มี agent ที่ทำงานอยู่ได้เพียงหนึ่งตัวต่อหนึ่ง project เพื่อลดการเขียนทับกัน

  • ซ่อน diff ของไฟล์ที่มีข้อมูลอ่อนไหว

  • ปิดบัง API keys, tokens, ค่าใน .env, certificates, SSH keys และข้อมูลลักษณะใกล้เคียงกับความลับก่อนส่งกลับไปที่ Telegram

  • ข้อมูล runtime ของแอปเก็บไว้ใต้ ~/.coding-agent-telegram

  • โฟลเดอร์ที่มีอยู่เดิมอาจต้องยืนยัน trust ก่อนทำ Git operation ที่มีการแก้ไข

  • เซิร์ฟเวอร์ไม่มีการเรียกใช้งานภายนอกแบบซ่อน ทุกอย่างยังอยู่ในการควบคุมของคุณ

  • ทำงานร่วมกับ Codex Sandbox mode ได้ดี โดยไม่ต้องให้สิทธิ์ danger-full-access

  • การเชื่อมต่อกับ Claude Code รองรับการกำหนด permission mode และรายการ allow/deny ของ tools ได้

✅ สิ่งที่ต้องมี

ก่อนเริ่มเซิร์ฟเวอร์ โปรดเตรียม:

🦞 ถ้ามี Openclaw อยู่แล้ว ทำไมยังต้องใช้ตัวนี้?

Openclaw มีความสามารถครบมาก และมี agent loop แบบรวมมาให้แล้วชื่อ Pi-Agent เหมาะกับ use case ที่หลากหลายกว่า ผมเองก็ชอบ Openclaw และเคยใช้มันเขียนโค้ดเหมือนกัน แต่สำหรับ coding โดยตรง มันไม่ใช่ตัวเลือกที่ดีที่สุดเสมอไป เพราะมี system prompt ขนาดใหญ่และ context ที่ติดมาด้วยมากกว่า Claude Code / Codex / Copilot จึงมักทำงานด้าน coding ได้มีประสิทธิภาพกว่า แม่นยำกว่า ตรงประเด็นกว่า และเสียสมาธิน้อยกว่า โปรเจ็กต์นี้ตั้งใจให้เรียบง่ายมาก โดยเชื่อมต่อกับ Codex / Copilot / Claude Code CLI เท่านั้น ดังนั้นคุณจึงมอบหมายงานให้ Codex / Copilot / Claude Code ทำได้โดยตรง

🆚 ทำไมฉันจึงต้องใช้ coding-agent-telegram หากมี Claude Code + Telegram Plugin อยู่แล้ว?

ความสามารถ Claude Code + Telegram Plugin อย่างเป็นทางการ coding-agent-telegram (รองรับ Claude)
แชทกับ AI ผ่าน Telegram ✅ ✅
แก้ไขโค้ดในเครื่องและรันคำสั่ง ✅ ✅
ต้องมี CLI session ที่กำลังทำงานอยู่ก่อน ใช่ ไม่ใช่ (เริ่มต้นหรือกลับมาใช้ session เดิมโดยอัตโนมัติ)
รองรับผู้ให้บริการ AI หลายราย ❌ รองรับเฉพาะ Claude ✅ Claude Code, Codex CLI, GitHub Copilot CLI
จัดการโปรเจกต์ผ่าน Telegram ❌ ✅ /project
จัดการ Branch ผ่าน Telegram ใช้คำสั่ง Git ด้วยตนเอง ✅ เวิร์กโฟลว์ /branch
สร้างและสลับ Session จำกัดเฉพาะ Claude session ที่กำลังใช้งาน ✅ /new, /switch, /current, /compact
กลับมาใช้ Local CLI session ที่มีอยู่ ❌ ✅
ใช้งาน Session ต่อเนื่องข้ามอุปกรณ์ มีข้อจำกัด ✅
ป้องกันการแก้ไข Workspace พร้อมกัน ❌ ✅ ป้องกันไม่ให้หลาย Agent แก้ไขโปรเจกต์เดียวกันพร้อมกัน
คิวงานเมื่อ Agent กำลังทำงาน ❌ ✅
Snapshot และ Diff ของระบบไฟล์แบบอิสระ ❌ ✅
ดู Diff ของไฟล์แบบมีโครงสร้างใน Telegram ❌ ✅
กรอง Secrets และ Diff ที่มีข้อมูลสำคัญ ❌ ✅
เวิร์กโฟลว์ Git ในตัว (pull / push / commit) ทำด้วยตนเอง ✅
รองรับหลาย Bot ต้องรันหลายอินสแตนซ์ ✅ จัดการด้วยเซิร์ฟเวอร์เดียว
การจัดการสถานะในระดับโปรเจกต์ ❌ ✅
สถาปัตยกรรมที่ไม่ผูกกับผู้ให้บริการรายใด ❌ ✅

ความแตกต่างที่สำคัญ

Telegram Plugin อย่างเป็นทางการของ Claude Code เชื่อม Telegram เข้ากับ Claude Code session ที่กำลังทำงานอยู่เพียงหนึ่ง session

coding-agent-telegram ทำหน้าที่เป็น Telegram Control Plane สำหรับจัดการโปรเจกต์, Branch, Session, เวิร์กโฟลว์ Git และ Coding Agent หลายตัว (Claude Code, Codex CLI และ GitHub Copilot CLI) ผ่านอินเทอร์เฟซเดียว

🏛️ สถาปัตยกรรม

Claude Code + Telegram Plugin

Telegram
    │
    ▼
Claude Code Channel
    │
    ▼
Claude Code Session ที่กำลังทำงานอยู่

coding-agent-telegram

Telegram
    │
    ▼
coding-agent-telegram
    │
    ├── Claude Code
    ├── Codex CLI
    └── GitHub Copilot CLI
           │
           ▼
โปรเจกต์ • Branch • Session • คิวงาน • Git • Diff • ตัวกรอง Secrets

🚀 เริ่มต้นอย่างรวดเร็ว

วิธีที่ A: สคริปต์ bootstrap แบบบรรทัดเดียว

curl -fsSL https://raw.githubusercontent.com/daocha/coding-agent-telegram/main/install.sh | bash

วิธีที่ B: ติดตั้งจาก PyPI ด้วย pip

pip install coding-agent-telegram
coding-agent-telegram

วิธีที่ C: รันจาก repository ที่ clone มา

git clone https://github.com/daocha/coding-agent-telegram
cd coding-agent-telegram
./startup.sh

🌐 เริ่ม Bot Server

ครั้งแรกแอปจะสร้างไฟล์ env และบอกว่าต้องกรอกค่าใดบ้าง
หลังแก้ไฟล์ env แล้ว ให้รันอีกครั้ง:
# หากคุณทำตามวิธีที่ A หรือ วิธีที่ B ให้รัน
coding-agent-telegram

# หากคุณทำตามวิธีที่ C ให้รันสิ่งนี้อีกครั้ง
./startup.sh

🎙️ [ทางเลือก] ฟีเจอร์เสียงเป็นข้อความ: เตรียมส่วนที่ OpenAI-Whisper ต้องใช้ในเครื่อง

ส่วนนี้ใช้เปิดการแปลงข้อความจากข้อความเสียง Telegram ด้วย Whisper แบบโลคัลตามตัวเลือกของคุณ ไฟล์เสียงถูกจำกัดไว้ที่สูงสุด 20 MB

# ถ้าติดตั้งด้วย pip
coding-agent-telegram-stt-install

# ถ้าใช้งานจาก repository ที่ clone มา
./install-stt.sh

ค่า env ที่แนะนำ:

ENABLE_OPENAI_WHISPER_SPEECH_TO_TEXT=true
OPENAI_WHISPER_MODEL=base
OPENAI_WHISPER_TIMEOUT_SECONDS=120

หมายเหตุ:

  • Whisper จะดาวน์โหลดโมเดลที่เลือกโดยอัตโนมัติครั้งแรกไปยัง ~/.cache/whisper
  • หากเลือก OPENAI_WHISPER_MODEL=turbo การถอดข้อความจากเสียงครั้งแรกมีโอกาสหมดเวลามากขึ้น ขณะ large-v3-turbo.pt ยังดาวน์โหลดไม่เสร็จ
  • หลังจากถอดข้อความจากเสียงแล้ว บอตจะส่งข้อความที่รู้จำได้กลับไปใน Telegram ก่อน แล้วจึงส่งต่อให้เอเจนต์ เพื่อช่วยตรวจสอบความคลาดเคลื่อนของการรู้จำ

🔑 ตั้งค่า Telegram

รับ Bot Token

  1. เปิด Telegram และเริ่มแชตกับ @BotFather
  2. ส่ง /newbot
  3. ทำตามขั้นตอนเพื่อกำหนด:
    • ชื่อที่แสดง
    • ชื่อผู้ใช้ bot ที่ลงท้ายด้วย bot
  4. BotFather จะส่ง HTTP API token กลับมา
  5. นำ token นี้ไปใส่ใน TELEGRAM_BOT_TOKENS ภายใน ~/.coding-agent-telegram/.env_coding_agent_telegram

รับ Chat ID

วิธีที่เชื่อถือได้ที่สุดคือใช้ Telegram getUpdates API พร้อม bot token ของคุณเอง

  1. เริ่มแชตกับบอตของคุณแล้วส่งข้อความ เช่น /start
  2. เปิด URL นี้ในเบราว์เซอร์ โดยแทนที่ <BOT_TOKEN>:
https://api.telegram.org/bot<BOT_TOKEN>/getUpdates
  1. หา object chat ใน JSON response
  2. คัดลอกค่า id ที่เป็นตัวเลข
  3. นำค่านี้ไปใส่ใน ALLOWED_CHAT_IDS ภายใน ~/.coding-agent-telegram/.env_coding_agent_telegram

หมายเหตุ:

  • สำหรับแชตส่วนตัว chat ID มักเป็นจำนวนเต็มบวก
  • หาก getUpdates คืนค่ากลับมาเป็นค่าว่าง ให้ส่งข้อความหาบอตอีกครั้งแล้วลองใหม่

📨 ประเภทข้อความที่รองรับ

บอตรองรับสิ่งต่อไปนี้ในตอนนี้:

  • ข้อความตัวอักษร
  • รูปภาพ
  • ข้อความเสียงและไฟล์เสียง เมื่อกำหนด ENABLE_OPENAI_WHISPER_SPEECH_TO_TEXT=true และติดตั้งส่วนที่ Whisper ต้องใช้ในเครื่องแล้ว
  • Codex และ Claude Code รองรับทั้งข้อความและรูปภาพ ส่วน Copilot ในปัจจุบันรองรับเฉพาะข้อความเท่านั้น ยังไม่มีผู้ให้บริการรายใดรองรับวิดีโอ

🤖 คำสั่ง Telegram

/provider เลือกผู้ให้บริการสำหรับเซสชันใหม่ โดยค่าที่เลือกจะถูกเก็บแยกตาม bot และ chat จนกว่าคุณจะเปลี่ยน
/project <project_folder> ตั้งค่าโฟลเดอร์ project ปัจจุบัน หากโฟลเดอร์ยังไม่มี แอปจะสร้างและทำเครื่องหมายว่า trusted หากมีอยู่แล้วแต่ยัง untrusted แอปจะถามยืนยัน trust ก่อน
/branch <new_branch> เตรียมหรือสลับ branch สำหรับ project ปัจจุบัน หาก branch มีอยู่แล้ว บอตจะถือ branch นั้นเป็น source candidate หากยังไม่มี บอตจะใช้ default branch ของ repository เป็น source candidate
/branch <origin_branch> <new_branch> เตรียมหรือสลับ branch โดยใช้ <origin_branch> เป็น source candidate สำหรับทั้งสองรูปแบบ บอตจะแสดงเฉพาะ source choices ที่มีอยู่จริงเท่านั้น: local/<branch> และ origin/<branch> หากมีเพียงตัวเดียวก็จะแสดงเพียงตัวนั้น หากไม่มีเลย บอตจะแจ้งว่าไม่พบ branch source
/current แสดง เซสชันที่ใช้งานอยู่ ของ bot และ chat ปัจจุบัน
/new [session_name] สร้างเซสชันใหม่สำหรับ project ปัจจุบัน หากไม่ระบุชื่อ บอตจะใช้รหัสเซสชันจริง หากยังไม่มีผู้ให้บริการ, project หรือ branch บอตจะพาคุณไปยังขั้นตอนที่ขาดอยู่
/switch แสดงเซสชันล่าสุด โดยเรียงจากใหม่ไปเก่า รายการนี้รวมทั้งเซสชันที่ bot ดูแลและ local Codex/Copilot/Claude Code CLI เซสชันของ project ปัจจุบัน
/switch page <number> แสดงหน้าถัดไปของเซสชันที่จัดเก็บไว้
/switch <session_id> สลับไปยังเซสชันที่ระบุด้วย ID หากเลือก local CLI เซสชัน บอตจะ import เข้าสู่ state แล้วทำงานต่อจากตรงนั้น
/compact สร้างเซสชันแบบย่อใหม่จากเซสชันที่กำลังใช้งาน แล้วสลับไปที่เซสชันนั้น
/commit <git commands> รันคำสั่งที่เกี่ยวข้องกับ git commit ซึ่งผ่านการตรวจสอบแล้วภายใน project ของเซสชันที่ใช้งานอยู่ ใช้ได้เมื่อ ENABLE_COMMIT_COMMAND=true เท่านั้น คำสั่ง Git ที่มีการแก้ไขต้องใช้ project ที่ trusted
/diff แสดงรายชื่อไฟล์ที่เปลี่ยนใน project ของเซสชันที่ใช้งานอยู่ โดยแยกไฟล์ที่ติดตามอยู่กับไฟล์ที่ยังไม่ได้ติดตามออกจากกัน ไฟล์ที่ติดตามอยู่จะมีปุ่ม inline สำหรับเปิด diff ของแต่ละไฟล์
/pull ดึงจาก origin สำหรับ branch ของเซสชันที่ใช้งานอยู่หลังจากยืนยันแล้ว และ bot จะรีเฟรช default branch ให้ด้วยเมื่อเกี่ยวข้อง
/push push origin <branch> สำหรับ เซสชันที่ใช้งานอยู่ ปัจจุบัน โดยบอตจะขอการยืนยันก่อน push
/abort ยกเลิก การรันของเอเจนต์ ปัจจุบันของ project นี้ หากมี คำถามที่เข้าคิว รออยู่ บอตจะถามว่าจะให้ประมวลผลต่อหรือไม่

⚙️ ตัวแปรสภาพแวดล้อม

ตำแหน่งไฟล์ env หลัก:

CODING_AGENT_TELEGRAM_ENV_FILE ใช้สิ่งนี้หากต้องการให้แอปชี้ไปยังไฟล์ env ที่กำหนดเอง
~/.coding-agent-telegram/.env_coding_agent_telegram ตำแหน่งไฟล์ env เริ่มต้น
./.env_coding_agent_telegram จะใช้ก็ต่อเมื่อไฟล์ local นี้มีอยู่แล้วเท่านั้น

จำเป็น

WORKSPACE_ROOT โฟลเดอร์หลักที่เก็บโฟลเดอร์โปรเจกต์ของคุณ
TELEGRAM_BOT_TOKENS Telegram bot tokens แบบคั่นด้วย comma
ALLOWED_CHAT_IDS Telegram private chat IDs แบบคั่นด้วย comma ที่ได้รับอนุญาตให้ใช้บอต

การตั้งค่าทั่วไป

APP_LOCALE ภาษา UI สำหรับข้อความของบอตและคำอธิบายคำสั่งที่ใช้ร่วมกัน ค่าที่รองรับ: en, de, fr, ja, ko, nl, th, vi, zh-CN, zh-HK, zh-TW
DEFAULT_AGENT_PROVIDER ผู้ให้บริการเริ่มต้นสำหรับเซสชันใหม่: codex, copilot หรือ claude ค่าเริ่มต้น: codex
CODEX_BIN คำสั่งที่ใช้เรียก Codex CLI. แอปจะพยายามตรวจหาเส้นทางของ Codex ที่ติดตั้งอยู่ในเครื่องโดยอัตโนมัติระหว่างการเริ่มต้น .env_coding_agent_telegram หรือสามารถใช้ which codex เพื่อดูเส้นทางได้
COPILOT_BIN คำสั่งที่ใช้เรียก Copilot CLI. แอปจะพยายามตรวจหาเส้นทางของ Copilot ที่ติดตั้งอยู่ในเครื่องโดยอัตโนมัติระหว่างการเริ่มต้น .env_coding_agent_telegram หรือสามารถใช้ which copilot เพื่อดูเส้นทางได้
CLAUDE_BIN คำสั่งที่ใช้เรียก Claude Code CLI. แอปจะพยายามตรวจหาเส้นทางของ Claude ที่ติดตั้งอยู่ในเครื่องโดยอัตโนมัติระหว่างการเริ่มต้น .env_coding_agent_telegram หรือสามารถใช้ which claude เพื่อดูเส้นทางได้
CODEX_MODEL กำหนด model ของ Codex เพิ่มเติมได้แบบ optional หากปล่อยว่างจะใช้ model เริ่มต้นของ Codex CLI ตัวอย่าง: gpt-5.4 OpenAI Codex/OpenAI models
COPILOT_MODEL กำหนด model ของ Copilot เพิ่มเติมได้แบบ optional หากปล่อยว่างจะใช้ model เริ่มต้นของ Copilot CLI ตัวอย่าง: gpt-5.4, claude-sonnet-4.6 GitHub Copilot supported models
CLAUDE_MODEL กำหนด model ของ Claude Code เพิ่มเติมได้แบบ optional หากปล่อยว่างจะใช้ model เริ่มต้นของ Claude Code CLI ตัวอย่าง: sonnet, opus, haiku Claude Code model configuration
CODEX_APPROVAL_POLICY โหมด approval ที่ส่งให้ Codex ค่าเริ่มต้น: never
CODEX_SANDBOX_MODE โหมด sandbox ที่ส่งให้ Codex ค่าเริ่มต้น: workspace-write
CODEX_SKIP_GIT_REPO_CHECK หากเปิดไว้ จะข้ามการตรวจ trusted-repo ของ Codex เสมอ
CLAUDE_PERMISSION_MODE Permission mode ที่ส่งให้ Claude Code เลือกได้จาก default, acceptEdits, plan, auto, dontAsk, bypassPermissions, manual ค่าเริ่มต้น: bypassPermissions (ทำงานอัตโนมัติเต็มรูปแบบ เนื่องจากไม่มี terminal แบบ interactive ให้ยืนยัน prompt)
CLAUDE_ALLOWED_TOOLS allowlist ของ tools สำหรับ Claude Code แบบคั่นด้วย comma โดยใช้ syntax กฎ permission ของ Claude Code ตัวอย่าง: Read,Edit,Bash(git *)
CLAUDE_DISALLOWED_TOOLS denylist ของ tools สำหรับ Claude Code แบบคั่นด้วย comma ตัวอย่าง: Bash(rm *)
ENABLE_COMMIT_COMMAND เปิดใช้งานคำสั่ง Telegram /commit ค่าเริ่มต้น: false
AGENT_HARD_TIMEOUT_SECONDS ฮาร์ดไทม์เอาต์สำหรับ การรันของเอเจนต์ หนึ่งครั้ง ค่าเริ่มต้น: 0 (ปิดใช้งาน)
SNAPSHOT_TEXT_FILE_MAX_BYTES ขนาดไฟล์สูงสุดที่บอตจะอ่านเป็นข้อความเพื่อสร้าง สแนปช็อตก่อนและหลังการรัน สำหรับ diff ของแต่ละ run ค่าเริ่มต้น: 200000
MAX_TELEGRAM_MESSAGE_LENGTH ขนาดข้อความสูงสุดก่อนที่แอปจะแบ่งการตอบกลับ ค่าเริ่มต้น: 3000
ENABLE_SENSITIVE_DIFF_FILTER ซ่อน diff สำหรับไฟล์ที่มีข้อมูลอ่อนไหว ค่าเริ่มต้น: true
ENABLE_SECRET_SCRUB_FILTER ปิดบัง tokens, keys, ค่า .env, certificates และข้อมูลลักษณะคล้ายความลับก่อนส่งไปยัง Telegram ค่าเริ่มต้น: true (แนะนำอย่างยิ่ง)
SNAPSHOT_INCLUDE_PATH_GLOBS บังคับรวม path ที่ตรงเงื่อนไขเข้าใน diff ตัวอย่าง: .github/*,.profile.test,.profile.prod
SNAPSHOT_EXCLUDE_PATH_GLOBS เพิ่มกฎยกเว้น diff เพิ่มเติมทับบนค่าเริ่มต้นของแพ็กเกจ ตัวอย่าง: .*,personal/*,sensitive*.txt หมายเหตุ: .* จะตรงกับ path ที่ซ่อนอยู่ รวมถึงไฟล์ใน ไดเรกทอรีที่ซ่อนอยู่

เสียงเป็นข้อความ

ENABLE_OPENAI_WHISPER_SPEECH_TO_TEXT ค่าเริ่มต้น: false หากเป็น true จะเปิดใช้การรู้จำข้อความเสียงและไฟล์เสียง ระบบจะตรวจสอบไบนารีหรือไลบรารีที่จำเป็น และแจ้งให้ผู้ใช้ติดตั้งหากยังขาดอยู่
OPENAI_WHISPER_MODEL โมเดลสำหรับ Whisper STT ค่าเริ่มต้น: base
โมเดลที่ใช้ได้: tiny ประมาณ 72 MB, base ประมาณ 139 MB, large-v3-turbo ประมาณ 1.5 GB
โมเดลจะถูกดาวน์โหลดอัตโนมัติเมื่อคุณส่งข้อความเสียงครั้งแรก แนะนำให้ใช้ base สำหรับการใช้งานทั่วไป หากต้องการความแม่นยำและคุณภาพที่ดีขึ้นสามารถลอง turbo ได้
OPENAI_WHISPER_TIMEOUT_SECONDS ค่าเริ่มต้น: 120 ระยะหมดเวลาของกระบวนการ STT โดยทั่วไปการประมวลผลเร็วพออยู่แล้ว แต่หากเลือก turbo การส่งข้อความเสียงครั้งแรกอาจใช้เวลานานเกินกำหนดระหว่างดาวน์โหลดโมเดล ขึ้นอยู่กับความเร็วอินเทอร์เน็ตของคุณ

สถานะและบันทึก

~/.coding-agent-telegram/state.json ไฟล์สถานะเซสชันหลัก
~/.coding-agent-telegram/state.json.bak ไฟล์สำรองของสถานะ
~/.coding-agent-telegram/logs ไดเรกทอรีบันทึก

ตัวอย่าง:

APP_LOCALE=en
WORKSPACE_ROOT=~/git
TELEGRAM_BOT_TOKENS=bot_token_one
ALLOWED_CHAT_IDS=123456789
DEFAULT_AGENT_PROVIDER=codex
CODEX_BIN=codex
COPILOT_BIN=copilot
CLAUDE_BIN=claude
CODEX_APPROVAL_POLICY=never
CODEX_SANDBOX_MODE=workspace-write
CLAUDE_PERMISSION_MODE=bypassPermissions
ENABLE_SENSITIVE_DIFF_FILTER=true
ENABLE_SECRET_SCRUB_FILTER=true

🧠 การจัดการเซสชัน

เซสชันถูกแยกตาม:

  • Telegram bot
  • Telegram chat

ดังนั้นบัญชี Telegram เดียวกันสามารถใช้หลาย bot ได้โดยไม่ทำให้เซสชันปะปนกัน

ตัวอย่าง:

  • Bot A + chat ของคุณ -> งาน backend
  • Bot B + chat ของคุณ -> งาน frontend
  • Bot C + chat ของคุณ -> งาน infra

เซสชันที่ใช้งานอยู่ ยังผูกกับสิ่งต่อไปนี้ด้วย:

  • โฟลเดอร์โปรเจ็กต์
  • ผู้ให้บริการ
  • ชื่อ branch หากมี
แต่ละเซสชันจะเก็บข้อมูล:
  • ชื่อเซสชัน
  • โฟลเดอร์โปรเจ็กต์
  • ชื่อ branch
  • ผู้ให้บริการ
  • timestamps
  • การเลือก เซสชันที่ใช้งานอยู่ ภายใต้ขอบเขต bot/chat นั้น

🔓 ล็อกการทำงานพร้อมกันของเวิร์กสเปซ

จะมี การรันของเอเจนต์ ที่ active ได้พร้อมกันเพียงหนึ่งตัวต่อ โฟลเดอร์โปรเจ็กต์ ไม่ว่า chat หรือ Telegram bot ตัวใดจะเป็นผู้เริ่มก็ตาม

  • โปรเจ็กต์กำลังถูกใช้งาน: ใน workspace นั้นมี การรันของเอเจนต์ ทำงานอยู่แล้ว
  • เอเจนต์กำลังทำงานอยู่: run ตัวนั้นยังประมวลผลคำขอปัจจุบันไม่เสร็จ

บอตบังคับกติกานี้เพื่อไม่ให้มีสอง agent เขียนลง workspace เดียวกันพร้อมกัน ช่วยลดการแก้ไขชนกันและลดโอกาสข้อมูลเสียหาย

หากมีข้อความเข้ามาในขณะที่ project เดียวกันกำลังมี agent ทำงานอยู่ บอตจะตอบทันทีว่า:

⏳ มี agent กำลังทำงานอยู่บน project นี้แล้ว โปรดรอให้เสร็จก่อน

lock นี้อยู่ในหน่วยความจำ ไม่ได้เก็บลงดิสก์ จึงถูกปล่อยอัตโนมัติเมื่อ agent ทำงานเสร็จ ล้มเหลว หรือ server รีสตาร์ต

💬 คำถามที่เข้าคิว

หาก project ปัจจุบันมี การรันของเอเจนต์ ทำงานอยู่แล้ว ข้อความตัวอักษรที่ส่งมาภายหลังจะไม่ถูกปฏิเสธ แต่จะถูกนำไปเข้าคิวแทน

  • คำถามใหม่จะถูกต่อท้ายในไฟล์ queued-questions บนดิสก์
  • agent ปัจจุบันยังคงทำงานกับคำขอเดิมต่อไป
  • เมื่อ run นั้นจบแบบปกติ บอตจะเริ่มประมวลผลคำถามในคิวโดยอัตโนมัติ

หาก run ปัจจุบันถูก abort และยังมี คำถามที่เข้าคิว เหลืออยู่ บอตจะไม่ทำต่ออัตโนมัติ แต่จะถามว่าต้องการประมวลผลคำถามที่เหลือต่อหรือไม่ แบบรวมกันหรือทีละข้อ

⚠️ Diff (การเปลี่ยนไฟล์)

ในแต่ละ การรันของเอเจนต์ บอตจะสร้าง สแนปช็อตก่อนและหลังการรัน แบบเบาของโปรเจกต์ด้วย เพื่อสรุปไฟล์ที่เปลี่ยนและส่ง diff กลับไปยัง Telegram ได้ สแนปช็อต นี้ถูกสร้างโดยตัวบอตเอง ไม่ใช่โดย Codex, Copilot หรือ Claude Code.

สิ่งที่ควรรู้เกี่ยวกับ สแนปช็อต:

  • แอปจะสแกน ไดเรกทอรีโปรเจ็กต์ ก่อนและหลังการรัน
  • สำหรับไฟล์ข้อความทั่วไป แอปจะใช้ diff จาก สแนปช็อต ของ run นั้นก่อน diff เทียบกับ git head
  • โฟลเดอร์การพึ่งพา แคช และรันไทม์ที่พบบ่อยจะถูกข้ามเช่นกัน
  • ไฟล์ binary และไฟล์ที่ใหญ่กว่า SNAPSHOT_TEXT_FILE_MAX_BYTES จะไม่ถูกอ่านเป็นข้อความ
  • สำหรับโปรเจกต์ขนาดใหญ่มาก การสแกนเพิ่มนี้อาจเพิ่มภาระด้าน I/O และ memory ได้อย่างเห็นได้ชัด
  • หาก สแนปช็อต ไม่สามารถแทนไฟล์เป็นข้อความได้ แอปจะ fallback ไปใช้ git diff เมื่อทำได้
  • สำหรับไฟล์ขนาดใหญ่หรือไม่ใช่ข้อความ diff อาจถูกละไว้และแทนด้วยข้อความสั้น ๆ

กฎการยกเว้น สแนปช็อต อยู่ในทรัพยากรของแพ็กเกจ:

  • src/coding_agent_telegram/resources/snapshot_excluded_dir_names.txt
  • src/coding_agent_telegram/resources/snapshot_excluded_dir_globs.txt
  • src/coding_agent_telegram/resources/snapshot_excluded_file_globs.txt

คุณสามารถ override ค่าเหล่านี้ในไฟล์ env ได้โดยไม่ต้องแก้ package ที่ติดตั้งอยู่:

  • SNAPSHOT_INCLUDE_PATH_GLOBS บังคับรวม path ที่ตรงเงื่อนไขเข้าไปใน diff ตัวอย่าง: .github/*,.profile.test,.profile.prod

  • SNAPSHOT_EXCLUDE_PATH_GLOBS เพิ่มกฎยกเว้น diff เพิ่มเติมทับบนค่าเริ่มต้นของ package ตัวอย่าง: .*,personal/*,sensitive*.txt หมายเหตุ: .* จะตรงกับ path ที่ซ่อนอยู่ รวมถึงไฟล์ใน ไดเรกทอรีที่ซ่อนอยู่

หาก include และ exclude ตรงพร้อมกัน include จะมีผลก่อน

🌿 พฤติกรรมของ Branch

บอตถือว่า project และ branch เป็นชุดเดียวกัน

  • การเลือก project จะไม่แอบเลือก branch ที่ไม่เกี่ยวข้องให้อัตโนมัติ
  • หากต้องใช้ branch บอตจะถามให้คุณเลือก
  • เมื่อมีการแสดงข้อมูล branch ในข้อความที่เกี่ยวกับเซสชัน จะโชว์ project และ branch ควบคู่กัน

เมื่อคุณสร้างหรือสลับ branch บอตจะพาคุณเลือก source อย่างชัดเจน:

  • local/<branch> คือใช้ local branch เป็นต้นทาง
  • origin/<branch> คืออัปเดตจาก remote branch ก่อน แล้วค่อยสลับ

ถ้าบอตพบว่า branch ที่เก็บไว้ในเซสชันไม่ตรงกับ branch ปัจจุบันของ repository บอตจะไม่ทำต่อแบบเดาสุ่ม แต่จะถามว่าต้องการใช้ branch ใด:

  • ใช้ branch ที่เก็บไว้ในเซสชัน
  • ใช้ branch ปัจจุบันของ repository

หาก source branch ที่คุณต้องการหายไป บอตจะเสนอ fallback source ตาม default branch และ current branch แทนที่จะปล่อยให้คุณเจอ Git error ตรง ๆ

🔐 พฤติกรรม trust ของ Git

  • โฟลเดอร์ที่มีอยู่เดิมจะอิงตาม CODEX_SKIP_GIT_REPO_CHECK
  • โฟลเดอร์ที่สร้างผ่าน /project <name> จะถูกทำเครื่องหมาย trusted โดยแอปนี้
  • โฟลเดอร์เดิมที่เลือกผ่าน /project <name> จะยังคงเป็น untrusted จนกว่าคุณจะยืนยัน trust ใน Telegram
  • ดังนั้นโฟลเดอร์โปรเจกต์ที่สร้างใหม่จึงใช้งานได้ทันที
  • สามารถปิด /commit ได้ทั้งหมดด้วย ENABLE_COMMIT_COMMAND
  • การทำ /commit ที่มีการแก้ไขจริงจะอนุญาตเฉพาะกับ trusted project เท่านั้น

🪵 บันทึก

log จะถูกเขียน ทั้งไปที่ stdout และไฟล์ log แบบหมุนเวียน ใต้ path นี้:

  • ~/.coding-agent-telegram/logs (หมุนเมื่อถึง 10 MB และเก็บสำรอง 3 ชุด)

หมายเหตุ: ถ้าคุณดู terminal ไปพร้อมกับ tail ไฟล์ log ข้อความแต่ละอันจะปรากฏสองครั้ง นี่เป็นพฤติกรรมปกติ ควรดูอย่างใดอย่างหนึ่ง ไม่ใช่ทั้งสองพร้อมกัน

เหตุการณ์ที่มักถูกบันทึก
  • การเริ่มต้น bot และเริ่ม polling
  • การเลือก project
  • การสร้างเซสชัน
  • การสลับเซสชัน
  • การรายงาน เซสชันที่ใช้งานอยู่
  • การรันงานแบบปกติ (รวม audit log line ที่มี prompt แบบตัดทอน)
  • การแทนที่เซสชันหลัง resume ล้มเหลว
  • warnings และ runtime errors

🗂️ โครงสร้างโปรเจกต์

  • src/coding_agent_telegram/ โค้ดหลักของแอปพลิเคชัน

  • tests/ ชุดทดสอบ

  • startup.sh entrypoint สำหรับ bootstrap และ startup แบบ local

  • src/coding_agent_telegram/resources/.env.example template สภาพแวดล้อมหลักที่ใช้ทั้งตอนเริ่มจาก repo และตอนติดตั้งเป็น package

  • pyproject.toml การตั้งค่า แพ็กเกจจิง และ dependencies

📦 การกำหนดเวอร์ชัน release

เวอร์ชันของ package ถูก derive จาก Git tags

  • TestPyPI/testing: v2026.3.26.dev1
  • PyPI prerelease: v2026.3.26rc1
  • PyPI stable: v2026.3.26

📌 หมายเหตุ

  • โปรเจกต์นี้ออกแบบมาสำหรับผู้ใช้ที่รัน agents แบบ local บนเครื่องของตนเอง
  • Telegram bot เป็น control surface ไม่ใช่ execution environment
  • หากคุณรันหลาย bot ก็ยังจัดการทั้งหมดได้ด้วย เซิร์ฟเวอร์โพรเซส เดียว