Web Agent Console

Web Agent Console 是一个本地优先的浏览器控制台，用来查看和操作命令行 Agent 会话。它把项目列表、会话历史、流式输出、审批、用户提问和附件交互集中到一个 Web 界面里，方便你在浏览器里观察和继续本地 Agent 工作流。

当前项目支持两条主要后端路径：

codex：通过受控的 codex app-server 驱动会话
claude-sdk：通过 @anthropic-ai/claude-agent-sdk 复用本地 Claude 会话与认证

这仍然是一个本地优先的 PoC，更适合个人使用、原型验证和内部工具场景，而不是直接作为生产部署方案。

移动端截图

以下截图均使用 README 专用的 mock 假数据生成，只用于展示移动端界面结构与交互布局。

_{共享密码输入}	_{项目 / 会话选择}	_输入图片
_添加文件	_计划任务

主要能力

按工作目录聚合项目和会话
在浏览器中查看流式输出、任务进度和运行状态
在 UI 中处理工具审批和用户问题
为单个会话切换模型和推理强度
上传附件并按后端能力做校验
页面刷新或服务重启后恢复部分会话状态
可选共享密码认证
可接收独立 Claude 进程回传的 hook 事件

适合谁

想用浏览器而不是纯终端来观察 Agent 执行过程的人
需要在图形界面里完成审批、回答问题、继续对话的人
同时维护多个工作目录，希望统一查看会话的人

快速开始

这部分会帮你完成什么

检查本机是否已经具备运行条件
用 npx 直接启动 Web Agent Console
按需切换 codex 或 claude-sdk provider

开始前准备

Node.js 22+
如果使用 codex provider，需要本地 codex 可执行文件和可用的登录态
如果使用 claude-sdk provider，需要本地 Claude Code / Agent SDK 登录态

1. 先检查本地环境

先确认本机是否具备 codex 和 claude-sdk 的基础运行条件：

npx web-agent-console doctor

这个命令会检查：

Node.js 版本
codex 是否已安装
@anthropic-ai/claude-agent-sdk 是否可解析
claude（Claude Code CLI）是否已安装
Claude 的基础认证信号是否存在

如果你愿意让 CLI 自动执行安全修复，可以使用：

npx web-agent-console doctor --fix

当前 --fix 只会自动尝试修复适合脚本化处理的项目，比如安装缺失的 Claude Code CLI。codex 安装和 Claude 登录态仍然会给出人工修复建议。

2. 直接启动

npx web-agent-console

默认会启动 codex provider，并在 http://127.0.0.1:4318 提供 Web 界面。

如果你希望启动后自动打开浏览器：

npx web-agent-console --open

3. 选择后端 provider

使用 codex：

npx web-agent-console --provider codex

使用 claude-sdk：

npx web-agent-console --provider claude-sdk

4. 常用命令

web-agent-console start
web-agent-console --open
web-agent-console --host 0.0.0.0 --port 4533 --password demo-password
web-agent-console --sandbox workspace-write --approval on-request
web-agent-console doctor
web-agent-console doctor --fix
web-agent-console --help

环境变量仍然可用，CLI 参数会覆盖同名环境变量。

5. 在仓库中开发

npm install
npm start

6. 固定端口启动

如果你想用固定端口调试或在局域网内访问，可以使用：

./scripts/start-local-4533.sh --help

示例：

WEB_AGENT_AUTH_PASSWORD=demo-password \
./scripts/start-local-4533.sh --sandbox danger-full-access --approval on-request

这个脚本默认会把 Web 界面暴露在 http://0.0.0.0:4533。

Provider 支持情况

Provider	状态	说明	附件支持
`codex`	可用	当前默认路径，支持会话管理、审批、流式更新和会话设置	仅图片
`claude-sdk`	可用	支持 Claude 会话、审批、提问、会话设置和外部 hook 桥接	图片、文本、PDF
`agentapi`	未完成	当前仅为占位实现，不建议在实际使用中启用	不支持

Runtime Steer 公共协议

除了现有的会话与审批接口，这个项目现在还对上层产品 / UI 暴露一组稳定的 runtime steer 公共协议：

