{"id":49655626,"url":"https://github.com/smallnest/imclaw","last_synced_at":"2026-05-06T09:05:02.789Z","repository":{"id":348198787,"uuid":"1196732684","full_name":"smallnest/imclaw","owner":"smallnest","description":"acp skill for openclaw, claude cc, codex, gemini cli, pi and others","archived":false,"fork":false,"pushed_at":"2026-04-17T13:03:04.000Z","size":597,"stargazers_count":26,"open_issues_count":6,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-17T15:09:55.919Z","etag":null,"topics":["acp","acpx","claude-code","codex","cursor","gemini-cli","openclaw","pi-coding-agent"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/smallnest.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-31T01:43:57.000Z","updated_at":"2026-04-17T13:03:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/smallnest/imclaw","commit_stats":null,"previous_names":["smallnest/imclaw"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/smallnest/imclaw","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smallnest%2Fimclaw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smallnest%2Fimclaw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smallnest%2Fimclaw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smallnest%2Fimclaw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smallnest","download_url":"https://codeload.github.com/smallnest/imclaw/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smallnest%2Fimclaw/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32686264,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-06T08:33:17.875Z","status":"ssl_error","status_checked_at":"2026-05-06T08:33:17.221Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["acp","acpx","claude-code","codex","cursor","gemini-cli","openclaw","pi-coding-agent"],"created_at":"2026-05-06T09:05:02.093Z","updated_at":"2026-05-06T09:05:02.765Z","avatar_url":"https://github.com/smallnest.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# IMClaw\n\nIMClaw 是一个支持 ACP 协议的 AI Agent 网关，通过 CLI 与 Agent 交互。\n\n**重要**:\n本项目演化出来的 autoresearch 独立成一个单独的项目:[smallnest/autoresearch](https://github.com/smallnest/autoresearch), 更智能更强大。\n\n## 功能特性\n\n- **ACP 协议**: 通过 acpx 支持 Claude、Codex 等 AI Agent\n- **多会话管理**: 支持 `/new` 新建会话\n- **多 Agent 支持**: 动态创建 Agent，通过命令切换\n- **权限控制**: 支持多种权限模式\n- **统一网关**: HTTP 和 WebSocket 使用同一端口\n\n## 安装\n\n### 方式一：下载预编译二进制\n\n从 [Releases](https://github.com/smallnest/imclaw/releases) 页面下载对应平台的二进制文件。\n\n### 方式二：使用 Go 安装\n\n```bash\ngo install github.com/smallnest/imclaw/cmd/imclaw@latest\ngo install github.com/smallnest/imclaw/cmd/imclaw-cli@latest\n```\n\n### 方式三：从源码构建\n\n```bash\n# 克隆仓库\ngit clone https://github.com/smallnest/imclaw.git\ncd imclaw\n\n# 构建\nmake build\n\n# 或者直接使用 go build\ngo build -o bin/imclaw ./cmd/imclaw\ngo build -o bin/imclaw-cli ./cmd/imclaw-cli\n```\n\n## 快速开始\n\n### 运行服务器\n\n```bash\n# 使用默认参数\n./bin/imclaw\n\n# 指定端口和认证令牌\n./bin/imclaw --port 9000 --token my-secret-token\n\n# 查看帮助\n./bin/imclaw --help\n```\n\n### 服务器参数\n\n| 参数 | 简写 | 默认值 | 说明 |\n|------|------|--------|------|\n| `--host` | `-H` | `0.0.0.0` | 服务监听地址 |\n| `--port` | `-p` | `8080` | 服务端口 |\n| `--timeout` | | `30` | 默认超时时间（秒） |\n| `--token` | | `\"\"` | 认证令牌（为空则不校验认证） |\n| `--version` | | | 显示版本信息 |\n\n## CLI 工具\n\nIMClaw 提供了命令行工具 `imclaw-cli`，可以直接与 Agent 交互。\n\n### 构建 CLI\n\n```bash\nmake build-cli\n# 或\ngo build -o bin/imclaw-cli ./cmd/imclaw-cli\n```\n\n### 安装 CLI\n\n```bash\nmake install-cli\n# 安装后可以直接使用 imclaw-cli 命令\n```\n\n### 使用方式\n\n#### 交互模式（REPL）\n\n```bash\n# 直接运行进入交互模式\n./bin/imclaw-cli\n\n# 指定 Agent\n./bin/imclaw-cli --agent codex\n\n# 使用指定的 Session ID\n./bin/imclaw-cli --session my-session-123\n\n# 指定权限模式和输出格式\n./bin/imclaw-cli --approve-all --format json\n```\n\n#### 单条消息\n\n```bash\n# 使用 -p/--prompt 参数（推荐）\n./bin/imclaw-cli -p \"什么是 Go 语言？\"\n./bin/imclaw-cli --prompt \"什么是 Go 语言？\"\n\n# 或直接传递消息\n./bin/imclaw-cli \"什么是 Go 语言？\"\n\n# 指定 Agent\n./bin/imclaw-cli --agent codex -p \"Hello\"\n\n# 使用指定 Session（可复用会话）\n./bin/imclaw-cli --session my-session -p \"继续之前的对话\"\n\n# JSON 输出格式\n./bin/imclaw-cli --format json -p \"Hello\"\n\n# 自动批准所有权限请求\n./bin/imclaw-cli --approve-all -p \"Hello\"\n\n# 只读模式（拒绝所有写操作）\n./bin/imclaw-cli --deny-all -p \"分析这段代码\"\n```\n\n### CLI 参数\n\n| 参数 | 说明 |\n|------|------|\n| `--server \u003curl\u003e` | IMClaw 服务器 WebSocket URL（默认：ws://localhost:8080/ws） |\n| `--token \u003ctoken\u003e` | 认证令牌 |\n| `-p, --prompt \u003cmessage\u003e` | 提示消息（单次执行模式） |\n| `--session \u003cid\u003e` | 指定使用的 Session ID（为空则自动创建） |\n| `--agent \u003ctype\u003e` | Agent 类型（claude, codex 等） |\n| `--cwd \u003cdir\u003e` | 工作目录 |\n| `--auth-policy \u003cpolicy\u003e` | 认证策略：skip 或 fail |\n| `--approve-all` | 自动批准所有权限请求 |\n| `--approve-reads` | 自动批准读取请求，写入需要确认（默认） |\n| `--deny-all` | 拒绝所有权限请求（只读模式） |\n| `--non-interactive-permissions \u003cpolicy\u003e` | 非交互模式下的权限策略：deny 或 fail |\n| `--format \u003cfmt\u003e` | 输出格式：text, json, quiet（默认：text） |\n| `--suppress-reads` | 禁止输出原始读取文件内容 |\n| `--model \u003cid\u003e` | Agent 模型 ID |\n| `--permission-preset \u003cpreset\u003e` | 权限预设：safe-readonly, dev-default (默认), full-auto |\n| `--allowed-tools \u003clist\u003e` | 允许的工具名称（逗号分隔）。默认：Bash,Read,Write。空字符串=允许所有 |\n| `--denied-tools \u003clist\u003e` | 拒绝的工具名称（逗号分隔），优先级高于 allowed-tools |\n| `--max-turns \u003ccount\u003e` | 会话最大轮次 |\n| `--prompt-retries \u003ccount\u003e` | 失败重试次数 |\n| `--json-strict` | 严格 JSON 模式（需要 --format json） |\n| `--timeout \u003cseconds\u003e` | 等待 Agent 响应的最大时间 |\n| `--ttl \u003cseconds\u003e` | 队列所有者空闲 TTL |\n| `--verbose` | 启用详细调试日志 |\n\n\n## 权限控制指南\n\nIMClaw 提供六维权限控制参数，可以灵活组合实现从粗粒度到细粒度的权限管理。\n\n### 六个权限参数概览\n\n| 参数 | CLI Flag | 说明 | 示例值 |\n|------|----------|------|--------|\n| **Permissions** | `--approve-all` / `--approve-reads` / `--deny-all` | 权限模式，控制是否自动批准操作 | `approve-all` |\n| **PermissionPreset** | `--permission-preset` | 预设策略，一组预配置的权限组合 | `safe-readonly` |\n| **AllowedTools** | `--allowed-tools` | 工具白名单 | `Bash,Read,Write` |\n| **DeniedTools** | `--denied-tools` | 工具黑名单，从白名单中剔除 | `Write,Bash` |\n| **AuthPolicy** | `--auth-policy` | 认证策略，控制认证失败时的行为 | `skip` / `fail` |\n| **NonInteractivePerms** | `--non-interactive-permissions` | 非交互模式权限策略 | `deny` / `fail` |\n\n---\n\n### 1. PermissionPreset（预设策略）\n\n预设是一组开箱即用的权限组合，适合快速配置。\n\n| 预设名 | Permissions | AllowedTools | 适用场景 |\n|--------|-------------|--------------|----------|\n| `safe-readonly` | `deny-all` | Glob, Grep, LS, Read | 安全阅读代码，无任何写操作风险 |\n| `dev-default` | `approve-reads` | Bash, Read, Write | 日常开发，读写自动批准 |\n| `full-auto` | `approve-all` | 所有已知工具 | 全自动模式，适合可信环境 |\n\n**不指定预设时**，默认等效于 `dev-default`（`approve-reads` + `Bash,Read,Write`）。\n\n```bash\n# 安全只读模式\nimclaw-cli --permission-preset safe-readonly -p \"分析这段代码\"\n\n# 全自动模式\nimclaw-cli --permission-preset full-auto -p \"帮我重构代码\"\n```\n\n---\n\n### 2. Permissions（权限模式）\n\n权限模式控制 Agent 执行操作时是否需要用户确认。\n\n| Flag | 行为 | 适用场景 |\n|------|------|----------|\n| `--approve-all` | 所有操作自动批准，无需确认 | 可信环境、自动化脚本 |\n| `--approve-reads` | 读取操作自动批准，写入操作需确认（默认） | 日常开发，防止误操作 |\n| `--deny-all` | 拒绝所有需要权限的操作 | 只读分析、安全审计 |\n\n**注意**：这三个 flag 是互斥的，后设置的会覆盖前面的。\n\n```bash\n# 自动批准所有操作\nimclaw-cli --approve-all -p \"帮我重构代码\"\n\n# 只读模式，拒绝所有写操作\nimclaw-cli --deny-all -p \"分析项目结构\"\n```\n\n---\n\n### 3. AllowedTools（工具白名单）\n\n精确控制 Agent 可以使用的工具。不指定时使用预设的工具列表。\n\n**支持的工具列表**：\n```\nBash          # 执行 shell 命令\nEdit          # 编辑文件\nGlob          # 文件模式匹配\nGrep          # 文件内容搜索\nLS            # 列出目录\nMultiEdit     # 批量编辑文件\nNotebookEdit  # 编辑 Jupyter Notebook\nRead          # 读取文件\nTodoWrite     # 写入待办事项\nWebFetch      # 抓取网页\nWebSearch     # 搜索网页\nWrite         # 写入文件\n```\n\n```bash\n# 只允许读取和搜索\nimclaw-cli --allowed-tools Read,Grep,Glob -p \"分析代码\"\n\n# 允许所有工具（空字符串）\nimclaw-cli --allowed-tools \"\" -p \"任意操作\"\n\n# 只允许执行命令\nimclaw-cli --allowed-tools Bash -p \"运行测试\"\n```\n\n---\n\n### 4. DeniedTools（工具黑名单）\n\n从 AllowedTools 中剔除指定工具，实现\"允许大部分但排除某些\"的效果。\n\n**优先级**：`DeniedTools` \u003e `AllowedTools`\n\n```bash\n# 允许所有工具，但禁止写入文件\nimclaw-cli --permission-preset full-auto --denied-tools Write -p \"帮我分析代码\"\n\n# 允许所有工具，但禁止执行命令和写入\nimclaw-cli --permission-preset full-auto --denied-tools Write,Bash -p \"只读分析\"\n\n# 组合使用：白名单 + 黑名单\nimclaw-cli --allowed-tools Bash,Read,Write,Edit --denied-tools Write -p \"可以编辑但不能新建文件\"\n```\n\n---\n\n### 5. AuthPolicy（认证策略）\n\n控制当 Agent 需要认证时的行为。\n\n| 值 | 行为 |\n|----|------|\n| `skip` | 跳过认证要求，继续执行 |\n| `fail` | 认证失败时报错停止 |\n\n```bash\n# 跳过认证\nimclaw-cli --auth-policy skip -p \"Hello\"\n\n# 认证失败时报错\nimclaw-cli --auth-policy fail -p \"Hello\"\n```\n\n---\n\n### 6. NonInteractivePerms（非交互模式权限）\n\n控制在无法提示用户确认时的行为（如管道输入、脚本执行）。\n\n| 值 | 行为 |\n|----|------|\n| `deny` | 自动拒绝所有权限请求 |\n| `fail` | 报错停止执行 |\n\n```bash\n# 脚本中自动拒绝权限请求\necho \"分析代码\" | imclaw-cli --non-interactive-permissions deny\n\n# 脚本中遇到权限请求时报错\nimclaw-cli --non-interactive-permissions fail -p \"Hello\" \u003c /dev/null\n```\n\n---\n\n### 参数优先级与组合规则\n\n参数按以下顺序解析，后者的设置会覆盖前者：\n\n```\n1. PermissionPreset    → 提供基准配置\n2. Permissions         → 覆盖预设的权限模式\n3. AllowedTools        → 覆盖预设的工具白名单\n4. DeniedTools         → 从当前白名单中剔除\n5. AuthPolicy          → 独立生效\n6. NonInteractivePerms → 独立生效\n```\n\n**解析流程示例**：\n\n```bash\nimclaw-cli \\\n  --permission-preset full-auto \\      # 1. 基准: approve-all, 所有工具\n  --approve-reads \\                    # 2. 覆盖权限模式为 approve-reads\n  --denied-tools Write,Bash \\          # 4. 从工具列表中剔除 Write 和 Bash\n  -p \"Hello\"\n\n# 最终结果:\n# - Permissions: approve-reads (读取自动批准，写入需确认)\n# - AllowedTools: 所有工具 - {Write, Bash}\n# - Agent 可以读取、搜索、编辑，但不能新建文件或执行命令\n```\n\n---\n\n### 典型使用场景\n\n#### 场景 1：安全代码审查（只读）\n\n```bash\n# 最严格：只允许读取和搜索，拒绝所有操作确认\nimclaw-cli --permission-preset safe-readonly -p \"审查这段代码的安全性\"\n\n# 等效于\nimclaw-cli --deny-all --allowed-tools Glob,Grep,LS,Read -p \"审查代码\"\n```\n\n#### 场景 2：日常开发（默认推荐）\n\n```bash\n# 读取自动批准，写入需确认\nimclaw-cli --permission-preset dev-default -p \"帮我实现这个功能\"\n\n# 等效于\nimclaw-cli --approve-reads --allowed-tools Bash,Read,Write -p \"实现功能\"\n```\n\n#### 场景 3：自动化脚本（无交互）\n\n```bash\n# 全自动 + 非交互模式拒绝权限请求 = 纯自动执行\nimclaw-cli \\\n  --permission-preset full-auto \\\n  --non-interactive-perms deny \\\n  -p \"运行测试并修复失败的用例\"\n```\n\n#### 场景 4：受限开发（可以编辑但不能执行命令）\n\n```bash\nimclaw-cli \\\n  --permission-preset full-auto \\\n  --denied-tools Bash \\\n  -p \"帮我重构代码\"\n\n# Agent 可以编辑文件，但不能执行 shell 命令\n```\n\n#### 场景 5：CI/CD 环境\n\n```bash\n# 完全自动化 + 认证跳过\nimclaw-cli \\\n  --approve-all \\\n  --auth-policy skip \\\n  --non-interactive-perms deny \\\n  --format json \\\n  -p \"检查代码并生成报告\"\n```\n\n---\n\n### 权限决策流程图\n\n```\nAgent 请求执行操作\n        │\n        ▼\n┌───────────────────┐\n│ 检查 NonInteractive │\n│ (非交互模式?)       │\n└─────────┬─────────┘\n          │\n    ┌─────┴─────┐\n    ▼           ▼\n  是           否\n    │           │\n    ▼           ▼\n┌─────────┐  ┌─────────────┐\n│ deny    │  │ 检查 Auth   │\n│ 或 fail │  │ Policy      │\n└─────────┘  └──────┬──────┘\n                    │\n              ┌─────┴─────┐\n              ▼           ▼\n            skip        fail\n              │           │\n              ▼           ▼\n       ┌─────────────────────┐\n       │ 检查工具是否在      │\n       │ AllowedTools 中     │\n       └──────────┬──────────┘\n                  │\n            ┌─────┴─────┐\n            ▼           ▼\n          允许        拒绝\n            │           │\n            ▼           ▼\n       ┌─────────────────────┐\n       │ 根据 Permissions    │\n       │ 决定是否需要确认     │\n       └──────────┬──────────┘\n                  │\n         ┌────────┼────────┐\n         ▼        ▼        ▼\n    approve-all approve-reads deny-all\n         │        │        │\n         ▼        ▼        ▼\n      自动批准  读自动    拒绝\n               写确认\n```\n\n### REPL 命令\n\n在交互模式下，支持以下命令：\n\n| 命令 | 说明 |\n|------|------|\n| `/new` | 创建新会话（清除上下文） |\n| `/session` | 显示当前会话信息 |\n| `/agent \u003cname\u003e` | 切换到指定的 Agent |\n| `/agents` | 列出可用的 Agent |\n| `/help` | 显示帮助 |\n| `/quit` | 退出 CLI |\n\n\n## 后台任务 API\n\nIMClaw 支持后台任务（Job）执行，允许异步提交任务并查询状态。适用于长时间运行的 Agent 任务。\n\n### Job 状态\n\n| 状态 | 说明 |\n|------|------|\n| `queued` | 任务在队列中等待执行 |\n| `running` | 任务正在执行中 |\n| `completed` | 任务执行成功 |\n| `failed` | 任务执行失败 |\n| `canceled` | 任务被用户取消 |\n\n### REST API\n\n#### 提交任务\n\n```bash\nPOST /api/jobs\nContent-Type: application/json\n\n{\n  \"prompt\": \"帮我分析项目结构\",\n  \"agent\": \"codex\"\n}\n```\n\n**响应：**\n```json\n{\n  \"id\": \"019d527d-34ed-7272-b336-f67fd49024db\",\n  \"status\": \"queued\",\n  \"prompt\": \"帮我分析项目结构\",\n  \"agent_name\": \"codex\",\n  \"created_at\": \"2026-04-03T16:37:10Z\"\n}\n```\n\n#### 查询任务状态\n\n```bash\nGET /api/jobs/{job_id}\n```\n\n**响应：**\n```json\n{\n  \"id\": \"019d527d-34ed-7272-b336-f67fd49024db\",\n  \"status\": \"completed\",\n  \"prompt\": \"帮我分析项目结构\",\n  \"agent_name\": \"codex\",\n  \"created_at\": \"2026-04-03T16:37:10Z\",\n  \"started_at\": \"2026-04-03T16:37:12Z\",\n  \"finished_at\": \"2026-04-03T16:37:45Z\",\n  \"result\": \"项目结构分析结果...\",\n  \"logs\": [\n    {\"timestamp\": \"2026-04-03T16:37:10Z\", \"level\": \"info\", \"message\": \"Job submitted\"},\n    {\"timestamp\": \"2026-04-03T16:37:12Z\", \"level\": \"info\", \"message\": \"Job started\"},\n    {\"timestamp\": \"2026-04-03T16:37:45Z\", \"level\": \"info\", \"message\": \"Job completed successfully\"}\n  ]\n}\n```\n\n#### 列出所有任务\n\n```bash\nGET /api/jobs\n```\n\n**响应：**\n```json\n{\n  \"jobs\": [\n    {\n      \"id\": \"019d527d-34ed-7272-b336-f67fd49024db\",\n      \"status\": \"completed\",\n      \"prompt\": \"帮我分析项目结构\",\n      \"agent_name\": \"codex\",\n      \"created_at\": \"2026-04-03T16:37:10Z\"\n    }\n  ]\n}\n```\n\n#### 取消任务\n\n```bash\nDELETE /api/jobs/{job_id}\n```\n\n### JSON-RPC API\n\n通过 WebSocket 连接使用 JSON-RPC 协议：\n\n#### 提交任务\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"method\": \"job.submit\",\n  \"params\": {\n    \"prompt\": \"帮我分析项目结构\",\n    \"agent\": \"codex\"\n  }\n}\n```\n\n#### 查询任务\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 2,\n  \"method\": \"job.get\",\n  \"params\": {\n    \"job_id\": \"019d527d-34ed-7272-b336-f67fd49024db\"\n  }\n}\n```\n\n#### 列出任务\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 3,\n  \"method\": \"job.list\"\n}\n```\n\n#### 取消任务\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 4,\n  \"method\": \"job.cancel\",\n  \"params\": {\n    \"job_id\": \"019d527d-34ed-7272-b336-f67fd49024db\"\n  }\n}\n```\n\n#### 删除任务\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 5,\n  \"method\": \"job.delete\",\n  \"params\": {\n    \"job_id\": \"019d527d-34ed-7272-b336-f67fd49024db\"\n  }\n}\n```\n\n### 使用示例\n\n#### curl 调用\n\n```bash\n# 提交任务\nJOB_ID=$(curl -s -X POST http://localhost:8080/api/jobs \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"prompt\": \"分析项目结构\", \"agent\": \"codex\"}' | jq -r '.id')\n\necho \"Job ID: $JOB_ID\"\n\n# 查询状态\ncurl -s http://localhost:8080/api/jobs/$JOB_ID | jq .\n\n# 取消任务\ncurl -X DELETE http://localhost:8080/api/jobs/$JOB_ID\n```\n\n#### Python 调用\n\n```python\nimport requests\nimport time\n\n# 提交任务\nresponse = requests.post('http://localhost:8080/api/jobs', json={\n    'prompt': '分析项目结构',\n    'agent': 'codex'\n})\njob = response.json()\njob_id = job['id']\nprint(f\"Job ID: {job_id}\")\n\n# 轮询等待完成\nwhile True:\n    response = requests.get(f'http://localhost:8080/api/jobs/{job_id}')\n    job = response.json()\n    status = job['status']\n    print(f\"Status: {status}\")\n\n    if status in ['completed', 'failed', 'canceled']:\n        break\n\n    time.sleep(2)\n\n# 获取结果\nif job['status'] == 'completed':\n    print(\"Result:\", job['result'])\nelse:\n    print(\"Error:\", job.get('error', 'Unknown error'))\n```\n\n#### JavaScript 调用\n\n```javascript\n// WebSocket 连接\nconst ws = new WebSocket('ws://localhost:8080/ws');\n\nws.onopen = () =\u003e {\n  // 提交任务\n  ws.send(JSON.stringify({\n    jsonrpc: '2.0',\n    id: 1,\n    method: 'job.submit',\n    params: {\n      prompt: '分析项目结构',\n      agent: 'codex'\n    }\n  }));\n};\n\nws.onmessage = (event) =\u003e {\n  const response = JSON.parse(event.data);\n  console.log('Response:', response);\n\n  if (response.id === 1) {\n    const jobId = response.result.id;\n    // 定期查询状态\n    setInterval(() =\u003e {\n      ws.send(JSON.stringify({\n        jsonrpc: '2.0',\n        id: 2,\n        method: 'job.get',\n        params: { job_id: jobId }\n      }));\n    }, 2000);\n  }\n};\n```\n\n### Job 数据结构\n\n```go\ntype Job struct {\n    ID         string     `json:\"id\"`\n    Status     JobStatus  `json:\"status\"`\n    Prompt     string     `json:\"prompt\"`\n    AgentName  string     `json:\"agent_name\"`\n    CreatedAt  time.Time  `json:\"created_at\"`\n    StartedAt  *time.Time `json:\"started_at,omitempty\"`\n    FinishedAt *time.Time `json:\"finished_at,omitempty\"`\n    Result     string     `json:\"result,omitempty\"`\n    Error      string     `json:\"error,omitempty\"`\n    Logs       []LogEntry `json:\"logs,omitempty\"`\n}\n\ntype LogEntry struct {\n    Timestamp time.Time `json:\"timestamp\"`\n    Level     string    `json:\"level\"`\n    Message   string    `json:\"message\"`\n}\n```\n\n### 状态转换\n\n```\n         ┌─────────┐\n         │ queued  │\n         └────┬────┘\n              │\n    ┌─────────┼─────────┐\n    ▼         ▼         │\n┌────────┐ ┌────────┐   │\n│running │ │canceled│   │\n└───┬────┘ └────────┘   │\n    │                    │\n    ├─────────┬─────────┤\n    ▼         ▼         ▼\n┌──────────┐ ┌───────┐ ┌────────┐\n│completed │ │failed │ │canceled│\n└──────────┘ └───────┘ └────────┘\n              │\n              ▼ (允许重试)\n          ┌────────┐\n          │ queued │\n          └────────┘\n```\n\n- Go 1.25.0+\n- acpx (用于 ACP 协议支持)\n\n### 安装 acpx\n\n```bash\nnpm install -g acpx@latest\n```\n\n## License\n\nMIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmallnest%2Fimclaw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmallnest%2Fimclaw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmallnest%2Fimclaw/lists"}