GET /api/providers/capabilities
POST /api/sessions/:sessionId/runs
POST /api/sessions/:sessionId/runs/:runId/steer
POST /api/sessions/:sessionId/runs/:runId/interrupt
GET /api/sessions/:sessionId/events
GET /api/events

这组接口把运行时能力拆成 session、run 和 same-run steer 三层语义：

POST /runs 表示在某个 session 中启动新 run
POST /runs/:runId/steer 表示优先尝试“原地引导当前 run”
如果底层 provider 不能满足 same-run steer，接口仍然可以成功，但会显式返回降级结果，而不是伪装成原地引导

REST 响应和 session-scoped SSE 都会携带可见降级元数据，例如：

requestedMode
actualMode
degraded
degradationReason
requestedRunId
effectiveRunId
runIdentityPreserved

对 codex 来说，这意味着会尽量保留原生 same-run steer 语义。对 claude-sdk 来说，这意味着降级会被明确暴露给 UI，而不是被误报成“仍在原 run 内继续执行”。

常见用法

启用共享密码认证

npx web-agent-console --password demo-password

运行 smoke 检查

npm run smoke

如果你想验证 claude-sdk 路径：

WEB_AGENT_PROVIDER=claude-sdk npm run smoke

接收 Claude hook 事件

如果你希望把独立运行的 Claude Code 进程中的审批、提问和状态同步到这个控制台，可以使用：

export CLAUDE_HOOK_SECRET=change-me
export WEB_AGENT_HOOK_SECRET="$CLAUDE_HOOK_SECRET"
export WEB_AGENT_RELAY_URL="http://127.0.0.1:4318"
node ./scripts/claude-hook-relay.mjs

发布到 npm

如果你要把这个项目作为工具发布，推荐直接发布为 npm CLI 包，而不是改造成纯终端 TUI。当前仓库已经支持 web-agent-console 命令入口，典型发布流程是：

npm test
npm version patch
npm publish --access public

如果你使用组织 scope，再把包名改成 @your-scope/web-agent-console 后发布即可。

注意事项

这是本地优先的 PoC，不是生产级多用户平台。
codex 路径默认使用 danger-full-access sandbox 和 on-request approval policy，如需更严格限制请显式覆盖。
如果你通过 start-local-4533.sh 对外监听 0.0.0.0，建议至少启用 WEB_AGENT_AUTH_PASSWORD，并配合主机防火墙使用。
agentapi 目前不是完整实现。
不同 provider 的附件能力不同，codex 只支持图片，claude-sdk 支持图片、文本和 PDF。

已知限制

还没有完善的多用户、权限、审计和生产级安全模型
状态主要保存在本地 JSON 文件中，而不是数据库
Claude 外部进程与 Web 控制台之间的待处理动作一致性依赖 hook relay 配置是否正确

开源协议

本项目采用 MIT License，这是一个宽松的开源协议，允许你在保留原始版权和协议声明的前提下自由使用、修改、分发和商业化。

开发者文档

如果你要了解项目结构、架构设计、环境变量、状态文件、接口和测试方式，请查看 DESIGN.md。

社区友链

LINUX DO

Name		Name	Last commit message	Last commit date
bin		bin
docs		docs
public		public
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
DESIGN.md		DESIGN.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

Navigation Menu

Repository navigation

About

Repository files navigation

Web Agent Console

移动端截图

主要能力

适合谁

快速开始

这部分会帮你完成什么

开始前准备

1. 先检查本地环境

2. 直接启动

3. 选择后端 provider

4. 常用命令

5. 在仓库中开发

6. 固定端口启动

Provider 支持情况

Runtime Steer 公共协议

常见用法

启用共享密码认证

运行 smoke 检查

接收 Claude hook 事件

发布到 npm

注意事项

已知限制

开源协议

开发者文档

社区友链

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Web Agent Console

移动端截图

主要能力

适合谁

快速开始

这部分会帮你完成什么

开始前准备

1. 先检查本地环境

2. 直接启动

3. 选择后端 provider

4. 常用命令

5. 在仓库中开发

6. 固定端口启动

Provider 支持情况

Runtime Steer 公共协议

常见用法

启用共享密码认证

运行 smoke 检查

接收 Claude hook 事件

发布到 npm

注意事项

已知限制

开源协议

开发者文档

社区友链

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages